The Standard ML Basis Library

Top-level environment

This chapter describes the standard initial top-level environment, that is, those identifiers available unqualified before the user introduces additional top-level bindings. As special aspects of this environment, infix identifiers and overloading are also discussed.

Modules in the top-level environment

There are no default requirements on which modules will be intially available at top-level for either interactive or batch-oriented sessions. Each implementation may provide its own mechanism for making its various modules available to the user's code. Even the presence of a top-level identifier that is logically defined in a structure (e.g., the type int is defined in the Int structure) is no guarantee that the structure name is in the environment.

Top-level type, exception and value identifiers

Various types, exceptions and values are available unqualified in the top-level environment. In particular, everything in General is thus available.

[TABLE] presents the top-level types and their defining structures.

**Top-level types and defining structures**
`eqtype unit`	`General`
`eqtype int`	`Int`
`eqtype word`	`Word`
`eqtype real`	`Real`
`eqtype char`	`Char`
`eqtype string`	`String`
`type substring`	`Substring`
`type exn`	`General`
`eqtype 'a array`	`Array`
`eqtype 'a vector`	`Vector`
`eqtype 'a ref`	`General`
`datatype bool = false \| true`	primitive
`datatype 'a option = NONE \| SOME of 'a`	`Option`
`datatype order = LESS \| EQUAL \| GREATER`	`General`
`datatype 'a list = nil \| :: of ('a * 'a list)`	primitive

[TABLE] presents the exceptions and exception constructors available at top-level. All of the exceptions are defined in General, except for Empty, which is defined in List.

**Top-level exceptions**
`exception Bind`
`exception Chr`
`exception Div`
`exception Domain`
`exception Empty`
`exception Fail of string`
`exception Match`
`exception Option`
`exception Overflow`
`exception Size`
`exception Subscript`

[TABLE] presents the non-overloaded functions available at top-level, plus the structure value to which each is bound. Note that the usefunction is special. Although not defined precisely, its intended purpose is to take the pathname of a file and treat the contents of the file as SML source code typed in by the user. It can be used as a simple build mechanism, especially for interactive sessions. Most implementations will provide a more sophisticated build mechanism for larger collections of source files.

**Non-overloaded, top-level functions**
`val ! : 'a ref -> 'a`	`General.!`
`val := : 'a ref * 'a -> unit`	`General.:=`
`val ref : 'a -> 'a ref`	`General.ref`
`val before : 'a * unit -> 'a`	`General.before`
`val ignore : 'a -> unit`	`General.ignore`
`val o : ('a -> 'b) * ('c -> 'a) -> 'c -> 'b`	`General.o`
`val exnName : exn -> string`	`General.exnName`
`val exnMessage : exn -> string`	`General.exnMessage`
`val getOpt : ('a option * 'a) -> 'a`	`Option.getOpt`
`val isSome : 'a option -> bool`	`Option.isSome`
`val valOf : 'a option -> 'a`	`Option.valOf`
`val not : bool -> bool`	`Bool.not`
`val real : int -> real`	`Real.fromInt`
`val trunc : real -> int`	`Real.trunc`
`val floor : real -> int`	`Real.floor`
`val ceil : real -> int`	`Real.ceil`
`val round : real -> int`	`Real.round`
`val ord : char -> int`	`Char.ord`
`val chr : int -> char`	`Char.chr`
`val size : string -> int`	`String.size`
`val str : char -> string`	`String.str`
`val concat : string list -> string`	`String.concat`
`val implode : char list -> string`	`String.implode`
`val explode : string -> char list`	`String.explode`
`val substring : string * int * int -> string`	`String.substring`
`val ^ : string * string -> string`	`String.^`
`val null : 'a list -> bool`	`List.null`
`val hd : 'a list -> 'a`	`List.hd`
`val tl : 'a list -> 'a list`	`List.tl`
`val length : 'a list -> int`	`List.length`
`val rev : 'a list -> 'a list`	`List.rev`
`val @ : ('a list * 'a list) -> 'a list`	`List.@`
`val app : ('a -> unit) -> 'a list -> unit`	`List.app`
`val map : ('a -> 'b) -> 'a list -> 'b list`	`List.map`
`val foldr : ('a * 'b -> 'b) -> 'b -> 'a list -> 'b`	`List.foldr`
`val foldl : ('a * 'b -> 'b) -> 'b -> 'a list -> 'b`	`List.foldl`
`val print : string -> unit`	`TextIO.print`
`val vector : 'a list -> 'a vector`	`Vector.fromList`
`val use : string -> unit`	primitive

Although the benefits and costs of allowing user-defined overloading are the source of some debate, the design of SML prohibits this feature. However, it would be unacceptable to most programmers not to provide overloading on certain basic arithmetic and relational operators and functions. The nature of overloading requires these identifiers to be available in the top-level environment. These identifiers, with their type schemas, are given in [TABLE], where

int := {Int.int, IntN.int, IntInf.int}
word := {Word.word, Word8.word, WordN.word}
real := {Real.real, RealN.real}
text := {String.string, Char.char, WideString.string, WideChar.char}
wordint := word union int
realint := real union int
num := word union int union real
numtext := num union text

Note that the same type must be chosen throughout the entire type of an overloaded operator. For example, the function abs cannot have type int -> real, but only a type like int -> int. In addition, we note that IntN.int, IntInf.int, WordN.word, RealN.real, WideString.string and WideChar.char are optional types.

**Overloaded, top-level identifiers**
`val + : num * num -> num`
`val - : num * num -> num`
`val * : num * num -> num`
`val div : wordint * wordint -> wordint`
`val mod : wordint * wordint -> wordint`
`val / : real * real -> real`
`val ~ : realint -> realint`
`val abs : realint -> realint`
`val < : numtext * numtext -> bool`
`val > : numtext * numtext -> bool`
`val <= : numtext * numtext -> bool`
`val >= : numtext * numtext -> bool`

Infix identifiers

The top-level environment has the following infix identifiers:

infix  7  * / div mod
infix  6  + - ^
infixr 5  :: @
infix  4  = <> > >= < <=
infix  3  := o
infix  0  before

[ INDEX | TOP | Parent | Root ]