next up previous contents
Next: 3.9 Exceptions Up: 3 The Slate World Previous: 3.7 Streams and Iterators   Contents

Subsections

3.8 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.

3.8.0.1 Basic Types

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.

3.8.0.2 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.

3.8.0.3 Standard behavior

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.

3.8.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.8.2 Files

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.

3.8.3 Shells and Pipes

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.8.4 Sockets

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 up previous contents
Next: 3.9 Exceptions Up: 3 The Slate World Previous: 3.7 Streams and Iterators   Contents
The Slate Project 2004-01-04