= SMLNJLibrary

The http://www.smlnj.org/doc/smlnj-lib/index.html[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 20250523, MLton includes a port of the SML/NJ Library
synchronized with SML/NJ version 110.99.8.

== Usage

* You can import a sub-library of the SML/NJ Library into an MLB file with:
+
[options="header"]
|===
|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 <<MLBasis#,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

* https://github.com/MLton/mlton/blob/master/lib/smlnj-lib/smlnj-lib.patch[`smlnj-lib.patch`]
