next up previous contents index
Next: 3.11 Paths Up: 3 The Slate World Previous: 3.9 Streams and Iterators   Contents   Index


3.10 External Resources

Slate includes an extensible framework for streams that deal with external resources, such as files or network connections or other programs. This generally relies on having a representative object in the image which tracks the underlying primitive identity of the resource, and also provides methods for iterator-style streams over what is available through the resources. Many of these resources aren't sequences as files are sequences of bytes, so they're asynchronous and behave differently from ordinary streams. Basic Types

provides the basic behavior for external resource types.
ExternalResource Locator
provides a core attribute type for structured descriptors of external resources, as a generalization of file pathnames, port descriptions, URLs, or even URIs.
ExternalResource Stream
provides an extension of the iterator interface (described on sub:Iterator-Streams) for ExternalResources. All of them provide ReadStream, WriteStream, and ReadWriteStream variants as appropriate. Primitives

Extending the framework to cover new primitive or otherwise connection types is fairly simple, since the following methods are the only input/output primitives needed for defining an external resource type:

resource read: n from: handle startingAt: start into: array
reads the next n elements from the resource identified by the given low-level handle, from the given starting point. The contents are placed in the given array, which should be a ByteArray currently.
resource write: n to: handle startingAt: start from: array
writes the next n elements to the resource identified by the given low-level handle, from the given starting point. The contents are read from the given array, which should be a ByteArray currently. Standard behavior

Opens the resource for usage within the system.
Closes the resource, releasing related administrative data; this happens automatically during garbage collection, but it is poor practice to rely upon this.
Creates the external resource represented (used by open).
answers whether the resource is open or closed.
answers whether the resource is active.
restarts the resource if it's already active.
flushes any unwritten elements.
commits all pending write-out information to the resource. Commit performs a flush but also ensures that the data is actually sent to the peer.
sends read:from:startingAt:into: with the resource's handle.
sends write:to:startingAt:from: with the resource's handle.
returns a ReadWriteStream for accessing the resource. Unlike the stream that iterator returns, interactor is expected to return a coupled pair of a ReadStream and WriteStream over the same resource, synchronized to preserve the resource's behavior.
answers a sensible buffer size for interaction, possibly dynamically determined.
answers a default sensible buffer size for interaction.
answers a suitable structured object for dealing with that resource's identity/location.
executes a code block with the resource as its argument, opening and closing the resource transparently to the block, even for abnormal terminations. If the resource is already open, then this takes no opening or closing actions, so that calls may be nested blindly.

3.10.1 Consoles

The Slate interpreter provides two console Streams primitively, ConsoleInput and ConsoleOutput, which are Read- and WriteStreams by default, capturing keyboard input and writing out to the console, respectively. These are also accessible as Console reader and Console writer. Console interactor delegates to these, acting as a ReadWriteStream.

3.10.2 Files

Files are persistent external sequences of bytes. The interpreter provides an object type File which provides the corresponding protocol extensions to ExternalResource:

returns a new File with the given name as its locator and also a mode option. No attempt to open the file is automatically made.
extends sessionDo: with a simple temporary mode option (which is reset on return).
returns a file handle for a String that names a path to a file, for read/write access.
returns a handle for reading an existing file of the given name, or Nil if it doesn't exist.
returns a handle for writing (appending) to a file with the given name.
returns a handle for writing (appending) to a new file with the given name. It will create a new file, but if the file exists, Nil will be returned.
wraps sessionDo: with the ability to create a new File dynamically for the session along with a specified mode.
returns the position within the File in byte units.
sets the position within the File to the given integer number of bytes.
returns the File size in bytes.
returns the File's pathname.
will always return a complete pathname whereas the regular method may not.
adjusts the file to have the given name.
answers whether the file's end has been reached.
makes a file with the given name, with empty contents.
answers whether there is a file with the object's pathname.
deletes the file.
Perhaps the most important utility is to load libraries based on path names. load: 'filename' will execute a file with the given path name as Slate source.

File mode objects specify the interaction capabilities requested of the underlying system for the handle. The modes consist of File Read, File Write, File ReadWrite, and File CreateWrite.

3.10.3 Shells and Pipes (Not Currently Implemented)

The Shell and Environment globals are provided to access the underlying operating system's command shell functionality from within the Slate environment. Shell provides a dispatch hook for shell-related methods, while Environment acts as a Dictionary of the current shell context's defined variables and values. They support several primitive methods as follows:

Shell enter
enters the host operating system's command-line shell. This has no effect on the Slate environment directly except for suspending and resuming it.
Shell runProgram: programName withArgs: argsArray
executes the program with the given name and passes it the arguments which must be Strings.
Shell execute: scriptFilename
passes the contents of the file named along to the shell, returning its output.
Environment at: varName
returns the value stored in a given environment variable.
Environment at: varName put: newValue
stores the new value into the given environment variable named.
Environment keys
returns an Array of the environment variable names defined in the context that Slate was executed in. This result is independent of the actual environment variables.
Environment values
returns an Array of the environment variable values in the context that Slate was executed in, in the same order as the keys are returned. This result is independent of the actual environment variables.

3.10.4 Networking

Sockets are ExternalResources that provide a connection on an operating system port. The behaviors specific to these two types are as follows:

creates a new socket of the appropriate type to listen/request on the port number.
listen &buffer:
sets the port to listening for client connections, with an optional override of the system default number of request queue entries.
creates a new socket connection for the next incoming request.
shuts down the socket, called when closing (automatically).
answers the hostname of the socket.
answers the port number of the socket.
answers the hostname of the peer.
answers the peer's port number.
answers the Internet Protocol address string of the peer, if any.
answers a Symbol representing the socket's current status.

next up previous contents index
Next: 3.11 Paths Up: 3 The Slate World Previous: 3.9 Streams and Iterators   Contents   Index
Brian Rice 2005-11-21