Introduction

In the process of working with Dylan, the Gwydion Project has come up with numerous extensions to the Dylan language. Some of them form entire libraries, like the Collection-Extensions and String-Extensions libraries. Others have been added to the Dylan library, in such modules as Extensions and System.

We continue to make no claims about future support for our extensions. However, some extensions are more likely than others to make it into our future compilers. This file documents those extensions which we think will be included in our compiler's Dylan library.

Extensions which go in separate libraries are documented in their own files; extensions which are part of the Mindy Dylan library but which have a less certain future are documented in the Mindy documentation.

For the remainder of this chapter, we shall refer to "Gwydion compilers" as a shorthand for "Mindy and other Dylan compilers that the Gwydion Project may write." It is not meant as a guarentee that all future Gwydion releases will support these extensions.

Specific Gwydion compilers may support extensions not listed here; see their documentation for details.

Modules of the Dylan Library

In addition to containing the Dylan module, the Dylan library contains a variety of modules which provide extensions. Gwydion compilers export the following modules from the Dylan library:

The Dylan Module

Whenever possible, we have tried to keep the Dylan module pristine and unextended, prefering to add our extensions to separate modules or libraries. However, this is not always possible, particularly when it involves extending the behavior of a function or macro that is exported from the Dylan module. Currently, Gwydion compilers support these extensions to the Dylan module as described below:

• Gwydion compilers support keyed-by clauses in for statements. The format of such a clause is

  var keyed-by key in collection

  The var is bound to each element in collection, and key is bound to the element's key value.

• Gwydion compilers supports using clauses in for statements. The format of such a clause is

  var in collection using protocol

  The protocol will be used instead of forward-iteration-protocol. The protocol argument must be a variable name, not an expression. These using clauses may be used together with keyed-by:

  var keyed-by key in collection using protocol

• Gwydion compilers have an additional type of top level definition, define function, which creates a constant binding in the current module and initializes it to a new function. The usage of define function usage is similar to that of define method. The following is an example:

  define function cube (x)
    x * x * x;
  end function cube;

  A similar result might be had by writing

  define constant cube = method (x)
                           x * x * x;
                         end method;

  or

  define method cube (x)
    x * x * x;
  end method cube;

• Gwydion compilers supports subclass specializers via the limited function. A subclass specializer causes a method to be invoked whenever the generic function was called on a value that is the specified class or any subclass of the specified class. The method is never invoked on a value that is an instance (direct or indirect) of the specified class, only when the value is a subclass of the specified class. The following is an example:

  define method make
      (result-class :: limited(<class>, subclass-of: <my-class>));
    let x = next-method();
    do-special-logging-or-something(x);
    x;
  end method;

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.

The System Module

The Introspection Module

The Cheap-IO Module

Discussing error conditions

This document uses two special terms in discussions of error conditions.

When we say that something is an error, we mean that the result is undefined. In particular, we do not mean that a Streams implementation must signal an error condition; that is the implementor's choice. So, for instance, the following text means only that the result of using unread-element in the case described is undefined:

It is an error to apply unread-element to an element that is not the element most recently read from the stream.

Only when we specifically mention signaling do we mean that a Streams implementation must signal an error condition. Note that we may not, in such a case, say exactly which error condition must be signaled; if we do not say so, the choice is again up to the implementor. In the following text, for instance, we state that an implementation must signal an error, but we do not say what error must be signaled:

When position is a <stream-position>, if it is invalid for some reason, this function signals an error.

By contrast, the following text says exactly which error must be signaled:

If the end of the stream is encountered and no value was supplied for on-end-of-stream, read-element signals an <end-of-stream-error> condition.

Goals of the Library

The Dylan Streams library aims to provide:

• A generic, easy-to-use interface for streaming over sequences and files. The same high-level interface for consuming or producing is available irrespective of the type of stream, or the types of the elements being streamed over.

• Efficiency, especially for the common case of file I/O.

• Access to an underlying buffer management protocol.

• An extensible framework. Other areas of functionality that require a stream interface should be easy to integrate with the library.

The proposal presents the design of a Streams library that meets these goals using Dylan's built-in sequences and a buffered disk file interface.

The proposal does not address a number of related issues, including:

• A standard object-printing package such as Smalltalk's printOn: or Lisp's print-object, or a formatted printing facility such as Lisp's format. Additional libraries are expected to provide these facilities.

• General object dumping and loading.

• A comprehensive range of I/O facilities for using memory-mapped files, network connections, and so on. Such facilities should be easy to add to the Streams library because of its extensible framework.

• An interface for naming files.

• An interface to operating system functionality, such as file renaming or deleting operations.

Concepts

A stream provides sequential access to an aggregate of data, such as a Dylan sequence or a disk file. Streams grant this access according to a metaphor of reading and writing: elements can be read from streams or written to them.

Streams are represented as Dylan objects, and all are general instances of the class <stream>, which the Streams library defines.

We say that a stream is established over the data aggregate. Hence, a stream providing access to the string "hello world" is said to be a stream over the string "hello world".

Streams permitting reading operations are called input streams. Input streams allow elements from the underlying data aggregate to be consumed. Conversely, streams permitting writing operations are called output streams. Output streams allow elements to be written to the underlying data aggregate. Streams permitting both kinds of operations are called input-output streams.

The library provides a set of functions for reading elements from an input stream. These functions hide the details of indexing, buffering, and so on. For instance, the function read-element reads a single data element from an input stream.

The following expression binds stream to an input stream over the string "hello world":

let stream = make(<string-stream>, contents: "hello world");

The first invocation of read-element on stream returns the character 'h', the next invocation 'e', and so on. Once a stream has been used to consume all the elements of the data, the stream is said to be at its end. This condition can be tested with the function stream-at-end?. The following code fragment applies function to all elements of the sequence:

let stream = make(<sequence-stream>, contents: seq);
while (~stream-at-end?(stream)) 
	function(read-element(stream));
end;

When all elements of a stream have been read, further calls to read-element result in the <end-of-stream-error> condition being signalled. An alternative end-of-stream behavior is to have a distinguished end-of-stream value returned. You can supply such an end-of-stream value as a keyword argument to the various read functions; the value can be any object. Supplying an end-of-stream value to a read function is more efficient than asking whether a stream is at its end on every iteration of a loop.

The library also provides a set of functions for writing data elements to an output stream. Like the functions that operate upon input streams, these functions hide the details of indexing, growing an underlying sequence, buffering for a file, and so on. For instance, the function write-element writes a single data element to an output stream.

The following forms bind stream to an output stream over an empty string and create the string "I see!", using the function stream-contents to access all of the stream's elements.

let stream = make(<byte-string-stream>, direction: #"output");
write-element(stream, 'I');
write-element(stream, ' ');
write(stream, "see");
write-element(stream, '!');
stream-contents(stream);

Calling write on a sequence has the same effect as calling write-element on all the elements of the sequence. However, it is not required that write be implemented directly in terms of write-element; it might be implemented more efficiently, especially for buffered streams.

Some streams are positionable; that is, they permit random access to their elements. Postionable streams allow you to set the position at which the stream will be accessed by the next operation. The following example uses positioning to return the character 'w' from a stream over the string "hello world":

let stream = make(<string-stream>, contents: "hello world");
stream-position(stream) := 6;
read-element(stream);

The following example returns a string, but the contents of the first ten characters are undefined:

let stream = make(<string-stream>, direction: #"output");
adjust-stream-position(stream, 10); 
write(stream, "whoa!");
stream-contents(stream);

You can request a sequence containing all of the elements of a positionable stream by calling stream-contents on it. The sequence returned never shares structure with any underlying sequence that might be used in future by the stream. For instance, the string returned by calling stream-contents on an output <string-stream> will not be the same string as that being used to represent the string stream.

When making an input <string-stream>, you can cause the stream to produce elements from any subsequence of the supplied string. For example:

read-to-end(make(<string-stream>, 
                 contents: "hello there, world",
                 start: 6, 
                 end: 11));

This example evaluates to "there". The interval (start, end) includes the index start but excludes the index end. This is consistent with standard Dylan functions over sequences, such as copy-sequence. The read-to-end function is one of a number of convenient utility functions for operating on streams and returns all the elements up to the end of the stream from the stream's current position.

Streams, growing sequences, and object identity

When writing to output streams over sequences, Dylan may from time to time need to grow the underlying sequence that it is using to represent the stream data.

Consider the example of an output stream instantiated over an empty string. As soon as a write operation is performed on the stream, it is necessary to replace the string object used in the representation of the string stream. As well as incurring the cost of creating a new string, the replacement operation can affect the integrity of other references to the string within the program.

To guarantee that alias references to a sequence used in an output <sequence-stream> will have access to any elements written to the sequence via the stream, supply a <stretchy-vector> to make. A stream over a stretchy vector will use the same stretchy vector throughout the stream's existence.

For example:

let sv = make(<stretchy-vector>);
let stream = make(<sequence-stream>, 
                  contents: sv, 
                  direction: #"output");
write(stream, #(1, 2, 3, 4, 5, 6, 7, 8, 9));
write(stream, "ABCDEF");
values(sv, stream-contents(stream));

The example returns two values. Each value is the same (\==) stretchy vector:

#[1, 2, 3, 4, 5, 6, 7, 8, 9, 'A', 'B', 'C', 'D', 'E', 'F']

If a stretchy vector is not supplied, the result is different:

let v = make(<vector>, size: 5);
let stream = make(<sequence-stream>,
                  contents: v, 
                  direction: #"output");
write(stream, #(1, 2, 3, 4, 5, 6, 7, 8, 9));
write(stream, "ABCDEF");
values(v, stream-contents(stream));

This example returns as its first value the original vector, whose contents are undefined, but the second value is a new vector:

#[1, 2, 3, 4, 5, 6, 7, 8, 9, 'A', 'B', 'C', 'D', 'E', 'F']

This difference arises because the output stream in the second example does not use a stretchy vector to hold the stream data. A vector of at least 15 elements is necessary to accommodate the elements written to the stream, but the vector supplied, v, can hold only 5. Since the stream cannot change v's size, it must allocate a new vector each time it grows.

Streams Reference

The exported streams class heterarchy is as follows:

Except for the classes <stream>, <buffered-stream>, and <positionable-stream>, these are instantiable classes.

Streams, in general, have a host of operations for walking over or changing collections, and file streams have some specific issues of their own. Therefore, we will cover the general stream classes and operations in the Section called General Stream Classes and Operations, and file streams in the Section called File Stream Classes and Operations.

The Standard-IO Library

The standard-IO module of the standard-IO library exports three names for the standard input, output, and error streams.

The <stream> instance corresponding to the standard error.

Type

<stream>

Description

The standard error <stream>. This usually represents the terminal; however most UNIX-like operating systems permit the standard error stream to be redirected at the command line.

The <stream> instance corresponding to the standard input.

Type

<stream>

Description

The standard input <stream>. Usually, this stream reads from the terminal for its data; however most UNIX-like operating systems permit the standard input stream to be redirected at the command line.

The <stream> instance corresponding to the standard output.

Type

<stream>

Description

The standard output <stream>. This usually represents the terminal (just like *standard-error* ); however most UNIX-like operating systems permit the standard output stream to be redirected at the command line.

The Format Module

Format a string and write it to a stream.

Synopsis

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

Parameters

stream	An instance of <stream>.
control-string	An instance of <string>.
args	Instances of <object>. The objects to substitute for the format fields.

Return Values

None.

Description

The format function takes a control string, formats according to the format directives embedded in the string, and then writes the result to the stream argument.

The format codes accepted by format are described in the format directives section.

Format a string and write it to a stream.

Synopsis

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

Parameters

stream	An instance of <stream>.
control-string	An instance of <string>.
args	Instances of <object>. The objects to substitute for the format fields.

Return Values

None.

Description

The default format method, specialized on the <stream> class.

Process a format-string and return the result as another string.

Synopsis

format-to-string ( control-string , #rest args ) => ( result )

Parameters

control-string	An instance of <string>.
args	Instances of <object>. The objects to substitute for the format fields.

Return Values

result

An instance of <string>.

Description

This function effectively calls format and returns the result as a string.

This method is called to format objects for the "%s" and "%c" format operators, in a form suitable for human readers.

Synopsis

print-message (object, stream) => ()

Parameters

object	An instance of <object>.
stream	An instance of <stream>.

Return Values

None.

Description

Prints object to stream. This generic function is intended to define the human-readable printing behavior of a Dylan object, as opposed to their representation as literal syntax. Calling this function on <condition> should result in a error message, rather than the name of the instance and its class, for example. (Contrast this behavior with the print function in the Print library.)

Predefined methods exist for the <string> , <character> , <condition> , and <symbol> classes.

Format Directives

The format directives are described below:

Directive -- Argument Type -- Textual Format

• %d -- <integer> -- decimal number

• %b -- <integer> -- binary number

• %o -- <integer> -- octal number

• %x -- <integer> -- hexadecimal number

• %c -- <character> -- character (with no quotes)

• %s -- <string> -- string (with no quotes)

• %s -- <condition> -- condition message (with no quotes)

• %= -- <object> -- unspecified, but works with any object

• %% -- none -- literal %

• %m -- <function> -- a function that accepts the stream as an argument and performs user-defined operations on the stream

The last format directive (%m) is specific to GwydionDylan. See the below examples for using some of the format directives.

Hello, my name is Doug Auclair, and I'm 33 years old.
      

format(*standard-output*, "Hello, my name is %s, and I'm %d years old.%c",
       "Doug Auclair", 33, '\n');
      

format(*standard-output*, "Hello, my name is %s, and I'm %d years old.\n",
       "Doug Auclair", 33);
      

format(*standard-output*, "Hello, my name is %s, and I'm %d years old.%m",
       "Doug Auclair", 33, new-line);
        

Hello, my name is Doug Auclair, and as of
now, November 17, 2000 09:28 PM, I'm 33 years old.
        

define function human-readable-time(stream :: <stream>,  
                                    time :: <decoded-time>)
 => ()
    format-time(stream, "%B %d, %Y %H:%M %p", time);
end function human-readable-time;
        

format(*standard-output*, "Hello, my name is %s, and as of\n"
                          "now, %m, I'm %d years old\n",
       "Doug Auclair", 
       rcurry(human-readable-time, get-current-time(timezone: 5 * 3600)),
       33);
        

The Format-Out Module

The Format-Out module exports one function format-out.

Formats arguments to *standard-output*.

Synopsis

format-out (control-string, #rest args) => ()

Parameters

control-string	An instance of <string>.
args	Instances of <object>. The objects to substitute for the format fields.

Return Values

None.

Description

Performs

apply(format, *standard-output*, control-string, args);

Print Module

The Print module provides ways to print objects. It also provides printing properties (depth, circular, etc), and inspection of those properties.

Prints an object on a stream

Synopsis

print (object, stream, #key level, length, circle?, pretty?) => ()

Parameters

object	An instance of <object>.
stream	An instance of <stream>.
level:	An instance of <integer-or-false-or-not-supplied>. Holds the maximum depth to which the user wants recursive printing to go. Defaults to $not-supplied.
length:	An instance of <integer-or-false-or-not-supplied>. Holds the maximum number of elements the user wants a sequence to be printed. This does not apply to some sequences, such as strings. Defaults to $not-supplied.
circle?:	An instance of <boolean-or-not-supplied>. Defines print behavior when printing a circular list Defaults to $not-supplied.
pretty?:	An instance of <boolean-or-not-supplied>. Whether the user wants pretty printing. Defaults to $not-supplied.

Return Values

None.

Description

Prints object to stream according to the print request formed by the keyed arguments. A first call to print creates a printing stream to represent the print request, and recursive calls to print on this printing stream process the keyed arguments differently (see below). There are inspection functions for querying the print request (see their descriptions below). When print actually prints an object, it calls print-object. Though the inspection functions for querying the print request allow you to inspect any parameter of the print request, print-object methods should only need to call print-length. All other aspects of the print request are handled by print. There is one exception which is described in the PPrint module (pretty-printing).

Level controls how deep into a nested data structure to print. The value #f indicates that there is no limit. The default, *default-level*, has no effect on recursive calls to print. Recursive calls to print may change the value of print-level explicitly, but print always uses a value to ensure the print request formed by the first call to print is never exceeded. For example, if a first call to print set the level to 5, and while at a depth of 3, a recursive call specified a level of 4, the recursive call would only descend 2 more levels, not 4.

Length controls how many elements of a sequence to print before printing ellipsis notation (...). The value #f indicates that there is no limit. The print-length control can be interpreted loosely by some print-object methods to control how many elements of any kind of object to print; for example, the default <object> method might regard print-length to determine how many slot-name/value pairs to print. The default, *default-length*, has no effect on recursive calls to print. Recursive calls to print may change the value of print-length explicitly, but they may only decrease the value, never increase it.

Circle? indicates whether printing should check all subcomponent references to make sure the printing process does not infinitely recurse through a data structure. Circular printing also tags objects that occur more than once when they are first printed, and later occurrences are printed as a reference to the previously emitted tag. The default, *default-circle?*, has no effect on recursive calls to print. If print-circle? is already #t, then it remains #t throughout all recursive calls. If print-circle? is #f, then recursive calls to print can change the value to #t; however, when printing exits the dynamic scope of the call that changed the value to #t, the value reverts to #f. If the original call to print specifies circle? as #f, and dynamically distinct recursive calls turn circular printing on and off, all output generated while circular printing was on shares the same tagging space; that is, if #1# is printed twice, once from each of two distinct recursive calls to print, then each #1# is guaranteed to signify the same \== object.

Pretty? indicates whether printing should attempt to insert line breaks and indentation to format objects according to how programmers tend to find it easier to read data. The default, *default-pretty?*, has no effect on recursive calls to print. If print-pretty? is already #t, then it remains #t throughout all recursive calls. If print-pretty? is #f, then recursive calls to print can change the value to #t; however, when printing exits the dynamic scope of the call that changed the value to #t, the value reverts to #f.

The default way to print objects

Synopsis

print-object (object, stream) => ()

Parameters

object	An instance of <object>.
stream	An instance of <stream>.

Return Values

None.

Description

Users extend print's ability to print various objects by adding methods to the print-object function. When print actually prints an object, it calls print-object. Users should never call print-object directly.

Provides the printed object representation for print and for the "%=" format directive (see the Section called Format Directives in Chapter 5). Default print-object methods exist for instances of <object>, <character>, <string>, <list>, <vector>, <sequence>, <array>, <table>, <range>, <function>, <singleton>, <limited-integer>, <union>, <symbol>, <general-integer>, <integer>, <ratio>, <single-float>, <double-float>, <extended-float>, <class>, and for #t and #f.

Users may choose to modify the printed representation in two ways: override the print-object method for that instance's type, or provide a printing function to the "%m" directive for format or format-out.

Creates a string that contains a printed object representation

Synopsis

print-to-string (object, #key level, length, circle?, pretty?) => (result)

Parameters

object	An instance of <object>.
level:	An instance of <integer-or-false-or-not-supplied>. Holds the maximum depth to which the user wants recursive printing to go. Defaults to $not-supplied.
length:	An instance of <integer-or-false-or-not-supplied>. Holds the maximum number of elements the user wants a sequence to be printed. This does not apply to some sequences, such as strings. Defaults to $not-supplied.
circle?:	An instance of <boolean-or-not-supplied>. Defines print behavior when printing a circular list Defaults to $not-supplied.
pretty?:	An instance of <boolean-or-not-supplied>. Whether the user wants pretty printing. Defaults to $not-supplied.

Return Values

result

An instance of <byte-string>.

Description

Calls print to produce output according to the print request formed by the keyed arguments and returns the output as a string.

The above print functions use or set the below exported variables to accomplish their work (#f (the default value of all these variables) indicates there is no bounds for the variable):

Gives how far down recursively to print

Type

false-or(<integer>)

Description

If a number is given, print prints a # when it reached the level.

How many elements to print of a sequence

Type

false-or(<integer>)

Description

If a number is given, print prints a ... to indicate that it reached the maximum number of printable elements.

What to do for circular lists

Type

<boolean>

Description

If on, prints identical objects as, e.g.: #1#

Formats outputted object

Type

<boolean>

Description

If on, prints object indented with proper line breaks, according to the formatting specifications given to pprint-logical-block.

The below functions give printing information on <stream>s. It seems, however, that these functions are neither used nor implemented, as they all give #f or 0 as their response, no matter the <stream>.

Always returns #f

Synopsis

print-length (stream) => (length)

Parameters

stream

An instance of <stream>.

Return Values

length

An instance of false-or(<integer>).

Description

Returns the current value for the print request. See the print function for details.

Always returns #f

Synopsis

print-level (stream) => (level)

Parameters

stream

An instance of <stream>.

Return Values

level

An instance of false-or(<integer>).

Description

Returns the current value for the print request. See the print function for details. Users should have little use for this function because print takes care to call print-object only when the print level has not been exhausted.

Always returns 0

Synopsis

print-depth (stream) => (depth)

Parameters

stream

An instance of <stream>.

Return Values

depth

An instance of <integer>.

Description

Returns the current depth to which printing has descended into the object on which print was originally called. Print takes care to call print-object only when the print depth has not been exhausted.

Always returns #f

Synopsis

print-pretty? (stream) => (pretty?)

Parameters

stream

An instance of <stream>.

Return Values

pretty?

An instance of #f.

Description

Returns whether pretty printing is on. Users should have little use for this function (see the Section called PPrint Module).

Always returns #f

Synopsis

print-circle? (stream) => (circle?)

Parameters

stream

An instance of <stream>.

Return Values

circle?

An instance of #f.

Description

Returns whether circular printing is on. Users should have little use for this function because print takes care to detect circularities, tag multiply referenced objects, and emit tags rather than descending into objects to repeatedly print them.

PPrint Module

The Print library implements most of the pretty printing technology described by Richard C. Waters in Common Lisp The Language, second edition. The interface is slightly different because Mindy does not have macros. This section only summarizes the pretty printing functionality to provide a quick reference for users of the Print library, and readers should refer to the Common Lisp manual for more details.

When writing print-object methods, users can ignore whether pretty printing is in effect. If you write your print-object method using pretty printing functions, then when pretty printing is in effect, the output will be pretty printed. When pretty printing is not in effect, your method will produce output as though you had not written it to use pretty printing. All print-object methods that are written to do pretty printing must call the pretty printing functions within the dynamic scope of a call to pprint-logical-block; otherwise, the pretty printing functions are no-ops.

The length of a single line

Type

<integer>

Description

This is the line length used by the pretty printer to determine how much output will fit on a single line. It defaults to 80.

Controls miser mode for pretty printing

Type

false-or(<integer>)

Description

Whenever a logical block (see pprint-logical-block) begins in a column of output that is greater than *default-line-length* - *print-miser-width*, then pretty printing is in miser mode. The value must be an integer or #f (the default). #f indicates that the pretty printer should never enter miser mode.

Stream used for pretty printing.

Superclasses

<buffered-stream>

Initialization Keywords

target:	An instance of <stream>. The stream where the output is finally going to go.
line-length:	An instance of <column>. The line length for this stream (0 minimum). Defaults to *default-line-length*.
column:	An instance of <column>. The column the first character in the buffer will appear in. Normally zero, but if we end up with a very long line with no breaks in it we might have to output part of it. Then this will no longer be zero. Defaults to 0.

Description

This is a working class for pretty-printing objects. Use an instance of this class when doing a great deal of pretty printing.

Start a logical block, creating a pretty-stream if necessary.

Synopsis

pprint-logical-block (stream, #key column, prefix, per-line-prefix, body, suffix) => ()

Parameters

stream	An instance of <stream>.
column:	An instance of <integer>.
prefix:	An instance of <byte-string>.
per-line-prefix:	An instance of <byte-string>.
body:	An instance of <function>.
suffix:	An instance of <byte-string>.

Return Values

None.

Description

This function groups printing into a logical block. The logical block provides boundaries for new levels of indentation, affects #"linear" newlines, and so on. Prefix is a string to print at the beginning of the logical block. The blocks indentation is automatically set to be one character position greater than the column in which prefix ends. Alternatively, per-line-prefix is a string to print on every line of the logical block. This function signals an error if it is called with both prefix and per-line-prefix supplied as non-#f. Suffix is a string to print at the end of the logical block. Column advises the pretty printer as to the current column of the output stream (defaults to zero). The column argument may be ignored entirely by some methods, and it may be ignored in some cases by methods that can better determine the stream's current output column.

Body must be a <function> that can take one argument, and this argument is a <stream>. The body function should use the stream argument passed to it; the body function should not close over the stream argument to pprint-logical-block. Pprint-logical-block wraps stream with a pretty printing stream when stream is any other kind of stream. If stream is already a pretty printing stream, then the body function is called on stream.

All print-object methods that are written to do pretty printing must call the other pretty printing functions within the dynamic scope of a call to pprint-logical-block; otherwise, the pretty printing functions are no-ops.

Output a conditional newline of some kind. If called on a regular stream, ignore it.

Synopsis

pprint-newline (kind, stream) => ()

Parameters

kind	An instance of <pretty-newline-kind>.
stream	An instance of <stream>.

Return Values

None.

Description

This function announces a conditional newline to the pretty printer. The pretty printer emits a newline depending on the kind and the state of the pretty printer's current line buffer. The kind argument has roughly the following meanings:

• #"fill": Emit a newline if the current section of output does not fit on one line.

• #"linear": Emit a newline if any #"linear" newline in the current section needs to be emitted. That is, if a current section of output cannot fit on one line, and any one of the #"linear" newlines in the section needs to be emitted, then emit them all.

• #"miser": Emit a newline as if it were a #"linear" newline, but only when miser mode is in effect. Miser style is in effect when a logical block starts past a particular column of output.

• #"mandatory": Emit a newline always. Establish that any containing sections cannot be printed on a single line so that #"linear" and #"miser" newlines will be emitted as appropriate.

Change the indentation. If called on a regular stream, just ignore it.

Synopsis

pprint-indent (relative-to, n, stream) => ()

Parameters

relative-to	An instance of <indentation-kind>.
n	An instance of <integer>.
stream	An instance of <stream>.

Return Values

None.

Description

This function specifies the indentation to use within the current logical block. When relative-to is #"block", then pprint-indent sets the indentation to the column of the first character of the logical block plus n. When relative-to is #"current", then pprint-indent sets the indentation to the current column plus n.

Output a tab. If called on a regular stream, ignore it.

Synopsis

pprint-tab (kind, colnum, colinc, stream) => ()

Parameters

kind	An instance of <tab-kind>.
colnum	An instance of <integer>.
colinc	An instance of <integer>.
stream	An instance of <stream>.

Return Values

None.

Description

This function announces a tab to the pretty printer. Colnum and colinc have meaning based on the value of kind:

• #"line": Tab to output column colnum. If the output is already at or beyond colnum, then add colinc to colnum until printing can continue at a column beyond the end of the output already on the line.

• #"line-relative": Output colnum spaces. Then output enough spaces to tab to a column that is a multiple of colinc from the beginning of the line.

• #"section": This is similar to #"line", but column counting is relative to the beginning of the current section rather than the beginning of the line.

• #"section-relative": This is similar to #"line-relative", but column counting is relative to the beginning of the current section rather than the beginning of the line.

Introduction

The various modules in this library contain a few new types and operations which are compatible with the collection types specified in the Dylan Reference Manual , but which are not part of that specification.

It is to be expected that more collection types will appear in time, and they will likely be added to this library. This may also result in reorganizations which could force incompatible changes to the existing modules. We hope to minimize such imcompatibilities and, when forced to them, will include sufficient information to facilitate conversion of existing code.

Collection-extensions exports these modules:

• self-organizing-list Provides "self-organizing lists". These explicit key collections provide roughly the semantics of hash tables, but use a probabilistic implementation which provides O(n) worst case performance but can provide very fast constant time access in the best case.

• subseq Provides "subsequences", which represent an aliased reference to some part of an existing sequence. These are analogous to slices (in Ada or Perl) or displaced arrays (in Common Lisp). Subsequences are themselves subclasses of <sequence>, and can therefore be passed any <collection> or <sequence> operation.

• vector-search Provides a small assortment of specialized operations for searching and modifying <vector>s. These operations are analogous to existing collection operations but provide keywords and efficiency improvements which are meaningful only within the more limited domain.

The Collections-Extensions Library also has some additional modules added by the GwydionDylan Maintainers. These modules are:

• heap was supposed to implement a priority queue, but because of conflicts with <deque> methods, heap is currently empty.

• sequence-diff implements the Unix diff utility algorithm

• Sequence-Utilities provides useful methods on collections, written by Matthias Hölzl.

Module self-organizing-list

The "Self Organizing List" is a poor man's hash table. More precisely, <self-organizing-list> is a subclass of <mutable-explicit-key-collection> and <stretchy-collection> for which addition and retrieval are both linear in the worst case, but which use a probabilistic strategy which yields nearly constant time in the best case.

Because they have a very low overhead, self-organizing lists may provide better peformance than hash tables in cases where references have a high degree of temporal locality. They may also be useful in situations where it is difficult to create a proper hash function.

Instantiate <self-organizing-list>s with

make(<self-organizing-list>, test: test)

Test is expected to be an equality function. In particular, it is expected to satisfy the identity and transitivity requirements as described in the Dylan Reference Manual . If not specified, test defaults to \==.

Module subseq

<Subsequence> is a new subclass of <sequence>. A subsequence represents an aliased reference to some part of an existing sequence. Although they may be created by make (with required keywords source:, start: and end:) on one of the instantiable subclasses, they are more often created by calls of the form

subsequence(sequence, start: 0, end: 3)

where start: and end: are optional keywords which default to the beginning and end, respectively, of the source sequence. No other new operations are defined for subsequences, since all necessary operations are inherited from <sequence>.

Because subsequences are aliased references into other sequences, several properties must be remembered:

• The contents of a subsequence are undefined after any destructive operation upon the source sequence.

• Destructive operations upon subsequences may be reflected in the source. The results of reverse! and sort! should be expected to affect the source sequence for vector subsequences.

If the source sequences are instances of <vector> or <string>, then the implementation will use subclasses of <subsequence> which are also subclasses of <vector> or <string>.

Efficiency notes:

• The implementation tries to insure that subsequences of subsequences can be accessed as efficiently as the original subsequence. (For example, the result of

  subsequence(subsequence(source, start: 1), start: 2)

  would produce a subsequence identical to the one produced by

  subsequence(source, start: 3)

• Vector subsequences, like all other vectors, implement constant time element access.

• Non-vector subsequences may take non-constant time to create, but will provide constant-time access to the first element. This should produce the best performance provided some element of the subsequence is accessed at least once.

Module vector-search

The vector-search module provides basic search and replace capabilities upon restricted subsets of <sequence> -- primarily <vector>. Exploiting the known properties of these types yields substantially better performance than can be achieved for sequences in general.

Find the index of first element of a <vector>

Synopsis

find-first-key (seq, pred?, #key start, end, failure) => ()

Parameters

seq	An instance of <vector>.
pred?	An instance of <object>. A <function> that returns #t for a matching condition.
start:	An instance of <object>. From which element to start the search Defaults to 0.
end:	An instance of <object>. Where to end the search
failure:	An instance of <object>. Returned if no match found

Return Values

None.

Description

Find the index of first element (after start but before end) of a vector which satisfies the given predicate. If no matching element is found, return failure. The defaults for start, end and failure are, respectively, 0, size(vector), and #f. This function is like find-key, but accepts start: and end: rather than skip:.

This is like find-first-key, but goes backward from end.

Synopsis

find-last-key (seq, pred?, #key start, end, failure) => ()

Parameters

seq	An instance of <vector>.
pred?	An instance of <object>. A <function> that returns true for a matching condition
start:	An instance of <object>. From which element to start the search Defaults to 0.
end:	An instance of <object>. Where to end the search
failure:	An instance of <object>. Returned if no match found

Return Values

None.

Description

See the description for find-first-key.

Module Sequence-Utilities

Sequence-Utilities, written by Matthias Hölzl, provides common or oft-used operations performed on <sequence>s. The whole module is rather Lispy in flavor, and has the feel of an elegant hack by the way functions use predicate functions to manipulate lists.

The table-extensions Module

This library contains a number of useful additional table classes, and a number of functions that could be useful in constructing your own table classes.

Implements a <table> class, keyed by strings keyed without regard for case.

Superclasses

<value-table>

Initialization Keywords

None.

Description

<case-insensitive-string-table> implements a <table> class whose keys are instances of <string> . However, instead of using \= for the equivalence relation, strings which are the same modulo case are considered equivalent.

Note that the case-insensitivity is true in general only for English strings -- non-English characters have their case "normalized" by subtracting the difference in integer code for the character 'a' and 'A'. This works only for ASCII and Unicode, and only for English.

Implements a class which compares keys using \= .

Superclasses

<table>

Initialization Keywords

None.

Description

<equal-table> implements a <table> class whose keys are compared with \= rather than \== . So for example, two instances of list that don't have object identity, but did contain references to the same object, would be considered equivalent keys by <equal-table> .

The type of hash states.

Superclasses

None.

Initialization Keywords

None.

Description

<hash-state> is the type of the hash state returned as the second value of hash functions. For example, $permanent-hash-state is of type <hash-state> .

A <table> class keyed by strings.

Superclasses

<value-table>

Initialization Keywords

None.

Description

This class implements a <table> class that is keyed by \= equal <string> instances.

Intended as the abstract superclass of user-defined tables.

Superclasses

<table>

Initialization Keywords

None.

Description

This class is intended to be an abstract superclass of <table> classes that have user-defined key comparison and hash functions. (NB: The hash functions cannot involve physical addresses.)

Tests whether two objects (usually strings) are the same modulo case.

Synopsis

case-insensitive-equal ( object-1 , object-2 ) => ( answer )

Parameters

object-1	An instance of <object> .
object-2	An instance of <object> .

Return Values

answer

An instance of <boolean> .

Description

Tests whether two objects have the same string value modulo case. Comparisons to non- <string> or <character> instances return #f.

Least-specific method testing whether two objects are the same modulo case.

Synopsis

case-insensitive-equal ( object-1 , object-2 ) => ( answer )

Parameters

object-1	An instance of <object> .
object-2	An instance of <object> .

Return Values

answer

An instance of <boolean> .

Description

Since at least one of the arguments is not a <character> or <string> , this method always returns #f.

Method testing whether two characters are the same modulo case.

Synopsis

case-insensitive-equal ( object-1 , object-2 ) => ( answer )

Parameters

object-1	An instance of <character> .
object-2	An instance of <character> .