1 Introduction

The IvoryScript Module Reference provides a comprehensive list of the types, classes, instances and global names defined within each module of the language.

The reference is organized by module. Each module entry includes sections on:

• Types: Definitions of primitive and user-defined types, including their constructors and associated usage.

• Classes: Declarations of type classes, detailing constraints and behaviours - along with the class methods and their associated types.

• Instances: Implementations of type classes for specific types.

• Global names: Names in the value namespace associated with constants, variables, functions, class methods and data constructors.

2 Primitive & Built-in

The Primitive and Built-in layer is the lowest visible layer of the IvoryScript runtime. Primitive operations are supplied directly by the compiler or virtual machine and carry no IvoryScript definition. Built-in functions are implemented in C++ using the defineBuiltInFn macro family and registered as first-class curried IvoryScript values; they participate in partial application, serialisation, and garbage collection in exactly the same way as user-defined functions. Neither primitives nor built-in functions require an explicit module import.

2.1 Type Definitions

Name	Category	Literal / Constructor	Description
Void	Primitive	Void	The unit type. Used as the return type of actions that produce no value. The single constructor is the built-in value Void.
Name	Primitive	'identifier	An interned symbol. Name literals are written with a leading single-quote: 'counter, 'x. Two names with the same spelling are always pointer-equal.
Type	Primitive	type expression	A runtime type descriptor. Produced by typeOf and used by the persistence and reflection machinery.
Int	Primitive	0, 42, -7…	Machine-word signed integer. Arithmetic operations are supplied as built-in functions and exposed via the Num Int instance in the Prelude.
Float	Primitive	function return	IEEE 754 single-precision floating-point. No literal syntax; values are produced by conversion functions such as fromIntFloat.
Double	Primitive	3.14, 0.0…	IEEE 754 double-precision floating-point. Floating-point literals are Double by default.
Char	Primitive	'a', 'Z', '\n'…	A single Unicode code point. Character literals use single quotes with standard C-style escape sequences.
String	Primitive	"hello"…	A mutable heap-allocated character array. Strings are environment-dependent; needsEnv returns True.
Byte	Primitive	function return	An unsigned 8-bit integer. Used as the element type of byte streams and byte strings.
Bits32	Primitive	function return	An unsigned 32-bit word. Provides bitwise operations via the Bitwise Bits32 instance.
ByteString	Primitive	function return	A heap-allocated sequence of bytes. Used for binary I/O and byte-level manipulation.
Exp a	Primitive	#!expr	A lazy (unevaluated) expression of type a. Reduction is forced by the #! operator or by reduce.
Ref	Primitive	runtime value	An opaque reference to a live runtime object. Used by the Ivory System event and interpreter infrastructure.
UTC	Primitive	function return	A UTC timestamp. Produced by time and compared with timeDiff.
When	Primitive	runtime value	A time interval or scheduling descriptor used by the Ivory System event model.
Dir	Primitive	function return	An open directory stream handle. Produced by openDir and consumed by nextDirEntry and closeDir.
DirEntry	Primitive	function return	A single entry from a directory listing. The name is extracted with dirEntryName.

2.2 Global Names

Name	Category	Type Signature	Description	Example
addInt	Primitive	Int -> Int -> Int	Addition. Used by the Num Int instance as (+).	addInt 4 7 → 11
subInt	Primitive	Int -> Int -> Int	Subtraction. Used by Num Int as (-).	subInt 10 3 → 7
mulInt	Primitive	Int -> Int -> Int	Multiplication. Used by Num Int as (*).	mulInt 3 5 → 15
divInt	Primitive	Int -> Int -> Int	Integer division (truncates towards zero). Also available as div.	divInt 7 2 → 3
modInt	Primitive	Int -> Int -> Int	Integer modulus. Used by Num Int as (mod).	modInt 7 3 → 1
negInt	Primitive	Int -> Int	Arithmetic negation. Used by Num Int as negate.	negInt 5 → -5
eqInt	Primitive	Int -> Int -> Bool	Equality.	eqInt 5 5 → True
nEqInt	Primitive	Int -> Int -> Bool	Inequality.	nEqInt 3 4 → True
ltInt	Primitive	Int -> Int -> Bool	Less-than.	ltInt 3 5 → True
ltEqInt	Primitive	Int -> Int -> Bool	Less-than-or-equal.	ltEqInt 5 5 → True
gtInt	Primitive	Int -> Int -> Bool	Greater-than.	gtInt 7 3 → True
gtEqInt	Primitive	Int -> Int -> Bool	Greater-than-or-equal.	gtEqInt 5 5 → True
compareInt	Primitive	Int -> Int -> Ordering	Three-way comparison returning LT, EQ, or GT.	compareInt 7 3 → GT
fromIntByte	Primitive	Int -> Byte	Converts an Int to a Byte (low 8 bits).	fromIntByte 65 → byte value 65.
fromStringInt	Primitive	String -> Int	Parses a decimal string as an Int.	fromStringInt "42" → 42
fetchInt	Built-in	-> Int	A shared zero-argument thunk yielding a default Int value. Used internally by the Fetch Int instance.	fetchInt
randomInt	Built-in	-> Int	Returns a pseudo-random Int. The generator must first be seeded with seedRandomInt.	randomInt
seedRandomInt	Built-in	Int -> Void	Seeds the pseudo-random integer generator.	seedRandomInt 12345
formatInt	Built-in	Int -> String -> String	Formats an Int using a C-style format string (e.g. "%d", "%08x").	formatInt 255 "%08x" → "000000ff"
showInt	Built-in	Int -> Void	Prints an Int to standard output.	showInt 42
extractInt	Built-in	InputStream Byte -> Int	Deserialises an Int from a byte stream.	extractInt is
insertInt	Built-in	OutputStream Byte -> Int -> Void	Serialises an Int to a byte stream.	insertInt os 42
addFloat	Primitive	Float -> Float -> Float	Addition. Used by Num Float as (+).	addFloat 1.5 2.5 → 4.0
subFloat	Primitive	Float -> Float -> Float	Subtraction.	subFloat 5.0 2.0 → 3.0
mulFloat	Primitive	Float -> Float -> Float	Multiplication.	mulFloat 2.0 3.0 → 6.0
divFloat	Primitive	Float -> Float -> Float	Division. Used by FractionalNum Float as (/).	divFloat 6.0 2.0 → 3.0
negFloat	Primitive	Float -> Float	Negation.	negFloat 3.5 → -3.5
eqFloat	Primitive	Float -> Float -> Bool	Equality.	eqFloat 1.0 1.0 → True
nEqFloat	Primitive	Float -> Float -> Bool	Inequality.	nEqFloat 1.0 2.0 → True
ltFloat	Primitive	Float -> Float -> Bool	Less-than.	ltFloat 1.0 2.0 → True
ltEqFloat	Primitive	Float -> Float -> Bool	Less-than-or-equal.	ltEqFloat 2.0 2.0 → True
gtFloat	Primitive	Float -> Float -> Bool	Greater-than.	gtFloat 3.0 1.0 → True
gtEqFloat	Primitive	Float -> Float -> Bool	Greater-than-or-equal.	gtEqFloat 2.0 2.0 → True
compareFloat	Primitive	Float -> Float -> Ordering	Three-way comparison.	compareFloat 2.5 2.5 → EQ
fromIntFloat	Primitive	Int -> Float	Converts an Int to a Float.	fromIntFloat 3
fromDoubleFloat	Primitive	Double -> Float	Converts a Double to a Float.	fromDoubleFloat 3.14
fromStringFloat	Primitive	String -> Float	Parses a string as a Float.	fromStringFloat "3.14"
formatFloat	Built-in	Float -> String -> String	Formats a Float using a C-style format string.	formatFloat 3.5 "%.2f"
showFloat	Built-in	Float -> Void	Prints a Float to standard output.	showFloat 3.5
extractFloat	Built-in	InputStream Byte -> Float	Deserialises a Float from a byte stream.	extractFloat is
insertFloat	Built-in	OutputStream Byte -> Float -> Void	Serialises a Float to a byte stream.	insertFloat os 3.5
addDouble	Primitive	Double -> Double -> Double	Addition. Used by Num Double as (+).	addDouble 1.5 2.5 → 4.0
subDouble	Primitive	Double -> Double -> Double	Subtraction.	subDouble 5.0 2.0 → 3.0
mulDouble	Primitive	Double -> Double -> Double	Multiplication.	mulDouble 2.0 3.0 → 6.0
divDouble	Primitive	Double -> Double -> Double	Division. Used by FractionalNum Double as (/).	divDouble 6.0 2.0 → 3.0
negDouble	Primitive	Double -> Double	Negation. Used by Num Double as negate.	negDouble 3.14 → -3.14
eqDouble	Primitive	Double -> Double -> Bool	Equality.	eqDouble 3.0 3.0 → True
nEqDouble	Primitive	Double -> Double -> Bool	Inequality.	nEqDouble 1.0 2.0 → True
ltDouble	Primitive	Double -> Double -> Bool	Less-than.	ltDouble 1.0 2.0 → True
ltEqDouble	Primitive	Double -> Double -> Bool	Less-than-or-equal.	ltEqDouble 2.0 2.0 → True
gtDouble	Primitive	Double -> Double -> Bool	Greater-than.	gtDouble 3.0 1.0 → True
gtEqDouble	Primitive	Double -> Double -> Bool	Greater-than-or-equal.	gtEqDouble 2.0 2.0 → True
compareDouble	Primitive	Double -> Double -> Ordering	Three-way comparison.	compareDouble 3.0 4.0 → LT
fromIntDouble	Primitive	Int -> Double	Converts an Int to a Double.	fromIntDouble 3 → 3.0
fromFloatDouble	Primitive	Float -> Double	Widens a Float to a Double.	fromFloatDouble f
fromStringDouble	Primitive	String -> Double	Parses a string as a Double.	fromStringDouble "3.14"
fetchDouble	Built-in	-> Double	A shared zero-argument thunk yielding a default Double. Used by the Fetch Double instance.	fetchDouble
formatDouble	Built-in	Double -> String -> String	Formats a Double using a C-style format string.	formatDouble 3.14159 "%.2f" → "3.14"
showDouble	Built-in	Double -> Void	Prints a Double to standard output.	showDouble 3.14
extractDouble	Built-in	InputStream Byte -> Double	Deserialises a Double from a byte stream.	extractDouble is
insertDouble	Built-in	OutputStream Byte -> Double -> Void	Serialises a Double to a byte stream.	insertDouble os 3.14
acos	Built-in	Double -> Double	Arc cosine (radians).	acos 1.0 → 0.0
asin	Built-in	Double -> Double	Arc sine (radians).	asin 0.0 → 0.0
atan	Built-in	Double -> Double	Arc tangent (radians).	atan 1.0 → 0.7854
atan2	Built-in	Double -> Double -> Double	Arc tangent of y/x, using the signs of both arguments to determine the quadrant.	atan2 1.0 1.0 → 0.7854
cos	Built-in	Double -> Double	Cosine (radians).	cos 0.0 → 1.0
cosh	Built-in	Double -> Double	Hyperbolic cosine.	cosh 0.0 → 1.0
deg	Built-in	Double -> Double	Converts radians to degrees. Alias: degrees.	deg 3.14159 → 180.0
degrees	Built-in	Double -> Double	Converts radians to degrees. Alias: deg.	degrees 3.14159 → 180.0
exp	Built-in	Double -> Double	Natural exponential (ex).	exp 1.0 → 2.71828
log	Built-in	Double -> Double	Natural logarithm.	log 2.71828 → 1.0
log10	Built-in	Double -> Double	Base-10 logarithm.	log10 100.0 → 2.0
pow	Built-in	Double -> Double -> Double	Exponentiation: pow x y returns xy.	pow 2.0 10.0 → 1024.0
rad	Built-in	Double -> Double	Converts degrees to radians. Alias: radians.	rad 180.0 → 3.14159
radians	Built-in	Double -> Double	Converts degrees to radians. Alias: rad.	radians 180.0 → 3.14159
sin	Built-in	Double -> Double	Sine (radians).	sin 0.0 → 0.0
sinh	Built-in	Double -> Double	Hyperbolic sine.	sinh 0.0 → 0.0
sqrt	Built-in	Double -> Double	Square root.	sqrt 4.0 → 2.0
tan	Built-in	Double -> Double	Tangent (radians).	tan 0.0 → 0.0
tanh	Built-in	Double -> Double	Hyperbolic tangent.	tanh 0.0 → 0.0
eqBool	Primitive	Bool -> Bool -> Bool	Equality.	eqBool True True → True
nEqBool	Primitive	Bool -> Bool -> Bool	Inequality.	nEqBool True False → True
showBool	Built-in	Bool -> Void	Prints a Bool to standard output.	showBool True
extractBool	Built-in	InputStream Byte -> Bool	Deserialises a Bool from a byte stream.	extractBool is
insertBool	Built-in	OutputStream Byte -> Bool -> Void	Serialises a Bool to a byte stream.	insertBool os True
eqChar	Primitive	Char -> Char -> Bool	Equality.	eqChar 'a' 'a' → True
nEqChar	Primitive	Char -> Char -> Bool	Inequality.	nEqChar 'a' 'b' → True
ltChar	Primitive	Char -> Char -> Bool	Less-than.	ltChar 'a' 'z' → True
ltEqChar	Primitive	Char -> Char -> Bool	Less-than-or-equal.	ltEqChar 'a' 'a' → True
gtChar	Primitive	Char -> Char -> Bool	Greater-than.	gtChar 'z' 'a' → True
gtEqChar	Primitive	Char -> Char -> Bool	Greater-than-or-equal.	gtEqChar 'a' 'a' → True
compareChar	Primitive	Char -> Char -> Ordering	Three-way comparison.	compareChar 'a' 'b' → LT
formatChar	Built-in	Char -> String -> String	Formats a Char using a C-style format string (e.g. "%c").	formatChar 'A' "%c" → "A"
showChar	Built-in	Char -> Void	Prints a Char to standard output.	showChar 'A'
extractChar	Built-in	InputStream Byte -> Char	Deserialises a Char from a byte stream.	extractChar is
insertChar	Built-in	OutputStream Byte -> Char -> Void	Serialises a Char to a byte stream.	insertChar os 'A'
eqString	Primitive	String -> String -> Bool	Lexicographic equality.	eqString "foo" "foo" → True
nEqString	Primitive	String -> String -> Bool	Lexicographic inequality.	nEqString "foo" "bar" → True
ltString	Primitive	String -> String -> Bool	Less-than (lexicographic).	ltString "apple" "banana" → True
ltEqString	Primitive	String -> String -> Bool	Less-than-or-equal (lexicographic).	ltEqString "abc" "abc" → True
gtString	Primitive	String -> String -> Bool	Greater-than (lexicographic).	gtString "z" "a" → True
gtEqString	Primitive	String -> String -> Bool	Greater-than-or-equal (lexicographic).	gtEqString "abc" "abc" → True
compareString	Primitive	String -> String -> Ordering	Three-way lexicographic comparison.	compareString "apple" "banana" → LT
lengthString	Built-in	String -> Int	Returns the number of characters in a string.	lengthString "hello" → 5
getAtString	Built-in	String -> Int -> Char	Returns the character at the given zero-based index.	getAtString "hello" 0 → 'h'
putAtString	Built-in	String -> Int -> Char -> Void	Writes a character at the given index in a mutable string.	putAtString s 0 'H'
concatString	Built-in	String -> String -> String	Concatenates two strings. Used by Seq String as (++).	concatString "foo" "bar" → "foobar"
reverseString	Built-in	String -> String	Returns a new string with characters in reverse order.	reverseString "abc" → "cba"
hashString	Built-in	String -> Int	Returns a hash code for the string.	hashString "key"
mutableString	Built-in	Int -> String	Allocates a new mutable string of the given length with uninitialised content.	mutableString 10
substring	Built-in	String -> Int -> Int -> String	Extracts a substring from a start index (inclusive) to an end index (exclusive).	substring "hello" 1 3 → "el"
formatString	Built-in	String -> String -> String	Formats a string value using a C-style format string.	formatString "hello" "%s" → "hello"
showString	Built-in	String -> Void	Prints a string to standard output.	showString "hello"
mapString	Built-in	String -> Env -> String	Remaps a string to the given environment. Used by the Env String instance as mapToEnv.	mapString s env
markString_GC	Built-in	String -> Void	Marks a string's storage for garbage collection. Used by the Mark_GC String instance.	markString_GC s
extractString	Built-in	InputStream Byte -> String	Deserialises a String from a byte stream.	extractString is
insertString	Built-in	OutputStream Byte -> String -> Void	Serialises a String to a byte stream.	insertString os "hello"
lShiftBits32	Primitive	Bits32 -> Bits32 -> Bits32	Left shift. Used by Bitwise Bits32 as (<<).	lShiftBits32 x 2
rShiftBits32	Primitive	Bits32 -> Bits32 -> Bits32	Right shift. Used by Bitwise Bits32 as (>>).	rShiftBits32 x 2
andBits32	Primitive	Bits32 -> Bits32 -> Bits32	Bitwise AND. Used as (#&).	andBits32 x y
xorBits32	Primitive	Bits32 -> Bits32 -> Bits32	Bitwise XOR. Used as (#^).	xorBits32 x y
orBits32	Primitive	Bits32 -> Bits32 -> Bits32	Bitwise OR. Used as (#|).	orBits32 x y
notBits32	Primitive	Bits32 -> Bits32	Bitwise complement. Used as (#¬).	notBits32 x
showBits32	Built-in	Bits32 -> Void	Prints a Bits32 value to standard output.	showBits32 x
bytesToString	Built-in	ByteString -> String	Converts a ByteString to a String.	bytesToString bs
lengthByteString	Built-in	ByteString -> Int	Returns the number of bytes in a ByteString.	lengthByteString bs
getAtByteString	Built-in	ByteString -> Int -> Int	Returns the byte value at the given index as an Int.	getAtByteString bs 0
mapByteString	Built-in	ByteString -> Env -> ByteString	Remaps a ByteString to the given environment.	mapByteString bs env
showByteString	Built-in	ByteString -> Void	Prints a ByteString to standard output.	showByteString bs
eqName	Built-in	Name -> Name -> Bool	Equality. Because names are interned this is pointer equality.	eqName 'x 'x → True
nameString	Built-in	Name -> String	Returns the string spelling of a name.	nameString 'counter → "counter"
hashName	Built-in	Name -> Int	Returns the hash code for a name. Used by hash-table implementations.	hashName 'key
showName	Built-in	Name -> Void	Prints a name to standard output.	showName 'counter
mapName	Built-in	Name -> Env -> Name	Remaps a name to the given environment. Used by the Env Name instance as mapToEnv.	mapName n env
extractName	Built-in	InputStream Byte -> Name	Deserialises a Name from a byte stream.	extractName is
insertName	Built-in	OutputStream Byte -> Name -> Void	Serialises a Name to a byte stream.	insertName os 'key
eqType	Built-in	Type -> Type -> Bool	Equality of type descriptors.	eqType (typeOf 0) (typeOf 0) → True
showType	Built-in	Type -> Void	Prints a type descriptor to standard output.	showType (typeOf 0)
mapType	Primitive	Type -> Env -> Type	Remaps a type descriptor to the given environment. Used by the Env Type instance.	mapType t env
extractType	Built-in	InputStream Byte -> Type	Deserialises a Type descriptor from a byte stream.	extractType is
insertType	Built-in	OutputStream Byte -> Type -> Void	Serialises a Type descriptor to a byte stream.	insertType os t
typeOf	Primitive	a -> Type	Returns the runtime type descriptor of a value.	typeOf 42 → the Type for Int.
objectType	Built-in	Ref -> Type	Returns the type of the object referenced by a Ref.	objectType ref
sizeOf	Primitive	Type -> Int	Returns the storage size in bytes of a type.	sizeOf (typeOf 0)
envOf	Primitive	a -> Env	Returns the environment that owns the storage for the given value.	envOf name
mkEnv	Built-in	Int -> Int -> Int -> Int -> Int -> Int -> Int -> Int -> Env	Allocates a new environment with explicit parameters controlling segment table size, name table size, MSA block size, and related capacities.	mkEnv 64 64 4096 256 256 256 64 64
setEnv	Built-in	Env -> Void	Sets the current construction environment to the given Env. Used internally to redirect heap allocation; the previous environment is restored afterwards.	setEnv env
destroyEnv	Built-in	Env -> Void	Releases all storage owned by the environment. Used by the Disposable Env instance.	destroyEnv env
extractEnv	Built-in	InputStream Byte -> Env	Deserialises an Env from a byte stream. Used internally by TransientDataStore deserialisation.	extractEnv is
insertEnv	Built-in	OutputStream Byte -> Env -> Void	Serialises an Env to a byte stream. Used internally by TransientDataStore serialisation.	insertEnv os env
eqEnv	Primitive	Env -> Env -> Bool	Pointer equality of two environment handles.	eqEnv e1 e2
neqEnv	Primitive	Env -> Env -> Bool	Pointer inequality of two environment handles.	neqEnv e1 e2
showAny	Built-in	Any -> Void	Displays an Any value by dispatching to the type-specific show method via the type descriptor.	showAny anyVal
mapAnyPtr	Built-in	Any -> Env -> Ptr a	Remaps the value stored in an Any to the given environment using its type's mapGenPtr method.	mapAnyPtr anyVal env
markAny_GC	Built-in	Any -> Void	Marks an Any value for garbage collection using its type's markGenPtr method.	markAny_GC anyVal
extractAnyPtr	Built-in	InputStream Byte -> Type -> Ptr a	Deserialises a value of the given type from a byte stream, returning it as a raw pointer. Used internally by Any deserialisation.	extractAnyPtr is t
insertAnyPtr	Built-in	OutputStream Byte -> Any -> Void	Serialises an Any value to a byte stream using its type's insertGenPtr method.	insertAnyPtr os anyVal
eqPtr	Built-in	Ptr a -> Ptr a -> Bool	Pointer address equality.	eqPtr p1 p2
eqPlainPtr	Built-in	Plain (Ptr a) -> Plain (Ptr a) -> Bool	Pointer address equality for plain (unboxed) pointer values.	eqPlainPtr pp1 pp2
castPtr	Primitive	Ptr a -> Ptr b	Reinterprets a pointer as a pointer to a different type. No conversion is performed.	castPtr ptr :: Ptr Byte
fromPlain	Primitive	Plain a -> Env -> a	Extracts a value from a Plain wrapper, remapping it into the given environment.	fromPlain plainVal env
eqRef	Built-in	Ref -> Ref -> Bool	Equality of two Ref values.	eqRef r1 r2
nEqRef	Built-in	Ref -> Ref -> Bool	Inequality of two Ref values.	nEqRef r1 r2
showRef	Built-in	Ref -> Void	Displays a Ref value to standard output.	showRef ref
matchRef	Built-in	Ref -> Ref -> Bool	Tests whether two references match. Used by the Ivory System event dispatch mechanism.	matchRef r1 r2
time	Built-in	-> UTC	Returns the current UTC time as a zero-argument thunk.	time
timeDiff	Built-in	UTC -> UTC -> Int	Returns the difference between two UTC values in milliseconds.	timeDiff t1 t0
showUTC	Built-in	UTC -> Void	Prints a UTC timestamp to standard output.	showUTC time
formatUTC	Built-in	UTC -> String -> String	Formats a UTC timestamp using a strftime-style format string.	formatUTC time "%Y-%m-%d"
showWhen	Built-in	When -> Void	Prints a When value to standard output.	showWhen w
showOrdering	Built-in	Ordering -> Void	Prints an Ordering value (LT, EQ, or GT) to standard output.	showOrdering LT
openDir	Built-in	String -> Maybe Dir	Opens a directory stream for the given path, returning Just Dir on success or Nothing if the path does not exist or is not a directory.	openDir "/tmp"
nextDirEntry	Built-in	Dir -> Maybe DirEntry	Advances the directory stream by one entry, returning Just DirEntry or Nothing at end of stream.	nextDirEntry dir
dirEntryName	Built-in	DirEntry -> String	Returns the file name of a directory entry.	dirEntryName entry
closeDir	Built-in	Dir -> Void	Closes an open directory stream.	closeDir dir
openFile	Built-in	String -> IO_Mode -> FileHandle	Opens a file at the given path with the specified mode, returning a file handle.	openFile "/tmp/data.bin" ReadMode
closeFile	Built-in	FileHandle -> Void	Closes an open file handle.	closeFile fh
readFileByte	Built-in	FileHandle -> Byte	Reads a single byte from an open file handle.	readFileByte fh
writeFileByte	Built-in	FileHandle -> Byte -> Void	Writes a single byte to an open file handle.	writeFileByte fh (fromIntByte 65)
error	Built-in	String -> a	Raises a runtime error with the given message. The polymorphic return type allows use in any context.	error "index out of bounds"
exit	Built-in	Int -> Void	Terminates the process with the given exit code.	exit 0
trace	Built-in	String -> Void	Writes a diagnostic string to the trace output. Active only when tracing is enabled.	trace "reached checkpoint"
delay	Built-in	Int -> Void	Suspends the current thread for the given number of milliseconds.	delay 1000
handleScriptInput	Built-in	Ref -> ByteString -> Int	Passes a raw byte buffer to the interpreter associated with the given Ref object handle. Returns the number of bytes consumed. Used internally by the Ivory System event loop to feed script input into a running interpreter session.	handleScriptInput ref inputBytes

3 Prelude

The Prelude module defines the core types, classes, and functions available in every IvoryScript script without an explicit import. It establishes the environment model that underpins persistence and garbage collection, the standard numeric and comparison hierarchies, and the utility functions used throughout the standard library. Primitive operations declared here are implemented directly by the runtime system and compiler; non-primitive definitions are written in IvoryScript itself.

3.1 Type Definitions

Name	Module	Data Constructors	Description
Env	Prelude	Env Int	An isolated managed memory space. Every heap-allocated value carries a reference to its owning environment. The foundation of the persistence and garbage collection model.
Plain a	Prelude	Plain a	A raw unboxed value of type a, not subject to environment mapping. Used to hold values that must bypass the normal environment-mapping mechanism. fromPlain extracts the value into a target environment.
Ptr a	Prelude	Null, Ptr a	A nullable heap pointer to a value of type a. Used for mutable allocation, array elements, and the internal representation of closures and algebraic data types.
Bool	Prelude	False, True	Boolean truth values.
Array a	Prelude	Array [a]	A fixed-size array of elements of type a, represented internally as a contiguous block of heap storage.
Ordering	Prelude	LT, EQ, GT	The result of a comparison: less than, equal, or greater than.
Maybe a	Prelude	Nothing, Just a	An optional value; either absent (Nothing) or present (Just a).
Uneval a	Prelude	Uneval (Exp a)	Wraps an unevaluated expression of type a. Carries the same environment-mapping behaviour as Exp a.

3.2 Class Definitions

Class	Module	Methods	Description
Env a	Prelude	needsEnv, mapToEnv, copyToPtr	Classifies types by their relationship to environments. needsEnv returns True if the value carries heap pointers that must be remapped when moved between environments. mapToEnv performs the remapping. Default implementations return False and the identity respectively, suitable for scalar types.
EnvIndependent a	Prelude	(inherits Env)	Subclass of Env for types whose values never require environment mapping. Overrides needsEnv to return False and mapToEnv to the identity.
EnvDependent a	Prelude	(inherits Env)	Subclass of Env for types whose values always require environment mapping. Overrides needsEnv to return True.
Mark_GC a	Prelude	mark_GC	Supports garbage collection. mark_GC traverses the value and marks all reachable heap storage. The default implementation is a no-op, suitable for scalar types. Must be overridden for any type containing Ptr, expression, or function values.
Disposable a	Prelude	destroy	Supports explicit resource release. destroy frees any resources held by the value. The default implementation is a no-op.
Eval a, b	Prelude	eval	Evaluates a value of type a to a value of type b. The primary instance reduces Exp b to b.
Cast a, b	Prelude	cast	General type conversion from a to b. May involve reduction of lazy expressions. The default subordinate instance delegates to strictCast.
StrictCast a, b	Prelude	strictCast	Strict type conversion from a to b, with no implicit reduction. Used for numeric coercions and conversions between primitive types.
IntegralCast Int, b	Prelude	fromInt	Extends StrictCast. Converts an Int value to type b. Instances are provided for Byte, Float, and Double.
Eq a	Prelude	=, /=	Equality and inequality. /= has a default implementation as the negation of =.
Ord a	Prelude	<, <=, >, >=, compare, max	Extends Eq with ordering. max has a default implementation in terms of <=.
Bitwise a	Prelude	<<, >>, #&, #^, #|, #¬	Bitwise shift and logical operations. Instances are provided for Bits32.
Num a	Prelude	zero, succ, pred, +, -, *, mod, plus, negate, abs	Numeric arithmetic. plus defaults to the identity; abs defaults to a conditional negation using zero and <=.
FractionalNum a	Prelude	/	Extends numeric types with division. Instances are provided for Float and Double.
Select a, b	Prelude	.	Named field selection via dot notation. a . name retrieves the value bound to name from a container of type a, returning a value of type b.
Seq a	Prelude	length, tail, take, drop, ++	Sequential container operations: length, tail, prefix, suffix, and concatenation.
ReverseableSeq a	Prelude	reverse	Extends Seq with reversal. Instances are provided for String and Array b.
IndexableSeq a, b	Prelude	getAt, putAt, head	Indexed element access and modification. head returns the first element.
Textual a	Prelude	format, stringify	String conversion. format applies a C-style format string; stringify produces a default string representation. Used by the default implementation of show.
Fetch a	Prelude	fetch	Provides a shared lazy expression holding a value of type a. Instances are provided for Int and Double.
Show a	Prelude	show, showWithNewline	Output to the standard output stream. showWithNewline appends a newline. The default implementation of show delegates to stringify via the Textual class.

3.3 Global Names

Name	Module	Category	Type Signature	Description	Example
id	Prelude	Function	a -> a	Identity function. Returns its argument unchanged.	id 42 returns 42.
reduce	Prelude	Function	Exp a -> a	Forces evaluation of a lazy expression. Equivalent to #! prefix notation.	reduce xs forces the head of a lazy list.
ignore	Prelude	Function	a -> Void	Evaluates its argument and discards the result. Used to force side effects.	ignore (socket.send bytes).
mkThunk	Prelude	Function	a -> (-> a)	Wraps a value in a zero-argument closure (thunk).	mkThunk 42 produces a thunk yielding 42.
mkExpr	Prelude	Function	a -> Exp a	Wraps a value as a lazy expression. Inverse of reduce.	mkExpr 42 produces an Exp Int.
compose	Prelude	Function	(b -> c) -> (a -> b) -> (a -> c)	Function composition. compose f g x applies g then f.	compose (*2) (+1) 3 returns 8.
fix	Prelude	Function	((a -> a) -> a -> a) -> (a -> a)	Fixed-point combinator for unary functions. Enables general recursion without a named binding.	fix (\rec n -> if n = 0 then 1 else n * rec (n-1)) 5 returns 120.
fix2	Prelude	Function	((a -> a -> a) -> a -> a -> a) -> (a -> a -> a)	Fixed-point combinator for binary functions.	fix2 (\rec x y -> if x = 0 then y else rec (x-1) (y+1)) 3 0 returns 3.
not	Prelude	Function	Bool -> Bool	Logical negation.	not True returns False.
&	Prelude	Function	Bool -> Bool -> Bool	Lazy logical conjunction. The second argument is not evaluated if the first is False.	True & False returns False.
|	Prelude	Function	Bool -> Bool -> Bool	Lazy logical disjunction. The second argument is not evaluated if the first is True.	False | True returns True.
fst	Prelude	Function	(a, b) -> a	Returns the first element of a pair.	fst (1, 2) returns 1.
snd	Prelude	Function	(a, b) -> b	Returns the second element of a pair.	snd (1, 2) returns 2.
fst3	Prelude	Function	(a, b, c) -> a	Returns the first element of a triple.	fst3 (1, 2, 3) returns 1.
snd3	Prelude	Function	(a, b, c) -> b	Returns the second element of a triple.	snd3 (1, 2, 3) returns 2.
thd3	Prelude	Function	(a, b, c) -> c	Returns the third element of a triple.	thd3 (1, 2, 3) returns 3.
isNull	Prelude	Function	Ptr a -> Bool	Tests whether a pointer is Null.	isNull Null returns True.
dePtr	Prelude	Function	Ptr a -> a	Dereferences a non-null pointer. Behaviour is undefined on Null.	dePtr (Ptr 42) returns 42.
fstPtr	Prelude	Function	Ptr (a, b) -> Ptr a	Returns a pointer to the first component of a pointer-to-pair, without copying.	fstPtr pairPtr.
sndPtr	Prelude	Function	Ptr (a, b) -> Ptr b	Returns a pointer to the second component of a pointer-to-pair, without copying.	sndPtr pairPtr.
isNothing	Prelude	Function	Maybe a -> Bool	Returns True if the value is Nothing.	isNothing Nothing returns True.
@=	Prelude	Function	a -> Ptr a -> Void	Assigns a value to a pointer, mapping the value to the pointer's environment before writing.	x @= ptr stores x remapped to ptr's environment.
assignByPtr	Prelude	Function	Ptr a -> Ptr a -> Void	Copies the value at the source pointer to the destination pointer, mapping between environments as required. Used internally by Code::genTypeMethods.	assignByPtr pSrc pDst.
mapFreeVarToEnv	Prelude	Function	a -> Env -> a	Maps a free variable to a target environment if it requires environment mapping; otherwise returns it unchanged. Used internally during closure construction.	mapFreeVarToEnv x env.
copyClosure	Prelude	Function	Env -> a	Allocates a copy of the current closure, remapping its free variables to the given environment. The compiler generates a specialised version of this for each closure type.	copyClosure dstEnv.
mapGenPtr	Prelude	Function	Ptr a -> Env -> Ptr a	Remaps a heap pointer to a target environment by allocating a new cell in that environment. The compiler generates a specialised version for each exposed closed type.	mapGenPtr ptr dstEnv.
markGenPtr	Prelude	Function	Ptr a -> Void	Marks the value at a pointer for garbage collection by calling mark_GC on the dereferenced value. The compiler generates a specialised version for each exposed closed type.	markGenPtr ptr.
showGenPtr	Prelude	Function	Ptr a -> Void	Displays the value at a pointer by calling show on the dereferenced value. The compiler generates a specialised version for each exposed closed type.	showGenPtr ptr.
typeOf	Prelude	Primitive	a -> Type	Returns the runtime Type descriptor of its argument.	typeOf 42 returns the Type for Int.
envOf	Prelude	Primitive	a -> Env	Returns the environment that owns the storage for the given value.	envOf name returns the environment holding the name's string data.
sizeOf	Prelude	Primitive	Type -> Int	Returns the storage size in bytes of the given type.	sizeOf (typeOf 0) returns the size of Int.
error	Prelude	Primitive	String -> a	Raises a runtime error with the given message. The return type is polymorphic so it may appear in any context.	error "index out of bounds".
castPtr	Prelude	Primitive	Ptr a -> Ptr b	Reinterprets a pointer as a pointer to a different type without any copying or conversion. Use with care.	castPtr ptr :: Ptr Byte.
cond	Prelude	Primitive	Bool -> a -> a -> a	Conditional selection. Equivalent to if ... then ... else ... in expression form.	cond (x > 0) x (negate x).

3.4 Instance Definitions

Class	Type(s)	Module	Notes
Env	Env	Prelude	Default (scalar).
Mark_GC	Env	Prelude	Default no-op.
Disposable	Env	Prelude	Calls primitive destroyEnv.
Eq	Env	Prelude	Pointer equality via primitives eqEnv, neqEnv.
Env	Plain b	Prelude	Default (not subject to environment mapping).
Mark_GC	Plain b	Prelude	Special case; plain values are handled directly by the collector.
Show	Plain b	Prelude	No-op; plain values have no user-visible representation.
Show	Exp Void	Prelude	Subordinate instance. show and showWithNewline reduce the expression.
StrictCast	-> b, b	Prelude	Forces the thunk via fromThunk.
Env	-> b	Prelude	needsEnv returns True; mapToEnv via primitive mapThunk.
Mark_GC	-> b	Prelude	Marks via markPtr_GC / markCell_GC.
Env	b -> c	Prelude	needsEnv returns True; mapToEnv via primitive mapFn.
Mark_GC	b -> c	Prelude	Marks via markPtr_GC / markCell_GC.
Show	b -> c	Prelude	Displays the string literal "*** Function ***".
Env	Exp b	Prelude	Subordinate. needsEnv returns True; mapToEnv via primitive mapExpr.
Mark_GC	Exp b	Prelude	Marks via markExprPtr_GC / markExpr_GC.
Eval	Exp b, b	Prelude	Reduces the expression. Constrained by | !b.
Eval	Exp c, b	Prelude	Subordinate. Reduces then evaluates further. Constrained by | !b and not !c.
Cast	Exp b, b	Prelude	Reduces the expression.
Cast	Exp c, b	Prelude	Subordinate. Reduces then casts. Constrained by (not !c) or !c and (instance StrictCast c, b).
StrictCast	a, Exp a	Prelude	Wraps a value as a lazy expression via mkExpr. Constrained by a /= Void.
Eval	b, b	Prelude	Identity evaluation for already-strict values. Constrained by | !b.
Env	Name	Prelude	needsEnv returns True; mapToEnv via primitive mapName.
Mark_GC	Name	Prelude	Default no-op (handled by collector).
Eq	Name	Prelude	Via primitive eqName.
Textual	Name	Prelude	stringify via nameString.
Show	Name	Prelude	Via primitive showName.
Env	Type	Prelude	needsEnv returns True; mapToEnv via primitive mapType.
Mark_GC	Type	Prelude	Default no-op.
Eq	Type	Prelude	Via primitive eqType.
Show	Type	Prelude	Via primitive showType.
Env	Byte	Prelude	Default (scalar).
Mark_GC	Byte	Prelude	Default no-op.
StrictCast	Int, Byte	Prelude	Via primitive fromIntByte.
IntegralCast	Int, Byte	Prelude	Via primitive fromIntByte.
Env	Bits32	Prelude	Default (scalar).
Mark_GC	Bits32	Prelude	Default no-op.
Bitwise	Bits32	Prelude	All six bitwise operations via corresponding primitives.
Env	Int	Prelude	Default (scalar).
Mark_GC	Int	Prelude	Default no-op.
Eq	Int	Prelude	Via primitives eqInt, nEqInt.
Ord	Int	Prelude	Via primitives ltInt, ltEqInt, gtInt, gtEqInt, compareInt.
Num	Int	Prelude	Via primitives addInt, subInt, mulInt, modInt, negInt.
Fetch	Int	Prelude	Shared lazy integer value via fetchInt.
Textual	Int	Prelude	format via primitive formatInt; stringify uses format "%d".
Show	Int	Prelude	Via primitive showInt.
Env	Float	Prelude	Default (scalar).
Mark_GC	Float	Prelude	Default no-op.
Eq	Float	Prelude	Via primitives eqFloat, nEqFloat.
Ord	Float	Prelude	Via primitives ltFloat, ltEqFloat, gtFloat, gtEqFloat, compareFloat.
Num	Float	Prelude	Via primitives addFloat, subFloat, mulFloat, negFloat.
FractionalNum	Float	Prelude	Via primitive divFloat.
Textual	Float	Prelude	format via primitive formatFloat; stringify uses format "%f".
Show	Float	Prelude	Via primitive showFloat.
Env	Double	Prelude	Default (scalar).
Mark_GC	Double	Prelude	Default no-op.
Eq	Double	Prelude	Via primitives eqDouble, nEqDouble.
Ord	Double	Prelude	Via primitives ltDouble, ltEqDouble, gtDouble, gtEqDouble, compareDouble.
Num	Double	Prelude	Via primitives addDouble, subDouble, mulDouble, negDouble.
FractionalNum	Double	Prelude	Via primitive divDouble.
Fetch	Double	Prelude	Shared lazy double value via fetchDouble.
Textual	Double	Prelude	format via primitive formatDouble; stringify uses format "%f".
Show	Double	Prelude	Via primitive showDouble.
Env	Char	Prelude	Default (scalar).
Mark_GC	Char	Prelude	Default no-op.
Eq	Char	Prelude	Via primitives eqChar, nEqChar.
Ord	Char	Prelude	Via primitives ltChar, ltEqChar, gtChar, gtEqChar, compareChar.
Textual	Char	Prelude	format via primitive formatChar; stringify uses format "%c".
Show	Char	Prelude	Via primitive showChar.
Env	String	Prelude	needsEnv returns True; mapToEnv via primitive mapString.
Mark_GC	String	Prelude	Via primitive markString_GC.
Eq	String	Prelude	Via primitives eqString, nEqString.
Ord	String	Prelude	Via primitives ltString, ltEqString, gtString, gtEqString, compareString.
Seq	String	Prelude	length via lengthString; ++ via concatString.
ReverseableSeq	String	Prelude	Via primitive reverseString.
IndexableSeq	String, Char	Prelude	getAt via getAtString; putAt via putAtString.
Textual	String	Prelude	format via primitive formatString; stringify is the identity.
Show	String	Prelude	Via primitive showString.
Env	Bool	Prelude	Default (scalar).
Mark_GC	Bool	Prelude	Default no-op.
Eq	Bool	Prelude	Via primitives eqBool, nEqBool.
Show	Bool	Prelude	Via primitive showBool.
Env	Array b	Prelude	Default (scalar; array pointer is not remapped).
ReverseableSeq	Array b	Prelude	Reverse operation on array contents.
Env	Ptr b	Prelude	Constrained by instance Env b. needsEnv returns True; mapToEnv allocates a new cell in the destination environment.
Mark_GC	Ptr b	Prelude	Constrained by instance Mark_GC b. Marks the pointed-to value if the pointer has not already been marked.
Eq	Ptr b	Prelude	Pointer equality via primitive eqPtr.
Show	Ptr b	Prelude	Constrained by b /= Array c. Displays Null or the dereferenced value with "^(" / ")" delimiters.
Env	Ptr (Array b)	Prelude	needsEnv returns False; mapToEnv raises a runtime error (array size unknown).
Mark_GC	Ptr (Array b)	Prelude	Default no-op; custom types must mark array elements explicitly.
Show	Ptr (Array b)	Prelude	Displays the literal string "^ARRAY".
Eq	Plain (Ptr b)	Prelude	Via primitive eqPlainPtr.
Env	(b, c)	Prelude	needsEnv returns True if either component does; mapToEnv maps both components.
Mark_GC	(b, c)	Prelude	Marks both components.
Disposable	(b, c)	Prelude	Destroys both components.
Eq	(b, c)	Prelude	Componentwise equality.
Textual	(b, c)	Prelude	Produces a comma-separated parenthesised string.
Show	(b, c)	Prelude	Displays as (c1,c2).
Env	(b, c, d)	Prelude	needsEnv returns True if any component does; mapToEnv maps all three components.
Mark_GC	(b, c, d)	Prelude	Marks all three components.
Textual	(b, c, d)	Prelude	Produces a comma-separated parenthesised string.
Show	(b, c, d)	Prelude	Displays as (c1,c2,c3).
Env	UTC	Prelude	Default (scalar).
Mark_GC	UTC	Prelude	Default no-op.
Show	UTC	Prelude	Via primitive showUTC.
Env	Ordering	Prelude	Default (scalar).
Mark_GC	Ordering	Prelude	Default no-op.
Show	Ordering	Prelude	Via primitive showOrdering.
Env	When	Prelude	Default (scalar).
Mark_GC	When	Prelude	Default no-op.
Show	When	Prelude	Via primitive showWhen.
Env	Maybe b	Prelude	needsEnv returns True; mapToEnv maps the contained value if present.
Mark_GC	Maybe b	Prelude	Marks the contained value if Just.
Show	Maybe b	Prelude	Displays "Nothing" or the contained value.
Env	Uneval b	Prelude	needsEnv returns True; mapToEnv maps the wrapped expression.
Mark_GC	Uneval b	Prelude	Marks the wrapped expression.
Show	Uneval b	Prelude	Reduces and displays the wrapped expression.

4 Extended tuples

The Tuple_4_10 module provides class instances for tuples of arity 4 through 10 (quadruples to decuples). Each of the five instance classes listed below applies uniformly to all seven arities. The notation (a, b, ..., n) denotes any such tuple, where the type variables represent the component types at each position.

4.1 Instance definitions

Class	Type(s)	Module	Method(s)
Env	(a, b, ..., n) — all arities 4 to 10	Tuple_4_10	needsEnv, mapToEnv
Mark_GC	(a, b, ..., n) — all arities 4 to 10	Tuple_4_10	mark_GC
Eq	(a, b, ..., n) — all arities 4 to 10	Tuple_4_10	(=)
Textual	(a, b, ..., n) — all arities 4 to 10	Tuple_4_10	stringify
Show	(a, b, ..., n) — all arities 4 to 10	Tuple_4_10	show

5 IO

The IO module provides the environment and garbage-collection infrastructure for the primitive FileHandle type. File handles are opened and closed by the built-in functions openFile, closeFile, readFileByte, and writeFileByte; this module supplies the class instances required so that handles can participate in environment remapping and GC marking.

5.1 Instance definitions

Class	Type(s)	Module	Method(s)
Env	FileHandle	IO	needsEnv, mapToEnv
Mark_GC	FileHandle	IO	mark_GC

6 Streams

The Streams module provides typed byte-stream I/O. The StreamInsert and StreamExtract type classes define uniform serialisation and deserialisation for all standard types. File-based binary streams are created with fileOutputByteStream and fileInputByteStream.

6.1 Type Definitions

Name	Module	Data Constructors	Description
InputStream a	Streams	InputStream (Exp a) (Exp Void)	A typed input stream producing values of type a. The first component is the input action; the second is the close action.
OutputStream a	Streams	OutputStream (a -> Void) (Exp Void)	A typed output stream consuming values of type a. The first component is the output function; the second is the close action.

6.2 Class Definitions

Class Name	Type Variables	Methods
StreamInsert	a, b	Name Type Signature Description insert a -> b -> Void Serialises a value of type b to stream a.
StreamExtract	a, b	Name Type Signature Description extract a -> b Deserialises a value of type b from stream a.

6.3 Global Names

Name	Module	Category	Type Signature	Description	Example
fileInputByteStream	Streams	Function	String -> InputStream Byte	Opens a file for binary reading and returns an InputStream Byte.	fileInputByteStream "data" opens the file "data" for reading.
fileOutputByteStream	Streams	Function	String -> OutputStream Byte	Opens a file for binary writing and returns an OutputStream Byte.	fileOutputByteStream "data" opens the file "data" for writing.
streamInputAction	Streams	Function	InputStream a -> Exp a	Returns the input action of an input stream.	streamInputAction is returns the action that reads the next value from is.
streamOutputFn	Streams	Function	OutputStream a -> (a -> Void)	Returns the output function of an output stream.	streamOutputFn os returns the function that writes a value to os.
streamCloseInputAction	Streams	Function	InputStream a -> Exp Void	Returns the close action for an input stream. The action must be evaluated to close the underlying resource.	streamCloseInputAction is closes the input stream is.
streamCloseOutputAction	Streams	Function	OutputStream a -> Exp Void	Returns the close action for an output stream. The action must be evaluated to close the underlying resource.	streamCloseOutputAction os closes the output stream os.
insert	Streams	Class method	OutputStream Byte -> b -> Void	Serialises a value to a binary output stream. Instances are provided for all standard types.	insert os 42 writes the integer 42 to os.
extract	Streams	Class method	InputStream Byte -> b	Deserialises a value from a binary input stream. Instances are provided for all standard types.	(#!(extract is))::Int reads an integer from is.

6.4 Instances

Class	Type(s)	Qualifier(s)	Method(s)	Description
StreamInsert, StreamExtract	OutputStream Byte, Int		insert, extract	Binary serialisation of integer values.
StreamInsert, StreamExtract	OutputStream Byte, Float		insert, extract	Binary serialisation of single-precision floating-point values.
StreamInsert, StreamExtract	OutputStream Byte, Double		insert, extract	Binary serialisation of double-precision floating-point values.
StreamInsert, StreamExtract	OutputStream Byte, Char		insert, extract	Binary serialisation of character values.
StreamInsert, StreamExtract	OutputStream Byte, String		insert, extract	Binary serialisation of string values.
StreamInsert, StreamExtract	OutputStream Byte, Bool		insert, extract	Binary serialisation of boolean values.
StreamInsert, StreamExtract	OutputStream Byte, Name		insert, extract	Binary serialisation of name values.
StreamInsert, StreamExtract	OutputStream Byte, Type		insert, extract	Binary serialisation of type values.
StreamInsert, StreamExtract	OutputStream Byte, (a, b)		insert, extract	Binary serialisation of two-element tuples.
StreamInsert, StreamExtract	OutputStream Byte, (a, b, c)		insert, extract	Binary serialisation of three-element tuples.
StreamInsert, StreamExtract	OutputStream Byte, Ptr a		insert, extract	Binary serialisation of pointer values. A null pointer is serialised as 0; a non-null pointer serialises the pointed-to value preceded by 1.
StreamInsert, StreamExtract	OutputStream Byte, Exp a		insert, extract	Binary serialisation of lazy expressions, including unevaluated thunks.
StreamInsert, StreamExtract	OutputStream Byte, a -> b		insert, extract	Binary serialisation of function closures.
StreamInsert, StreamExtract	OutputStream Byte, Env		insert, extract	Binary serialisation of runtime environments.

7 Streams: extended tuples

The Streams_Tuple_4_10 module extends the byte-stream serialisation infrastructure to cover tuples of arity 4 through 10. Both instance classes listed below apply uniformly to all seven arities. Components are read and written in left-to-right order, delegating to the existing stream instances for each component type.

7.1 Instance definitions

Class	Type(s)	Module	Method(s)
StreamExtract	(InputStream Byte), (a, b, ..., n) — all arities 4 to 10	Streams_Tuple_4_10	extract
StreamInsert	(OutputStream Byte), (a, b, ..., n) — all arities 4 to 10	Streams_Tuple_4_10	insert

8 Serialisable

The Serialisable module defines the two-parameter Serialisable type class. An instance Serialisable a b states that values of type a can be losslessly converted to and from a serialised form of type b. The class is distinct from the byte-stream StreamInsert and StreamExtract classes: Serialisable expresses an abstract round-trip contract without prescribing a particular wire format.

8.1 Class definitions

Name	Module	Type Signature	Description
Serialisable	Serialisable	serialise :: a -> b	Converts a value of type a to its serialised representation of type b.
		deserialise :: b -> a	Reconstructs a value of type a from its serialised form b.

9 Any

The Any module provides the Any dynamic type — a uniform wrapper that can hold a value of any IvoryScript type together with its runtime type descriptor. Conversions between a concrete type and Any are handled automatically by subordinate StrictCast instances. Any values support environment remapping, garbage-collection marking, and byte-stream serialisation.

9.1 Type definitions

Name	Module	Data Constructors	Description
Any	Any	Any a	A dynamically-typed value. Internally represented as the pair (Type, Ptr a) where the first component is the runtime type descriptor and the second is a pointer to the value.

9.2 Global names

Name	Module	Category	Type Signature	Description
Any	Any	Constructor	a -> (Type, Ptr a)	Wraps a value in Any by pairing it with its runtime type descriptor and allocating a pointer cell for the value.
typeOfAny	Any	Function	Any -> Type	Returns the runtime type descriptor of the value held inside an Any.

9.3 Instance definitions

Class	Type(s)	Module	Qualifier(s)	Method(s)
StrictCast (subordinate)	c, Any	Any	!c, c ≠ Void, c ≠ Any	strictCast — wraps a forced value of any concrete type as Any.
StrictCast (subordinate)	Any, c	Any	c ≠ Void	strictCast — extracts a value of type c from an Any, pattern-matching on the type.
Env	Any	Any		needsEnv, mapToEnv — remaps the type descriptor and the pointed-to value into the target environment using mapAnyPtr.
Mark_GC	Any	Any		mark_GC — delegates to markAny_GC, which dispatches via the embedded type descriptor.
Show (subordinate)	Any	Any		show — delegates to showAny, which dispatches via the embedded type descriptor.
StreamExtract	(InputStream Byte), Any	Any		extract — reads the type tag then deserialises the value using extractAnyPtr.
StreamInsert	(OutputStream Byte), Any	Any		insert — writes the type tag then serialises the value using insertAnyPtr.

10 Binding

The Binding module defines a binding between two typed values and provides the BindingSet class for managing collections of bindings.

10.1 Type definitions

Name	Module	Data Constructors	Description
Binding a b	Binding	Bind a b	Represents a binding between two typed values. Represented as (a, b).

10.2 Global names

Name	Module	Category	Type Signature	Description
Bind	Binding	Data constructor	a -> b -> (a, b)	Constructs a binding between two values.

10.3 Class definitions

Name	Module	Type Signature	Description
BindingSet	Binding	addBinding :: a -> b -> c -> Void	Adds a binding to a set.
		hasBinding :: a -> b -> Bool	Checks if a binding exists in a set.
		removeBinding :: a -> b -> Void	Removes a binding from a set.

10.4 Instance definitions

Class	Type(s)	Module	Method(s)
Env	Binding b c	Binding	needsEnv, mapToEnv
Mark_GC	Binding b c	Binding	mark_GC
Textual	Binding b c	Binding	stringify
Show	Binding b c	Binding	show
StrictCast	Binding Name c, Binding Name Any	Binding	strictCast
StreamExtract	(InputStream Byte), Binding c d	Binding	extract
StreamInsert	(OutputStream Byte), Binding c d	Binding	insert

11 List

The List module defines the list type and provides functions for list construction, sequencing, reversal, sorting, and infinite list generation.

11.1 Function Definitions

Name	Module	Category	Type Signature	Description
Nil	List	Data constructor	Ptr Void	Represents an empty list.
Cons	List	Data constructor	a -> Exp [a] -> Ptr (a, Exp [a])	Constructs a list cell with a head element and lazy tail.
unmappedCons	List	Variable	a -> Exp [a] -> [a]	Constructs a list cell without environment mapping.
hd	List	Variable	c -> d	Returns the head of a list.
tl	List	Variable	c -> d	Returns the tail of a list.
takeList	List	Variable	Int -> c -> c	Takes the first n elements of a list.
dropList	List	Variable	Int -> c -> c	Drops the first n elements of a list.
lengthList	List	Variable	b -> Int	Returns the length of a list.
concatList	List	Variable	Exp [a] -> Exp [a] -> Exp [a]	Concatenates two lazy lists.
concatList_	List	Variable	[a] -> [a] -> [a]	Concatenates two strict lists.
reverseList	List	Variable	c -> c	Reverses a list.
replicate	List	Variable	a -> Int -> b	Replicates a value n times.
repeat	List	Variable	a -> Exp [a]	Creates an infinite list with the same value repeated.
cycle	List	Variable	b -> b	Creates an infinite list by repeating a list cyclically.
listFrom	List	Variable	a -> a -> b	Creates an infinite list starting from s with step step.
listFromTo	List	Variable	a -> a -> a -> b	Creates a bounded list from s to e with step step.
merge	List	Variable	b -> b -> b	Merges two ordered lists into one ordered list.
mergeSort	List	Variable	[c] -> [c]	Sorts a list using merge sort.

11.2 Instance Definitions

Class	Type(s)	Module	Method(s)
Env	[b]	List	needsEnv, mapToEnv
Mark_GC	[b]	List	mark_GC
Show	[b]	List	show
Show (subordinate)	Exp [b]	List	show
Seq	Exp [b]	List	length, tail, take, drop, (++)
Seq (subordinate)	[b]	List	length, tail, take, drop, (++)
IndexableSeq	Exp [b], b	List	head
IndexableSeq (subordinate)	[b], b	List	head
ReverseableSeq	Exp [b]	List	reverse
ReverseableSeq (subordinate)	[b]	List	reverse
StreamExtract	(InputStream Byte), [c]	List	extract
StreamInsert	(OutputStream Byte), [c]	List	insert

12 List functions

The ListFunction module provides operations on lists that involve functions, including filtering, folding, mapping, flattening, and grouping.

12.1 Function Definitions

Name	Module	Category	Type Signature	Description	Example
filter	ListFunction	Variable	(a -> Bool) -> b -> b	Filters elements of a list based on a predicate.	filter ((<) 2) [1, 2, 3, 4] -> [3, 4]
flatMap	ListFunction	Variable	(a -> Exp [b]) -> Exp [a] -> Exp [b]	Applies a function returning a list to each element, then flattens the result. Equivalent to flatten (mapf f xs).	flatMap (\x -> [x, x*2]) [1, 2] -> [1, 2, 2, 4]
flatten	ListFunction	Variable	a -> b	Flattens a list of lists into a single list.	flatten [[1, 2], [3, 4]] -> [1, 2, 3, 4]
foldl	ListFunction	Variable	(b -> a -> b) -> b -> [a] -> b	Left-associative fold of a list using a function.	foldl (+) 0 [1, 2, 3, 4] -> 10
foldr	ListFunction	Variable	(a -> b -> b) -> b -> c -> b	Right-associative fold of a list using a function.	foldr (\x xs -> x :+ xs) [] [1, 2, 3] -> [1, 2, 3]
groupBy	ListFunction	Variable	(a -> a -> Bool) -> [a] -> [[a]]	Groups consecutive elements of a list according to a predicate.	groupBy (=) [1, 1, 2, 3, 3, 4] -> [[1,1],[2],[3,3],[4]]
iterate	ListFunction	Variable	(a -> a) -> a -> b	Produces an infinite list by applying a function iteratively to a seed value.	take 5 (iterate ((+) 1) 0) -> [0, 1, 2, 3, 4]
mapf	ListFunction	Variable	(a -> b) -> c -> d	Applies a function to every element of a list.	mapf ((*) 2) [1, 2, 3] -> [2, 4, 6]
span	ListFunction	Variable	(a -> Bool) -> [a] -> ([a], [a])	Splits a list into a prefix satisfying a predicate and the remainder.	span ((>) 3) [1, 2, 3, 4] -> ([1, 2], [3, 4])

13 Strings and character lists

The StringList module provides basic string and character list functions, including conversions between them.

13.1 Function Definitions

Name	Module	Category	Type Signature	Description
chars	StringList	Variable	String -> [Char]	Converts a string into a list of characters.
quotedChars	StringList	Variable	[Char] -> [String]	Converts a list of characters into a list of quoted strings.
string	StringList	Variable	Exp [Char] -> String	Converts a list of characters into a string.

13.2 Instance Definitions

Class	Type(s)	Module	Method(s)
StrictCast	[Char], String	StringList	strictCast
StrictCast (subordinate)	String, Exp [Char]	StringList	strictCast

14 Tree

The Tree module defines a binary tree data type and provides functions for manipulating and displaying trees, including depth calculation, maximum value, and sum of all elements.

14.1 Type Definitions

Name	Module	Data Constructors	Description
Tree	Tree	Empty, Leaf a, Branch (Exp (Tree a)) (Exp (Tree a))	A binary tree: empty, a leaf containing a value, or a branch with two lazy subtrees.

14.2 Global Names

Name	Module	Category	Type Signature	Description
Empty	Tree	Data Constructor	Tree a	Represents an empty tree.
Leaf	Tree	Data Constructor	a -> Ptr a	Constructs a leaf node containing a value.
Branch	Tree	Data Constructor	Exp (Tree a) -> Exp (Tree a) -> Ptr (Exp (Tree a), Exp (Tree a))	Constructs a branch node with left and right lazy subtrees.
unmappedBranch	Tree	Variable	Exp (Tree a) -> Exp (Tree a) -> Tree a	Constructs a branch node without environment mapping.
depthTree	Tree	Variable	Exp (Tree a) -> Int	Returns the depth of a tree.
maxTree	Tree	Variable	Exp (Tree a) -> Maybe a	Finds the maximum value in the tree.
sumTree	Tree	Variable	Exp (Tree a) -> a	Sums all values in the tree.

14.3 Instance Definitions

Class	Type(s)	Module	Method(s)
Env	Tree b	Tree	needsEnv, mapToEnv
Mark_GC	Tree b	Tree	mark_GC
Show	Exp (Tree b)	Tree	show
Textual	Tree b	Tree	stringify
StreamExtract	(InputStream Byte), Tree c	Tree	extract
StreamInsert	(OutputStream Byte), Tree c	Tree	insert

15 Array

The Array module defines type methods for the Array type in IvoryScript. However, direct arrays are not currently supported in IvoryScript, and only the supertype Ptr (Array a) is supported. All dynamic types must override the type methods.

15.1 Instance Definitions

Class	Type(s)	Module	Method(s)
Env	Array b	Array	needsEnv, mapToEnv
Show	Array b	Array	show

16 Basic vector

The BasicVector module provides a dynamic-length, pointer-backed array type. A BasicVector a stores n elements in a single contiguous Ptr (Array a) block and records the length as an Int. Construction from a list allocates the array in one pass; element access by index is O(1). The type supports environment remapping, garbage-collection marking, serialisation, and display via the standard class infrastructure.

16.1 Type definitions

Name	Module	Data Constructors	Description
BasicVector a	BasicVector	BasicVector [a]	A contiguous array of n elements represented as the pair (Int, Ptr (Array a)). The constructor accepts a list and allocates the backing store immediately.

16.2 Global names

Name	Module	Category	Type Signature	Description
BasicVector	BasicVector	Constructor	[a] -> BasicVector a	Builds a BasicVector from a list. Allocates a Ptr (Array a) of the appropriate length and copies each element into it, remapping each value into the construction environment.
lengthBasicVector	BasicVector	Function	BasicVector a -> Int	Returns the number of elements stored in the vector.
getAtBasicVector	BasicVector	Function	BasicVector a -> Int -> a	Returns the element at the given zero-based index. Raises a runtime error if the index is out of bounds.
getAtBasicVector_	BasicVector	Function	BasicVector a -> Int -> a	Returns the element at the given index without a range check. For use in contexts where the index is known to be valid.

16.3 Instance definitions

Class	Type(s)	Module	Method(s)
Env	BasicVector b	BasicVector	needsEnv, mapToEnv — allocates a new backing array in the target environment and copies each element, remapping it individually.
Mark_GC	BasicVector b	BasicVector	mark_GC — marks the backing Ptr (Array b) and recursively marks each element.
Seq	BasicVector b	BasicVector	length — delegates to lengthBasicVector.
IndexableSeq	BasicVector b, b	BasicVector	getAt — delegates to getAtBasicVector.
Show	BasicVector b	BasicVector	show — displays the vector in list notation: [e0, e1, …] or [] for an empty vector.
StreamExtract	(InputStream Byte), BasicVector c	BasicVector	extract — reads the element count as an Int, then deserialises each element in order.
StreamInsert	(OutputStream Byte), BasicVector c	BasicVector	insert — writes the element count as an Int, then serialises each element in order.

17 Vector

The Vector module defines the Vector type, a dynamic-length array implemented as a segmented slice structure for memory efficiency. It supports element access, update, length query, and index search operations.

17.1 Type Definitions

Name	Module	Data Constructors	Description
Vector	Vector	Vector [a] Int	A dynamic-length array represented as (Int, Int, Ptr (Array(Ptr (Array a)))): length, slice size, and slice table pointer.

17.2 Global Names

Name	Module	Category	Type Signature	Description
Vector	Vector	Data Constructor	[a] -> Int -> (Int, Int, Ptr (Array(Ptr (Array a))))	Constructs a vector from a list of elements and a slice size.
lengthVector	Vector	Variable	Vector a -> Int	Returns the length of the vector.
getAtVector	Vector	Variable	Vector a -> Int -> a	Retrieves the element at a given index.
putAtVector	Vector	Variable	Vector a -> Int -> a -> Void	Updates the element at a given index.
findVectorIndex	Vector	Variable	Vector a -> a -> Int	Returns the lowest index matching a given value, or -1 if not found.

17.3 Instance Definitions

Class	Type(s)	Module	Method(s)
Env	Vector b	Vector	needsEnv, mapToEnv
Mark_GC	Vector b	Vector	mark_GC
Seq	Vector b	Vector	length
IndexableSeq	Vector b, b	Vector	getAt, putAt
Show	Vector b	Vector	show
StreamExtract	(InputStream Byte), Vector c	Vector	extract
StreamInsert	(OutputStream Byte), Vector c	Vector	insert

18 Hash table

The HashTable module implements a map from keys to values using an array of slots, each comprising a chain of nodes. It supports operations for adding, retrieving, and removing key-value pairs.

18.1 Type Definitions

Name	Module	Data Constructors	Description
HashTable	HashTable	HashTable Int	A hash table represented as (Int, Ptr (Array(Ptr (HashTableEntry keyType valType)))): slot count and slot array pointer.
HashTableEntry	HashTable	HashTableEntry (Ptr (HashTableEntry keyType valType)) keyType valType	A node in a slot chain, represented as (Ptr (HashTableEntry keyType valType), keyType, valType): next pointer, key, and value.

18.2 Global Names

Name	Module	Category	Type Signature	Description
HashTable	HashTable	Data Constructor	Int -> (Int, Ptr (Array(Ptr (HashTableEntry keyType valType))))	Constructs a hash table with a specified number of slots.
HashTableEntry	HashTable	Data Constructor	Ptr (HashTableEntry keyType valType) -> keyType -> valType -> (Ptr (HashTableEntry keyType valType), keyType, valType)	Constructs a slot chain node with a next pointer, key, and value.
nHashTableSlots	HashTable	Variable	(HashTable keyType valType) -> Int	Returns the number of slots in the hash table.
hashTableSlots	HashTable	Variable	(HashTable keyType valType) -> Ptr (Array(Ptr (HashTableEntry keyType valType)))	Returns the slot array pointer.
findInHashTableSlot	HashTable	Variable	Ptr (HashTableEntry keyType valType) -> keyType -> Ptr (HashTableEntry keyType valType)	Searches for a node with the specified key in a slot chain.
hashTableGet	HashTable	Variable	(HashTable keyType valType) -> Int -> keyType -> Maybe valType	Retrieves the value associated with a given key.
hashTableAdd	HashTable	Variable	(HashTable keyType valType) -> Int -> keyType -> valType -> Void	Adds a new key-value pair to the hash table.
hashTableRemove	HashTable	Variable	(HashTable keyType valType) -> Int -> keyType -> Void	Removes a key-value pair from the hash table.
setHashTableEntryNext	HashTable	Variable	Ptr (HashTableEntry keyType valType) -> Ptr (HashTableEntry keyType valType) -> Void	Destructively updates the next pointer for a node in the slot chain.

18.3 Instance Definitions

Class	Type(s)	Module	Method(s)
Env	HashTableEntry keyType valType	HashTable	needsEnv, mapToEnv
Mark_GC	HashTableEntry keyType valType	HashTable	mark_GC
Show	HashTableEntry keyType valType	HashTable	show
Env	HashTable keyType valType	HashTable	needsEnv, mapToEnv
Mark_GC	HashTable keyType valType	HashTable	mark_GC
Show	HashTable keyType valType	HashTable	show
StreamExtract	(InputStream Byte), HashTable keyType valType	HashTable	extract
StreamInsert	(OutputStream Byte), HashTable keyType valType	HashTable	insert

19 Hash table functions

The HashTableFunction module provides higher-order operations over the HashTable type. Functions that accept a function argument are separated here from the core HashTable module to keep the base module free of higher-order dependencies.

19.1 Global names

Name	Module	Category	Type Signature	Description
foldHashTable	HashTableFunction	Function	(keyType -> valType -> a -> a) -> a -> HashTable keyType valType -> a	Right-to-left fold over all key/value entries in a hash table. The accumulator function receives each key and value in chain order within each slot, and slots are visited in index order. The result is the final accumulated value after all entries have been processed.

20 Name/Any map

The NameAnyMap module implements a map from names to values of type Any using a hash table. It supports binding, retrieval, and removal of key-value pairs where keys are of type Name.

20.1 Type Definitions

Name	Module	Data Constructors	Description
NameAnyMap	NameAnyMap	NameAnyMap Int	A hash table mapping Name keys to values of type Any.

20.2 Global Names

Name	Module	Category	Type Signature	Description
NameAnyMap	NameAnyMap	Data Constructor	Int -> HashTable Name Any	Constructs a name-to-Any map with the specified number of hash table slots.

20.3 Instance Definitions

Class	Type(s)	Module	Method(s)
Mark_GC	NameAnyMap	NameAnyMap	mark_GC
Env	NameAnyMap	NameAnyMap	needsEnv, mapToEnv
BindingSet	NameAnyMap, Name, Any	NameAnyMap	addBinding, removeBinding
Show	NameAnyMap	NameAnyMap	show
Select	NameAnyMap, Any	NameAnyMap	(.)
StreamExtract	(InputStream Byte), NameAnyMap	NameAnyMap	extract
StreamInsert	(OutputStream Byte), NameAnyMap	NameAnyMap	insert

21 Name/Any map functions

The NameAnyMapFunction module provides higher-order operations over the NameAnyMap type. It depends on HashTableFunction for the underlying fold primitive.

21.1 Global names

Name	Module	Category	Type Signature	Description
foldNameAnyMap	NameAnyMapFunction	Function	(Name -> Any -> a -> a) -> a -> NameAnyMap -> a	Folds a function over every name/value entry in a NameAnyMap, accumulating a result. Entry visit order follows the internal hash table slot order.
nameAnyMapNames	NameAnyMapFunction	Function	NameAnyMap -> Type -> String	Returns a formatted string listing the names of all entries whose value has the given runtime type. The result is a comma-separated list of quoted name strings enclosed in square brackets, e.g. ["x", "y"].

22 Property

The Property module defines the Property type — a named, dynamically-typed value. A Property is a Binding Name Any in which the bound value has been forced to a strict Any. Properties are the building blocks of PropertySet and are used throughout the Ivory System for structured, named data.

22.1 Type definitions

Name	Module	Data Constructors	Description
Property	Property	Property Name a	A named value of any type. Internally represented as a Binding Name Any; the value component is held as a strict Any so the runtime type is always available.

22.2 Global names

Name	Module	Category	Type Signature	Description
Property	Property	Constructor	Name -> a -> Binding Name Any	Constructs a Property from a name and a value. The value is immediately coerced to Any and the pair is wrapped as a Bind.
typeOfProperty	Property	Function	Property -> Type	Returns the runtime Type of the value held in a property by interrogating the inner Any.

22.3 Instance definitions

Class	Type(s)	Module	Method(s)
Env	Property	Property	needsEnv, mapToEnv — remaps the underlying Binding Name Any to the target environment.
Mark_GC	Property	Property	mark_GC — delegates to the Mark_GC instance for Binding Name Any.
Show	Property	Property	show — delegates to the Show instance for Binding Name Any.
StreamExtract	(InputStream Byte), Property	Property	extract — deserialises a Binding Name Any from the stream and wraps it as a Property.
StreamInsert	(OutputStream Byte), Property	Property	insert — serialises the underlying Binding Name Any to the stream.
StrictCast	Binding Name c, Property	Property	strictCast — converts a Binding Name c to a Property by forcing the value and wrapping it in Any.

23 Property set

The PropertySet module defines an ordered, indexed collection of Property values. A PropertySet is backed by a BasicVector Property, giving O(1) indexed access. Properties are looked up by name using the Select class dot operator; a runtime error is raised if the name is not found.

23.1 Type definitions

Name	Module	Data Constructors	Description
PropertySet	PropertySet	PropertySet [Property]	An ordered collection of named, dynamically-typed values backed by a BasicVector Property. The constructor accepts a list of Property values.

23.2 Global names

Name	Module	Category	Type Signature	Description
PropertySet	PropertySet	Constructor	[Property] -> PropertySet	Builds a PropertySet from a list of properties by delegating to BasicVector.

23.3 Instance definitions

Class	Type(s)	Module	Method(s)
Env	PropertySet	PropertySet	needsEnv, mapToEnv — remaps the backing BasicVector Property to the target environment.
Mark_GC	PropertySet	PropertySet	mark_GC — delegates to the Mark_GC instance for BasicVector Property.
Select	PropertySet, Any	PropertySet	(.) — looks up a property by Name key, scanning the vector linearly. Returns the Any value of the first matching property. Raises a runtime error if not found.
Show	PropertySet	PropertySet	show — delegates to the Show instance for BasicVector Property.
StreamExtract	(InputStream Byte), PropertySet	PropertySet	extract — deserialises a BasicVector Property from the stream and wraps it as a PropertySet.
StreamInsert	(OutputStream Byte), PropertySet	PropertySet	insert — serialises the backing BasicVector Property to the stream.

24 Mathematical constants

The MathConst module provides definitions for common mathematical constants such as e and pi, along with other important constants like the golden ratio, square root of 2, and natural logarithms.

24.1 Global Names

Name	Module	Category	Type Signature	Description	Example
e	MathConst	Variable	Double	Represents the mathematical constant e (Euler's number).	e = 2.71828182845904523536
pi	MathConst	Variable	Double	Represents the mathematical constant pi (ratio of a circle's circumference to its diameter).	pi = 3.14159265358979323846
phi	MathConst	Variable	Double	Represents the golden ratio, a mathematical constant with many applications in geometry and art.	phi = 1.61803398874989484820
sqrt2	MathConst	Variable	Double	Represents the square root of 2, commonly used in geometry.	sqrt2 = 1.41421356237309504880
ln2	MathConst	Variable	Double	Represents the natural logarithm of 2, important in logarithmic calculations.	ln2 = 0.69314718055994530942
ln10	MathConst	Variable	Double	Represents the natural logarithm of 10, useful in logarithmic base conversions.	ln10 = 2.30258509299404568402

25 Arithmetic functions

The Arith module implements common arithmetic functions such as factorial, greatest common divisor (gcd), least common multiple (lcm), and Fibonacci numbers etc.

25.1 Global Names

Name	Module	Category	Type Signature	Description	Example
fact	Arith	Variable	Int -> Int	Computes the factorial of a number using tail recursion.	fact 5 computes 120.
fibonacci	Arith	Variable	Int -> Int	Computes the nth Fibonacci number.	fibonacci 10 computes 55.
gcd	Arith	Variable	Int -> Int -> Int	Computes the greatest common divisor of two numbers using the Euclidean algorithm.	gcd 54 24 computes 6.
lcm	Arith	Variable	Int -> Int -> Int	Computes the least common multiple of two numbers.	lcm 54 24 computes 216.

26 Numeric aggregates

The NumAggregate module provides type classes and functions for computing aggregate values over lists of numbers.

26.1 Class Definitions

Class Name	Type Variables	Methods
SumAggregate	a, b	Name Type Signature Defined sum a -> b No
MeanAggregate	a, b	Name Type Signature Defined mean a -> b No

26.2 Global Names

Name	Module	Category	Type Signature	Description	Example
median	NumAggregate	Function	[a] -> a	Returns the median of a list of numbers. The list is sorted and the middle element selected; for even-length lists the mean of the two middle elements is returned.	median [1, 2, 3, 4, 5] returns 3.
sum	NumAggregate	Class method	a -> b	Returns the sum of a list of numbers.	sum [1, 2, 3] returns 6.
mean	NumAggregate	Class method	a -> b	Returns the arithmetic mean of a list of numbers.	mean [1.0, 2.0, 3.0] returns 2.0.

26.3 Instances

Class	Type(s)	Qualifier(s)	Method(s)	Description
SumAggregate	[Int], Int		sum	Sum of a list of integers.
MeanAggregate	[Int], Double		mean	Arithmetic mean of a list of integers, returned as a Double.
SumAggregate	[Double], Double		sum	Sum of a list of double-precision numbers.
MeanAggregate	[Double], Double		mean	Arithmetic mean of a list of double-precision numbers.

27 Integer sequences

The IntSeq module implements common integer sequences including factorials, Fibonacci numbers, prime numbers, and prime gap sequences.

27.1 Global Names

Name	Module	Category	Type Signature	Description	Example
factorials	IntSeq	Variable	Exp [Int]	An infinite lazy sequence of factorial numbers.	take 5 factorials -> [1, 1, 2, 6, 24]
fibonaccis	IntSeq	Variable	Exp [Int]	An infinite lazy sequence of Fibonacci numbers.	take 5 fibonaccis -> [0, 1, 1, 2, 3]
maximalPrimeGaps	IntSeq	Variable	Exp [(Int, Int)]	An infinite lazy sequence of (prime, gap to next) pairs where each gap is a new maximum over all previous gaps.	take 4 maximalPrimeGaps -> [(2,1),(3,2),(7,4),(23,6)]
maxPrime	IntSeq	Variable	Int -> Int	Returns the largest prime less than n.	maxPrime 100 -> 97
nthPrime	IntSeq	Variable	Int -> Int	Returns the nth prime number.	nthPrime 5 -> 11
positiveInts	IntSeq	Variable	Exp [Int]	An infinite lazy sequence of positive integers starting from 1.	take 5 positiveInts -> [1, 2, 3, 4, 5]
primeGaps	IntSeq	Variable	Exp [(Int, Int)]	An infinite lazy sequence of (prime, gap to next) pairs.	take 4 primeGaps -> [(2,1),(3,2),(5,2),(7,4)]
primes	IntSeq	Variable	Exp [Int]	An infinite lazy sequence of prime numbers generated by a sieve method.	take 5 primes -> [2, 3, 5, 7, 11]

28 Simple root

The SimpleRoot module provides a pre-allocated NameAnyMap in an isolated managed environment, serving as the application-wide root store for global data. The store is created once at module initialisation and remains available throughout the application lifetime. All standard NameAnyMap operations apply directly to root.

SimpleRoot is the lightest-weight form of a persistent root: it provides a live in-memory store with no serialisation overhead. For a persistent store that may be written to and read from a binary stream, see TransientDataStore and TransientStore.

28.1 Global Names

Name	Module	Category	Type Signature	Description	Example
root	SimpleRoot	Variable	NameAnyMap	The application-wide root store. A NameAnyMap with 47 hash slots allocated in an isolated managed environment. All NameAnyMap operations — addBinding, removeBinding, dot-selection, show, insert, and extract — apply directly.	addBinding root #config (Any #!"production") stores a global binding under the name config.

29 Transient data store

The TransientDataStore module provides an independent store holding a single root value of any type in an isolated managed environment. The root type is given by the type parameter a. Each store owns its environment exclusively: values within it are garbage-collected independently of the application heap and may be serialised to a binary stream like any other IvoryScript type.

For a named dictionary mapping Name keys to heterogeneous values, see the TransientStore module, which instantiates TransientDataStore with a NameAnyMap root.

29.1 Type Definitions

Name	Module	Data Constructors	Description
TransientDataStore a	TransientDataStore	TransientDataStore a	A persistent container holding a single root value of type a in an isolated managed environment. The environment is allocated at construction time and all values within the store are remapped into it.

29.2 Global Names

Name	Module	Category	Type Signature	Description	Example
TransientDataStore	TransientDataStore	Data constructor	a -> TransientDataStore a	Constructs a new transient data store containing the given root value. The value is remapped into a freshly allocated isolated environment.	TransientDataStore myValue creates a store with myValue as the root.
insert	TransientDataStore	Class method	OutputStream Byte -> TransientDataStore a -> Void	Serialises the store to a binary output stream. The format comprises a magic header (I_SDS_v_0001), the runtime environment, a type tag for a, and the root value.	insert os tds writes tds to os.
extract	TransientDataStore	Class method	InputStream Byte -> TransientDataStore a	Deserialises a store from a binary input stream. The magic header is validated and the embedded type tag checked against a; a mismatch raises an error.	tds :: TransientDataStore MyType = #!(extract is) restores a store from is.
destroy	TransientDataStore	Class method	TransientDataStore a -> Void	Releases the managed environment held by the store, freeing its memory.	destroy tds frees the store after use.

29.3 Instance Definitions

Class	Type(s)	Module	Method(s)
Disposable	TransientDataStore a	TransientDataStore	destroy
StreamInsert	OutputStream Byte, TransientDataStore a	TransientDataStore	insert
StreamExtract	InputStream Byte, TransientDataStore a	TransientDataStore	extract
Show	TransientDataStore a	TransientDataStore	show
Env	TransientDataStore a	TransientDataStore	(direct copy)
Mark_GC	TransientDataStore a	TransientDataStore	mark_GC

30 Transient store

The TransientStore module provides an independent store of named, dynamically-typed values in an isolated managed environment. A TransientStore is a TransientDataStore NameAnyMap: a dictionary mapping Name keys to values of type Any, each store owning its environment exclusively. As with any IvoryScript type, the store may be serialised to and deserialised from a binary byte stream.

30.1 Type Definitions

Name	Module	Data Constructors	Description
TransientStore	TransientStore	TransientStore	A TransientDataStore NameAnyMap. The standard named persistent store mapping Name keys to values of type Any.

30.2 Global Names

Name	Module	Category	Type Signature	Description	Example
TransientStore	TransientStore	Data constructor	TransientStore	Constructs a new empty transient store with 47 hash slots.	ts :: TransientStore = TransientStore creates a new empty store.
addBinding	TransientStore	Class method	TransientStore -> Name -> Any -> Void	Adds a named binding to the store. The value must be wrapped in Any.	addBinding ts #count (Any #!42) stores the integer 42 under the name count.
removeBinding	TransientStore	Class method	TransientStore -> Name -> Void	Removes the binding for the given name from the store.	removeBinding ts #count removes the count binding.
(.)	TransientStore	Class method	TransientStore -> Name -> Any	Retrieves the value bound to the given name via dot-notation syntax. An absent name raises an error.	ts.count :: Int retrieves the value bound to count as an Int.
insert	TransientStore	Class method	OutputStream Byte -> TransientStore -> Void	Serialises the store to a binary output stream via the underlying TransientDataStore serialisation.	insert os ts writes the contents of ts to os.
extract	TransientStore	Class method	InputStream Byte -> TransientStore	Deserialises a store from a binary input stream via the underlying TransientDataStore deserialisation.	ts :: TransientStore = #!(extract is) restores a store from is.
destroy	TransientStore	Class method	TransientStore -> Void	Releases the managed environment held by the store, freeing its memory.	destroy ts frees the store after use.

30.3 Instance Definitions

Class	Type(s)	Module	Method(s)
BindingSet	TransientStore, Name, Any	TransientStore	addBinding, removeBinding
Select	TransientStore, Any	TransientStore	(.)
Disposable	TransientStore	TransientStore	destroy
StreamInsert	OutputStream Byte, TransientStore	TransientStore	insert
StreamExtract	InputStream Byte, TransientStore	TransientStore	extract
Show	TransientStore	TransientStore	show
Env	TransientStore	TransientStore	(direct copy)
Mark_GC	TransientStore	TransientStore	mark_GC

30.4 Example

The following example demonstrates persisting an infinite lazy list of prime numbers to a file, then restoring and consuming part of it. The list is never fully evaluated; only the elements accessed by take are computed on restoration.

-- Persist the primes starting from the 1001st to a file
let {
   ts :: TransientStore = TransientStore;
   os :: OutputStream Byte = fileOutputByteStream "holyGrail"
} in {
   addBinding ts #primesFrom1000 (Any #!(drop 1000 primes));
   insert os ts;
   destroy ts;
   streamCloseOutputAction os;
};

-- Restore the store and take the first 100 elements
let {
   is :: InputStream Byte = fileInputByteStream "holyGrail";
   ts :: TransientStore = #!(extract is)
} in {
   streamCloseInputAction is;
   take 100 (ts.primesFrom1000::Exp [Int])
};
      

31 Any numeric

The AnyNum module provides a Num instance for the Any type, enabling arithmetic operations to be applied to dynamically-typed values. The implementation dispatches on the runtime type of the first operand and performs the corresponding concrete operation.

31.1 Instance definitions

Class	Type(s)	Module	Method(s)
Num	* (Any)	AnyNum	(+) — dispatches on the runtime type of the left operand. Supported types: Int, Double. The result is wrapped in Any.

32 Any sequence

The AnySeq module provides a Seq instance for the Any type, enabling the concatenation operator (++) to be applied to dynamically-typed sequence values. The implementation dispatches on the runtime type of the left operand.

32.1 Instance definitions

Class	Type(s)	Module	Method(s)
Seq	* (Any)	AnySeq	(++) — dispatches on the runtime type of the left operand. Supported types: String. The result is wrapped in Any.

33 Any binding set

The AnyBindingSet module provides Select and BindingSet instances for the Any type, enabling property lookup and binding mutation to be applied to dynamically-typed container values. Both instances dispatch at runtime on the concrete type held inside the Any wrapper, currently supporting PropertySet, NameAnyMap, and TransientStore.

33.1 Instance definitions

Class	Type(s)	Module	Method(s)
Select (subordinate)	Any, Any	AnyBindingSet	(.) — dispatches on the runtime type of the Any container. Supported container types: PropertySet, NameAnyMap, TransientStore. The key must be a Name value wrapped in Any.
BindingSet	Any, Name, Any	AnyBindingSet	addBinding, removeBinding — dispatches on the runtime type of the container. Supported container types: NameAnyMap, TransientStore.