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
assert
should not have side-effects in the expression that is passed toassert
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
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
format
function used by Mindy uses report-condition for condition arguments to the%S
format directive. TheFormat
library'sprint-message
method for conditions callsreport-condition
.If you are writing a module that does no output but still provides
report-condition
methods, you should usecondition-format
to format output. Usingcondition-format
makes 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 theFormat
library'sformat
function, then your module will require theFormat
,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 theFormat
library's format control strings, then you only have one choice anyway, and there's no reason to usecondition-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
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
Streams
andFormat
libraries. Methods onreport-condition
should usecondition-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 GwydionFormat
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 oncondition-format
for 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-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 callcondition-force-output
yourself.Mindy supplies a method for when stream is
#"Cheap-IO"
. The GwydionFormat
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 oncondition-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 theStreams
library, 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
exit
function to call the argument function. The argument function must take no required arguments. Users may callon-exit
multiple times to install more than one function forexit
to call, but the order in which exit invokes the functions is undefined. Callingon-exit
on 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:
numerator
anddenominator
. 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.