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.

We note in passing that the special identifiers = and <>, corresponding to polymorphic equality and inequality, are available in the top-level environment but are not bound in any module.

The following table presents the top-level types and their defining structures, if any.

eqtype unit General
eqtype int Int
eqtype word Word
type 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

Although the types bool and list are considered primitive and defined in the top-level environment, for convenience they also bound in the structures Bool and List, respectively.

The next list presents the exceptions and exception constructors available at top-level. All of the exceptions are defined in General, except for Option, which is defined in Option and Empty, which is defined in List.

exception Bind
exception Chr
exception Div
exception Domain
exception Empty
exception Fail of string
exception Match
exception Option
exception Overflow
exception Size
exception Span
exception Subscript

The next table presents the non-overloaded functions available at top-level, plus the structure value to which each is bound. Note that the use function 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.

val ! : 'a ref -> 'a General.!
val := : 'a ref * 'a -> unit General.:=
val ref : 'a -> 'a ref primitive
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 and default types, are given below

val + : num * num -> num int * int -> int
val - : num * num -> num int * int -> int
val * : num * num -> num int * int -> int
val div : wordint * wordint -> wordint int * int -> int
val mod : wordint * wordint -> wordint int * int -> int
val / : real * real -> real real * real -> real
val ~ : realint -> realint int -> int
val abs : realint -> realint int -> int
val < : numtext * numtext -> bool int * int -> bool
val > : numtext * numtext -> bool int * int -> bool
val <= : numtext * numtext -> bool int * int -> bool
val >= : numtext * numtext -> bool int * int -> bool
where 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.

Appendix C provides additional information on how overload resolution is performed on these identifiers, particularly in the context of overloaded literals.

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 ]

Last Modified October 4, 1997
Comments to John Reppy.
Copyright © 1997 Bell Labs, Lucent Technologies