The Standard ML Basis Library

Introduction

This document describes the Standard ML Basis Library. This library provides an extensive initial basis for Standard ML, which complements the language described by the Definition of Standard ML. The goals of the Basis Library are to:

• serve as the basic toolkit for the SML programmer, whether novice or professional.
• replace the many incompatible general-purpose libraries currently available.
• focus attention on the attractiveness of SML as a language for programming in a wide variety of domains, e.g,. systems programming.

In this chapter, we discuss the principles and conventions used in the design of the Library, and present a high-level view of the library structure.

By design, the Basis Library is meant to provide a fairly rich collection of general-purpose modules that can serve as the basis for applications programming or for more domain-specific libraries. One criterion for inclusion in the Basis Library is that a type or value requires compiler or run-time system support. In addition, the Library defines a standard minimal environment that anyone using SML can expect to find. The Library also attempts to provide similar functions in similar contexts. Thus, the traditional app function for lists, which applies a function to each member of a list, has also been provided for arrays and vectors.

An opposite design force has been the desire to keep the basis library small. In general, a function has been included only if it has clear or proven utility, with additional emphasis on those that are complicated to implement, require compiler support, or are more concise or efficient than an equivalent combination of other functions. Some exceptions were made for historical reasons.

Library modules

The Basis Library is contained in a set of structures. Almost every type, exception constructor and value belongs to some structure. Although some identifiers are also bound in the initial top-level environment we have attempted to keep the number of top-level identifiers small. Infix declarations and overloading are specified for the top-level environment.

We view the signature and structure names used below as being reserved. For an implementation to be conforming, any module it provides that is named in the SML Basis Library must exactly match the description specified in the library. For example, the Int structure provided by an implementation should not match a superset of the INTEGER signature. If an implementation provides any types, values or modules not described in the SML Basis Library, they must be encapsulated in additional structures whose names are not used by the SML Basis Library. In particular, an implementation must not introduce any new non-module identifiers into the top-level environment.

Required modules

We have divided the modules into required and optional categories. Any conforming implementation of SML Basis Library must provide implementations of all of the required modules.

Many of the structures are variations on some generic module (e.g., single and double-precision floating-point numbers). The following table gives a list of the required generic signatures.

Optional modules

The library specifies a large collection of signatures and structures that are considered optional in a conforming implementation. They provide features that, although useful, are not considered fundamental to a workable SML implementation. These modules include additional representations of integers, words, characters and reals; more efficient array and vector representations; and a subsystem providing Posix compatability.

Although an implementation may or may not provide one of these modules, if it provides one, the module must exactly match the specification given in this document. The names specified here for optional signatures and structures must be used at top-level only to denote implementations of the specified library module. On the other hand, if an implementation offers features related to an optional module, it should also provide the optional module.

The library specifies the following optional signatures.

Module dependencies

We specify certain relationships among the modules.

• If IntInf is provided, then LargeInt must be a thinned version of IntInf. Otherwise, if LargeInt is not the same as Int, then there must be a structure Int{N} equal to LargeInt.
• If LargeWord is not the same as Word, then there must be a structure Word{N} equal to LargeWord.
• If LargeReal is not the same as Real, then there must be a structure Real{N} equal to LargeReal.
• The signatures MULTIBYTE and LOCALE, and the structures Locale, WideChar, WideString, WideSubstring, WideCharVector, WideCharArray and WideTextIO are optional as a group.
• The Posix structures and signatures plus SysWord are optional as a group.

Backward compatability

To permit users to compile programs written under the old basis, we require that each implementation provide the structure SML90. This structure contains the top-level bindings specified in the 1990 version of the [CITE]Definition/, along with one or more substructures that define the top-level bindings of various implementations. For example, a user might write:

local
  open SML90 SML90.SMLNJ
in
  (* user's program *)
end

We expect that at some future point, the SML90 module will be deemed obsolete, and will be dropped from the standard basis.

Design rules and conventions

In designing the library, we have tried to follow a set of stylistic rules to make library usage consistent and predictable, and to preclude certain errors. These rules are not meant to be prescriptive for the programmer using or extending the library. On the other hand, although the library itself thwarts the conventions on occasion, we feel the rules are reasonable and helpful, and would encourage their use.

Orthographic conventions

We use a new set of spelling and capitalization conventions. Some of these conventions, e.g., the capitalization of value constructors, seem to be widely accepted in the user community. Other decisions were based less on dominant style or compelling reason than on compromise and the need for consistency and some sense of good taste.

The conventions we use are:

• Alphanumeric value variables are in mixed-case, with a leading lower-case letter; e.g., map, openIn.
• Type identifiers are all lower case, with words separated by underscores; e.g., word, file_desc.
• Signature identifiers are in all capitals, with words separated by underscore; e.g., PACK_WORD, OS_PATH. We refer to this as the signature convention.
• Structure and functor identifiers are in mixed-case, with initial letters of words capitalized; e.g., General, WideChar. We refer to this as the structure convention.
• Alphanumeric datatype constructors use the signature convention; e.g., SOME, A_READ, FOLLOW_ALL. In certain cases, where external usage or aesthetics dictates otherwise, the structure convention is followed; e.g., Jan, Mon. Within the basis library, the only use of the latter convention occurs with the months and weekdays in Date. The only exceptions to these rules are the identifiers nil, true and false, where we bow to tradition.
• Exception identifiers use the structure convention; e.g., Domain, TerminatedStream.

Naming

Similar values should have similar names, with similar type shapes, following the conventions outlined above. For example, the function Array.app has the type:

    val app : ('a -> unit) -> 'a array -> unit

Comparisons

Many structures define a type ty along with a comparison function

    val compare : ty * ty -> order

Types that have a standard or obvious linear order come with the full set of relational operators plus a compare function. Certain abstract types, e.g., OS.FileSys.file_id, provide a compare function for use with, for example, ordered binary trees.

Conversions

Most structures defining a type provide conversion functions to and from other types. When unambiguous, we use the naming convention toT and fromT, where T is some version of the name of the other type. For example, in WORD, we have

    val fromInt : Int.int -> word
    val toInt : word -> Int.int

    val uidToWord : uid -> SysWord.word
    val gidToWord : gid -> SysWord.word

There should be conversions to and from strings for most types. Following the convention above, these functions are typically called toString and fromString. Usually, modules provide additional string conversion functions that allow more control over format and operate on an abstract character stream. These functions are called fmt and scan. The input accepted by fromString and scan consists of printable ASCII characters. The output generated by toString and fmt consists of printable ASCII characters.

We adopt the convention that conversions from strings should be forgiving, allowing initial white space and multiple formats, and ignoring additional terminating characters. On the other hand, we have tried to specify conversions to strings precisely. In addition, for basic types, scanning functions should accept legal SML literals, and formatting functions should, whenever possible, produce the value part of a valid SML literal but, for flexibility, may omit certain annotations. For example, String.toString produces a valid SML string constant, but without the enclosing quotes, and Word.toString produces a word constant without the "0wx" prefix.

Characters and strings

The old basis did not provide a character type, only a string type. To manipulate characters, programmers used integers corresponding to the character's code. This was unsatisfactory for several reasons:

• No symbolic names for pattern matching single characters
• Character to string conversions require unnecessary range checks
• There is no provision for the extended character sets necessary for international use.

The revised SML Definition introduces a new char type and literal syntax along with old string type. The SML Standard Basis provides support for both string and char types, where the string type is a vector of characters. In addition, we define the optional types WideString.string and WideChar.char, in which the former is again a vector of the latter, for handling character sets more extensive than Latin-1.

Miscellany

Functional arguments that are evaluated solely for their side-effects should have a return type of unit. For example, the list application function should have the type:

   val app : ('a -> unit) -> 'a list -> unit

Last Modified August 5, 1997
Comments to John Reppy.
Copyright © 1997 Bell Labs, Lucent Technologies