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 20130706, MLton includes a port of the SML/NJ Library
synchronized with SML/NJ version 110.76.

== 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.
|=====

* 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
----
+
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:

* `HTML/html-attrs-fn.sml` (modified): Rewrote use of or-patterns.
* `HTML/html-elements-fn.sml` (modified): Rewrote use of or-patterns.
* `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.
* `Util/base64.sml` (modified): Rewrote use of `Unsafe.CharVector.create` and `Unsafe.CharVector.update`; MLton assumes that vectors are immutable.
* `Util/bit-array.sml` (modified): The computation of the `maxLen` is given by:
+
[source,sml]
----
val maxLen = 8*Word8Array.maxLen
----
+
This is fine in SML/NJ where `Word8Array.maxLen` is 16777215, but in MLton, `Word8Array.maxLen` is equal to `valOf(Int.maxInt)`, so the computation overflows. To accommodate both SML/NJ and MLton, the computation is replaced by
+
[source,sml]
----
val maxLen = (8*Word8Array.maxLen) handle Overflow => Word8Array.maxLen
----

* `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/redblack-map-fn.sml` (modified): Rewrote use of `where` structure specification.
* `Util/redblack-set-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.

== Patch ==

* <!ViewGitFile(mlton,master,lib/smlnj-lib/smlnj-lib.patch)>
