## MLton 20241230

# SMLNJLibrary

The SML/NJ Library is a collection of libraries that are distributed with SML/NJ. Due to differences between SML/NJ and MLton, these libraries will not work out-of-the box with MLton.

As of 20241214, MLton includes a port of the SML/NJ Library synchronized with SML/NJ version 110.99.6.1.

## Usage

- You can import a sub-library of the SML/NJ Library into an MLB file with:

  MLB file | Description
  --- | ---
  `$(SML_LIB)/smlnj-lib/Util/smlnj-lib.mlb` | Various utility modules, included collections, simple formating, …​
  `$(SML_LIB)/smlnj-lib/Controls/controls-lib.mlb` | A library for managing control flags in an application.
  `$(SML_LIB)/smlnj-lib/HashCons/hash-cons-lib.mlb` | Support for implementing hash-consed data structures.
  `$(SML_LIB)/smlnj-lib/HTML/html-lib.mlb` | HTML 3.2 parsing and pretty-printing library.
  `$(SML_LIB)/smlnj-lib/HTML4/html4-lib.mlb` | HTML 4.01 parsing and pretty-printing library.
  `$(SML_LIB)/smlnj-lib/INet/inet-lib.mlb` | Networking utilities; supported on both Unix and Windows systems.
  `$(SML_LIB)/smlnj-lib/JSON/json-lib.mlb` | JavaScript Object Notation (JSON) reading and writing library.
  `$(SML_LIB)/smlnj-lib/PP/pp-lib.mlb` | Pretty-printing library.
  `$(SML_LIB)/smlnj-lib/Reactive/reactive-lib.mlb` | Reactive scripting library.
  `$(SML_LIB)/smlnj-lib/RegExp/regexp-lib.mlb` | Regular expression library.
  `$(SML_LIB)/smlnj-lib/SExp/sexp-lib.mlb` | S-expression library.
  `$(SML_LIB)/smlnj-lib/Unix/unix-lib.mlb` | Utilities for Unix-based operating systems.
  `$(SML_LIB)/smlnj-lib/UUID/uuid-lib.mlb` | UUID generating library.
  `$(SML_LIB)/smlnj-lib/XML/xml-lib.mlb` | XML library.

- If you are porting a project from SML/NJ’s CompilationManager to MLton’s ML Basis system using `cm2mlb`, note that the following maps are included by default:

      # SMLNJ Library
      $SMLNJ-LIB                              $(SML_LIB)/smlnj-lib
      $smlnj-lib.cm                           $(SML_LIB)/smlnj-lib/Util
      $controls-lib.cm                        $(SML_LIB)/smlnj-lib/Controls
      $hash-cons-lib.cm                       $(SML_LIB)/smlnj-lib/HashCons
      $html-lib.cm                            $(SML_LIB)/smlnj-lib/HTML
      $html4-lib.cm                           $(SML_LIB)/smlnj-lib/HTML4
      $inet-lib.cm                            $(SML_LIB)/smlnj-lib/INet
      $json-lib.cm                            $(SML_LIB)/smlnj-lib/JSON
      $pp-lib.cm                              $(SML_LIB)/smlnj-lib/PP
      $reactive-lib.cm                        $(SML_LIB)/smlnj-lib/Reactive
      $regexp-lib.cm                          $(SML_LIB)/smlnj-lib/RegExp
      $sexp-lib.cm                            $(SML_LIB)/smlnj-lib/SExp
      $unix-lib.cm                            $(SML_LIB)/smlnj-lib/Unix
      $xml-lib.cm                             $(SML_LIB)/smlnj-lib/XML

  This will automatically convert a `$/smlnj-lib.cm` import in an input `.cm` file into a `$(SML_LIB)/smlnj-lib/Util/smlnj-lib.mlb` import in the output `.mlb` file.

## Details

The following changes were made to the SML/NJ Library, in addition to deriving the `.mlb` files from the `.cm` files:

- `Compat/either` (added): Implements `signature EITHER` and `structure Either: EITHER` (see https://github.com/SMLFamily/BasisLibrary/wiki/2015-002-Addition-of-Either-module); used by RegExp Library.

- `Compat/fn` (added): Implements `signature FN` and `structure Fn: FN` (see https://github.com/SMLFamily/BasisLibrary/wiki/2015-005-Addition-of-Fn-module); used by JSON Library.

- `Compat/mono-buffer` (added): Implements `signature MONO_BUFFER` and `structure CharBuffer: MONO_BUFFER` (see https://github.com/SMLFamily/BasisLibrary/wiki/2018-001-Addition-of-monomorphic-buffers); used by JSON and PP Libraries.

- `Compat/mono-sequence` (added): Implements `signature MONO_{ARRAY,VECTOR}{,_SLICE}_EXT` and `structure Word8Slice: MONO_VECTOR_SLICE_EXT` (see https://github.com/SMLFamily/BasisLibrary/wiki/2015-003-Additional-operations-on-sequences and https://github.com/SMLFamily/BasisLibrary/wiki/2018-001-Addition-of-monomorphic-buffers); used by SML/NJ Library.

- `HTML4/pp-init.sml` (added): Implements `structure PrettyPrint` using the SML/NJ PP Library. This implementation is taken from the SML/NJ compiler source, since the SML/NJ HTML4 Library used the `structure PrettyPrint` provided by the SML/NJ compiler itself.

- `JSON/json-stream-parser.sml` and `JSON/json-parser.sml` (modified): Rewrote use of `Unsafe.CharVector.create` and `Unsafe.CharVector.update`; MLton assumes that vectors are immutable.

- `Util/base64.sml` (modified): Rewrote use of `Unsafe.CharVector.create` and `Unsafe.CharVector.update`; MLton assumes that vectors are immutable.

- `Util/dynamic-array.sml` (modified): Rewrote use of `Array.fromVector`.

- `Util/engine.mlton.sml` (added, not exported): Implements `structure Engine`, providing time-limited, resumable computations using <:MLtonThread:>, <:MLtonSignal:>, and <:MLtonItimer:>.

- `Util/graph-scc-fn.sml` (modified): Rewrote use of `where` structure specification.

- `Util/time-limit.mlb` (added): Exports `structure TimeLimit`, which is not exported by `smlnj-lib.mlb`. Since MLton is very conservative in the presence of threads and signals, program performance may be adversely affected by unnecessarily including `structure TimeLimit`.

- `Util/time-limit.mlton.sml` (added): Implements `structure TimeLimit` using `structure Engine`. The SML/NJ implementation of `structure TimeLimit` uses SML/NJ’s first-class continuations, signals, and interval timer.

- `Util/utf8.sml` (modified): Rewrote use of `String.implodeRev` (see https://github.com/SMLFamily/BasisLibrary/wiki/2015-003d-STRING).

## Patch

- `smlnj-lib.patch`