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.

3.10.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, 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.

3.10.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.10.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 (used by open).

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:

sends read:from:startingAt:into: with the resource's handle.

write:startingAt:from:

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

sessionDo:

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:

newNamed:&mode:

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.

sessionDo:&mode:

extends sessionDo: with a simple temporary mode option (which is reset on return).

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.

withOpenNamed:do:&mode:

wraps sessionDo: with the ability to create a new File dynamically for the session along with a specified mode.

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.

isAtEnd

answers whether the file's end has been reached.

create

makes a file with the given name, with empty contents.

exists

answers whether there is a file with the object's pathname.

delete

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:

newOnPort:

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.

accept

creates a new socket connection for the next incoming request.

shutdown

shuts down the socket, called when closing (automatically).

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.