The Extensions Module

Ultimately, there will be several, more logically separate libraries that extend Dylan or provide an application framework for users. For now, we put any commonly used utilities in the Extensions module.

Generally Useful Definitions

The Extensions module exports the following generally useful functionality:


<byte-vector>[sealed Class]

A <vector> that holds integers between 0 and 255 inclusively

Superclasses

<simple-vector>

Initialization Keywords

fill:An instance of <byte>. The default value of each element Defaults to 0.
size:An instance of <object>. The size of the vector Defaults to 0.

Description

An efficient vector for byte-storage.


<byte-character>[Constant]

An ASCII character.

Type

<byte-character-type>

Description

Characters of this type represent the ASCII character set (or extensions to ASCII such as ISO 8859). Note, in Gwydion compilers the <character> class is equivalent to Unicode characters.


assert[Function]

Signals an error if assumption is incorrect

Synopsis

assert (value) => ()

Parameters

valueAn instance of <object>. A boolean condition which should be #t

Return Values

None.

Description

This function signals an error if value is #f. Otherwise, it does nothing. In future Gwydion compilers, assert may be changed to a macro, which may or may not evaluate its argument exactly once.

Note: So, it goes to follow that users of assert should not have side-effects in the expression that is passed to assert because if we ever turn assertions off, that would mean the program runs differently in debug mode than it does in release mode.


one-of[Method]

Creates a class that is one of the supplied arguments.

Synopsis

one-of (#rest things) => (res)

Parameters

thingsInstances of <object>. The allowable classes

Return Values

resAn instance of <type>. The resulting type from the supplied classes.

Description

This function takes any number of objects, and returns the type that is the type-union of the singletons of those objects. For example, the expression

one-of(#"foo", #"bar", #"baz")

is equivalent to

type-union(singleton(#"foo"), singleton(#"bar"), singleton(#"baz"))

false-or[Method]

Creates a class that is either #f or the supplied class.

Synopsis

false-or (type) => (res)

Parameters

typeAn instance of <object>. The alternate type

Return Values

resAn instance of <type>. The resulting type-union.

Description

This function is useful in type expressions. It captures the common idiom of returning an instance of a particular type or the value #f. The expression

false-or(<integer>)

is equivalent to the expression

type-union(<integer>, singleton(#f))

Debugger Customizations

(A note on terminology: We use the term "debugger" here in the loose, Dylan sense of anything that handles an uncaught error. In Mindy, this debugger is indeed a full fledged debugger, but in other Gwydion compilers it may not be.)

The debugger uses the function report-condition to print conditions as error messages to users; for example, this is the function that implements the %S format-string directive for conditions. The debugger also uses the format function exported from the Cheap-io module to process format strings, and it prints directly to the Unix stdout. If any library that is used itself uses the Debugger-format library, then the debugger uses format from the Format library, which is shipped with Gwydion compilers. You can extend how the debugger prints conditions, change what formatting function it uses, and direct where debugger output goes with the following:


report-condition[open Generic]

Writes a condition to a stream.

Synopsis

report-condition (condition, stream) => ()

Parameters

conditionAn instance of <condition>.
streamAn instance of <object>. As we don't know the underlying output system, we'll accept any object.

Return Values

None.

Description

This is the function that is used to print condition variables as error messages to users. The internal format function used by Mindy uses report-condition for condition arguments to the %S format directive. The Format library's print-message method for conditions calls report-condition.

If you are writing a module that does no output but still provides report-condition methods, you should use condition-format to format output. Using condition-format makes your module more flexible for users of your module. If you call Cheap-IO's format, you'll be forced to write to only one destination, stdout, ignoring the stream argument. If you call the Format library's format function, then your module will require the Format, Print, and Streams libraries; therefore, users of your module may ultimately load these other libraries needlessly. Of course, if you want to make use of the extended functionality of the Format library's format control strings, then you only have one choice anyway, and there's no reason to use condition-format.

Report-condition has several supplied methods. The default method (on <condition>) simply prints the condition (not very descriptive). The <format-string-condtion> (of which the simple conditions are derived) method uses the supplied format-string to output information about the cause of the condition. The <type-error> method gives the expected and actual types, and the <abort> method just prints the supplied description.


condition-format[open Generic]

Serves as a firewall between the condition system and streams.

Synopsis

condition-format (stream, control-string, #rest arguments) => ()

Parameters

streamAn instance of <object>. As we don't know the underlying output system, we'll accept any object.
control-stringAn instance of <string>. The format string to print the condition.
argumentsInstances of <object>.

Return Values

None.

Description

This function serves as a firewall between the condition system and the Streams and Format libraries. Methods on report-condition should use condition-format to do their formatting. Users will generally use *debug-output* or *warning-output* for the stream argument, but this is not required.

Mindy supplies a method for when stream is #"Cheap-IO". The Gwydion Format library supplies a method for when stream is a subclass of <stream>. If you are implementing your own streams or format libraries, you will need to define a method on condition-format for your type of stream.


condition-force-output[open Generic]

Flushes the condition output stream.

Synopsis

condition-force-output (stream) => ()

Parameters

streamAn instance of <object>. As we don't know the underlying output system, we'll accept any object.

Return Values

None.

Description

Condition-force-output forces any pending output from stream's buffer to stream's destination. This function is invoked by the debugger after a condition has been reported and before it pauses for user input. Unless you are writing a debugger, you do not need to call condition-force-output yourself.

Mindy supplies a method for when stream is #"Cheap-IO". The Gwydion Format library supplies a method for when stream is a subclass of <stream>. If you are implementing your own streams or format libraries, you will need to define a method on condition-force-output for your type of stream.


*default-level*[Variable]

Gives how far down recursively to print

Type

<object>

Description

Default-handler for <warning> uses *warning-output* to print warning messages. This variable must be either a <stream> from the Streams library, or #"Cheap-IO" (the default). When this variable is #"Cheap-IO", the output goes to stderr.

Exiting Applications

The Extensions module exports the following functionality for controlling the exiting of applications:


exit[Method]

Causes the application to quit.

Synopsis

exit (#key exit-code) => (res)

Parameters

exit-code:An instance of <integer>. Defaults to 0.

Return Values

resAn instance of <never-returns>.

Description

Causes the process to exit with return code exit-code.


on-exit[Method]

Adds a function to be called just before quitting.

Synopsis

on-exit (function) => ()

Parameters

functionAn instance of <function>. A function to execute before quitting.

Return Values

None.

Description

Arranges for the exit function to call the argument function. The argument function must take no required arguments. Users may call on-exit multiple times to install more than one function for exit to call, but the order in which exit invokes the functions is undefined. Calling on-exit on the same function repeatedly installs that function multiple times.

Collections

The Extensions module exports the following <collection> functionality:


key-exists?[Method]

Returns #t if a key is in a collection.

Synopsis

key-exists? (coll, key) => (result, value)

Parameters

collAn instance of <collection>.
keyAn instance of <object>.

Return Values

resultAn instance of <boolean>.
valueAn instance of <object>. The associated datum for the key

Description

Return whether key is in coll. If the key is in the coll, then the second value is the element associated with key; otherwise, the second return value is #f.

Integers

Gwydion compilers have an abstract class <general-integer> which has two concrete subclasses, <integer> and <extended-integer>. <integer>s have a limited range of values, and <integer> arithmetic uses the computer's underlying integer facilities. <extended-integer>s can take on any value, and are similar to Common Lisp "bignums." Expressions involving <extended-integer>s produce <extendedinteger> results because <extended-integer>s are contagious. If an expression involving only <integer> values would produce a result that does not fit in an <integer>, then the Gwydion compiler will signal an overflow error. You can use the as function to convert back and forth between <integer>s and <extended-integer>s. As signals an error when converting an <extended-integer> to a <integer>, and the value does not fit in a <integer>.

The Extension module exports the following integer functionality:


<general-integer>[abstract Class]

Parent class of all integers.

Superclasses

<rational>

Initialization Keywords

None.

Description

The superclass of <integer> and <extended-integer>.


<extended-integer>[ Class]

An integer of any size.

Superclasses

<general-integer>

Initialization Keywords

None.

Description

A bignum is just a vector of digits.


$maximum-integer[Constant]

Highest computed integer for the architecture.

Type

<integer>

Description

Holds the largest positive <integer>.


$minimum-integer[Constant]

Lowest computed integer for the architecture.

Type

<integer>

Description

Holds the smallest negative <integer>.

Ratios

The Extensions module exports the following:


<ratio>[functional Class]

An exact fractional number.

Superclasses

<rational>

Initialization Keywords

numerator:An instance of <extended-integer>.
denominator:An instance of <extended-integer>. Guaranteed positive.

Description

A ratio has two slots: numerator and denominator. It is normalized so that it has a positive denominator, and the greatest common divisor of the numerator and the denominator is one. Ratios are never automatically converted to integers. For example, ratio(4, 2) would return 2/1.

A numeric operation involving two ratios produces a normalized ratio result. A numeric operation involving a ratio and an integer produced a normalized ratio result. A numeric operation involving a ratio and a float produces a float result.


ratio[Method]

Makes a ratio from to integers.

Synopsis

ratio (num, denom) => (res)

Parameters

numAn instance of <extended-integer>.
denomAn instance of <extended-integer>.

Return Values

resAn instance of <ratio>.

Description

This function makes a ratio from the two integers.