| Gwydion Dylan Library Reference Guide | ||
|---|---|---|
| Prev | Chapter 2. The Dylan Library and Gwydion Dylan Extensions | Next |
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.
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 to0.size:An instance of <object>. The size of the vector Defaults to0.
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
value An 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
assertshould not have side-effects in the expression that is passed toassertbecause 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
things Instances of <object>. The allowable classes
Return Values
res An 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
type An instance of <object>. The alternate type
Return Values
res An 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 expressionfalse-or(<integer>)is equivalent to the expression
type-union(<integer>, singleton(#f))
(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
condition An instance of <condition>.stream An 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
formatfunction used by Mindy uses report-condition for condition arguments to the%Sformat directive. TheFormatlibrary'sprint-messagemethod for conditions callsreport-condition.If you are writing a module that does no output but still provides
report-conditionmethods, you should usecondition-formatto format output. Usingcondition-formatmakes your module more flexible for users of your module. If you callCheap-IO'sformat, you'll be forced to write to only one destination,stdout, ignoring the stream argument. If you call theFormatlibrary'sformatfunction, then your module will require theFormat,Streamslibraries; 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 theFormatlibrary's format control strings, then you only have one choice anyway, and there's no reason to usecondition-format.
Report-conditionhas 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
stream An instance of <object>. As we don't know the underlying output system, we'll accept any object.control-string An instance of <string>. The format string to print the condition.arguments Instances of <object>.
Return Values
None.
Description
This function serves as a firewall between the condition system and the
StreamsandFormatlibraries. Methods onreport-conditionshould usecondition-formatto 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 GwydionFormatlibrary 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 oncondition-formatfor your type of stream.
condition-force-output | [open Generic] |
Flushes the condition output stream.
Synopsis
condition-force-output (stream) => ()
Parameters
stream An instance of <object>. As we don't know the underlying output system, we'll accept any object.
Return Values
None.
Description
Condition-force-outputforces 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 callcondition-force-outputyourself.Mindy supplies a method for when stream is
#"Cheap-IO". The GwydionFormatlibrary 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 oncondition-force-outputfor 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 theStreamslibrary, or#"Cheap-IO"(the default). When this variable is#"Cheap-IO", the output goes tostderr.
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 to0.
Return Values
res An 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
function An instance of <function>. A function to execute before quitting.
Return Values
None.
Description
Arranges for the
exitfunction to call the argument function. The argument function must take no required arguments. Users may callon-exitmultiple times to install more than one function forexitto call, but the order in which exit invokes the functions is undefined. Callingon-exiton the same function repeatedly installs that function multiple times.
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
coll An instance of <collection>.key An instance of <object>.
Return Values
result An instance of <boolean>.value An 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.
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>.
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:
numeratoranddenominator. 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 return2/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
num An instance of <extended-integer>.denom An instance of <extended-integer>.
Return Values
res An instance of <ratio>.
Description
This function makes a ratio from the two integers.