Next: 3.9 Exceptions
Up: 3 The Slate World
Previous: 3.7 Streams and Iterators
  Contents
Subsections
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.
- ExternalResource
- 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, URL's, or even URI's.
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.
- open
- Opens the resource for usage within the system.
- close
- Closes the resource, releasing related administrative
data; this happens automatically during garbage collection, but it
is poor practice to rely upon this.
- enable
- Creates the external resource represented. Establishing
a peer connection happens later.
- isOpen
- answers whether the resource is open or closed.
- isActive
- answers whether the resource is active.
- restart
- restarts the resource if it's already active.
- flush
- flushes any unwritten elements.
- commit
- 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.
- read:startingAt:into:
- calls read:from:startingAt:into:
with the resource's handle.
- write:startingAt:from:
- calls write:to:startingAt:from:
with the resource's handle.
- interactor
- 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.
- bufferSize
- answers a sensible buffer size for interaction,
possibly dynamically determined.
- defaultBufferSize
- answers a default sensible buffer size
for interaction.
- locator
- answers a suitable structured object for dealing
with that resource's identity/location.
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.
Files are persistent external sequences of bytes. The interpreter
provides an object type File which follows the corresponding
protocol extensions to ExternalResource:
- open:
- returns a file handle for a String that
names a path to a file, for read/write access.
- openForInput:
- returns a handle for reading an existing
file of the given name, or Nil if it doesn't exist.
- openForOutput:
- returns a handle for writing (appending)
to a file with the given name.
- openNew:
- 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.
- exists
- answers whether there is a file with the stream's
pathname.
- position
- returns the position within the file in byte units.
- position:
- sets the position within the file to the given
integer number of bytes.
- size
- returns the file size in bytes.
- name
- returns the file's pathname.
- fullName
- will always return a complete pathname whereas
the regular method may not.
- renameTo:
- adjusts the file to have the given name.
- atEnd
- answers whether the file's end has been reached.
- delete
- deletes the file.
Perhaps the most important utility is to load libraries based on path
names. 'filename' fileIn will execute a file with the given
path name as Slate source.
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.
SocketClient and SocketServer are ExternalResources
that provide a connection on an operating system port. The behaviors
specific to these two types are as follows:
- newOnPort:
- creates a new socket of the appropriate type
to listen/request on the port number.
- shutdown
- shuts down the socket, called when closing (automatically).
- wait
- waits indefinitely for a connection on the SocketServer.
- wait:
- waits a specific given amount of time in seconds
for a connection on the SocketServer. An Error is
raised if this does not happen. A timeout of zero will cause polling.
- host
- answers the hostname of the socket.
- port
- answers the port number of the socket.
- peerHost
- answers the hostname of the peer.
- peerPort
- answers the peer's port number.
- peerIP
- answers the Internet Protocol address string of
the peer, if any.
- status
- answers a symbol representing the socket's current
status.
Next: 3.9 Exceptions
Up: 3 The Slate World
Previous: 3.7 Streams and Iterators
  Contents
The Slate Project
2004-02-16