The Standard ML Basis Library

Introduction

This document is a proposal for a Standard ML Basis Library. This library provides a rich 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 used in the design of the Library, and present a high-level view of the library structure.

Design principles

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 was 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 interactively 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 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.

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 have divided the modules into required and optional modules. Any conforming implementation of SML Standard Library will provide implementations of all of the required modules. In addition, if an implementation provides any of the services covered by the optional modules, then they shall conform to the given interfaces.

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

O

Are any of the structure's members available in the initial top-level environment?

M

Does the structure require special compiler or run-time system support?

We specify certain relationships among the modules.

• If IntInf is provided, then LargeInt.int must be the same as IntInf.int.
• 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.

Miscellaneous structures

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

Conforming implementations must provide modules that exactly match the signatures defined in the SML Standard Library. For example, the Int structure provided by an implementation should not match a superset of the INTEGER signature. Additional structures should be provided for extensions to the basis, other libraries, or access to implementation-specific information.

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. We hope users will accept the conventions and concentrate on the issues of semantics.

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 should be 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.

Miscellany

Functional arguments that are evaluated solely for their side-effects should be required to 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 January 21, 1997
Copyright © 1996 AT&T