doc/guide/src/SMLNJLibrary.adoc

   1 SMLNJLibrary
   2 ============
   3
   4 The http://www.smlnj.org/doc/smlnj-lib/index.html[SML/NJ Library] is a
   5 collection of libraries that are distributed with SML/NJ.  Due to
   6 differences between SML/NJ and MLton, these libraries will not work
   7 out-of-the box with MLton.
   8
   9 As of 20180119, MLton includes a port of the SML/NJ Library
  10 synchronized with SML/NJ version 110.82.
  11
  12 == Usage ==
  13
  14 * You can import a sub-library of the SML/NJ Library into an MLB file with:
  15 +
  16 [options="header"]
  17 |=====
  18 |MLB file|Description
  19 |`$(SML_LIB)/smlnj-lib/Util/smlnj-lib.mlb`|Various utility modules, included collections, simple formating, ...
  20 |`$(SML_LIB)/smlnj-lib/Controls/controls-lib.mlb`|A library for managing control flags in an application.
  21 |`$(SML_LIB)/smlnj-lib/HashCons/hash-cons-lib.mlb`|Support for implementing hash-consed data structures.
  22 |`$(SML_LIB)/smlnj-lib/HTML/html-lib.mlb`|HTML 3.2 parsing and pretty-printing library.
  23 |`$(SML_LIB)/smlnj-lib/HTML4/html4-lib.mlb`|HTML 4.01 parsing and pretty-printing library.
  24 |`$(SML_LIB)/smlnj-lib/INet/inet-lib.mlb`|Networking utilities; supported on both Unix and Windows systems.
  25 |`$(SML_LIB)/smlnj-lib/JSON/json-lib.mlb`|JavaScript Object Notation (JSON) reading and writing library.
  26 |`$(SML_LIB)/smlnj-lib/PP/pp-lib.mlb`|Pretty-printing library.
  27 |`$(SML_LIB)/smlnj-lib/Reactive/reactive-lib.mlb`|Reactive scripting library.
  28 |`$(SML_LIB)/smlnj-lib/RegExp/regexp-lib.mlb`|Regular expression library.
  29 |`$(SML_LIB)/smlnj-lib/SExp/sexp-lib.mlb`|S-expression library.
  30 |`$(SML_LIB)/smlnj-lib/Unix/unix-lib.mlb`|Utilities for Unix-based operating systems.
  31 |`$(SML_LIB)/smlnj-lib/XML/xml-lib.mlb`|XML library.
  32 |=====
  33
  34 * If you are porting a project from SML/NJ's <:CompilationManager:> to
  35 MLton's <:MLBasis: ML Basis system> using `cm2mlb`, note that the
  36 following maps are included by default:
  37 +
  38 -----
  39 # SMLNJ Library
  40 $SMLNJ-LIB                              $(SML_LIB)/smlnj-lib
  41 $smlnj-lib.cm                           $(SML_LIB)/smlnj-lib/Util
  42 $controls-lib.cm                        $(SML_LIB)/smlnj-lib/Controls
  43 $hash-cons-lib.cm                       $(SML_LIB)/smlnj-lib/HashCons
  44 $html-lib.cm                            $(SML_LIB)/smlnj-lib/HTML
  45 $html4-lib.cm                           $(SML_LIB)/smlnj-lib/HTML4
  46 $inet-lib.cm                            $(SML_LIB)/smlnj-lib/INet
  47 $json-lib.cm                            $(SML_LIB)/smlnj-lib/JSON
  48 $pp-lib.cm                              $(SML_LIB)/smlnj-lib/PP
  49 $reactive-lib.cm                        $(SML_LIB)/smlnj-lib/Reactive
  50 $regexp-lib.cm                          $(SML_LIB)/smlnj-lib/RegExp
  51 $sexp-lib.cm                            $(SML_LIB)/smlnj-lib/SExp
  52 $unix-lib.cm                            $(SML_LIB)/smlnj-lib/Unix
  53 $xml-lib.cm                             $(SML_LIB)/smlnj-lib/XML
  54 ----
  55 +
  56 This will automatically convert a `$/smlnj-lib.cm` import in an input
  57 `.cm` file into a `$(SML_LIB)/smlnj-lib/Util/smlnj-lib.mlb` import in
  58 the output `.mlb` file.
  59
  60 == Details ==
  61
  62 The following changes were made to the SML/NJ Library, in addition to
  63 deriving the `.mlb` files from the `.cm` files:
  64
  65 * `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.
  66 * `Util/base64.sml` (modified): Rewrote use of `Unsafe.CharVector.create` and `Unsafe.CharVector.update`; MLton assumes that vectors are immutable.
  67 * `Util/engine.mlton.sml` (added, not exported): Implements `structure Engine`, providing time-limited, resumable computations using <:MLtonThread:>, <:MLtonSignal:>, and <:MLtonItimer:>.
  68 * `Util/graph-scc-fn.sml` (modified): Rewrote use of `where` structure specification.
  69 * `Util/redblack-map-fn.sml` (modified): Rewrote use of `where` structure specification.
  70 * `Util/redblack-set-fn.sml` (modified): Rewrote use of `where` structure specification.
  71 * `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`.
  72 * `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.
  73
  74 == Patch ==
  75
  76 * <!ViewGitFile(mlton,master,lib/smlnj-lib/smlnj-lib.patch)>