Section Intro: Stream Operators

THE META-HTML LANGUAGE REFERENCE MANUAL

File Operators

[TOC]

Session Operators

Section Intro: Stream Operators

Stream Operators

Synopsis:

A stream is a data object upon which various input and output operations may be performed.

Meta-HTML provides commands for creating, opening, reading from, and writing to, stream objects. The referenced underlying object may either be a file or a network connection.

Commands:

stream-get
stream-get-contents
stream-info

stream-put
stream-put-contents
stream-readable

stream-shutdown
stream-writable
with-open-stream

More Information:

There are three special names which can be used with with-open-stream, these are *standard-input*, *standard-output*, and *standard-error*.

*standard-input* always names the stream that from which input was being read at the time the engine, server, or mhc invoked. *standard-output* always names the stream to which output is being written by the engine, server or mhc.

*standard-error* always names the stream where error output will appear -- this stream could be the same as the one named by *standard-output*, but this does not have to be the case.

<stream-get STREAM &key [STOP-AT=CHARACTER] Simple

Reads a chunk of data from STREAM and returns it. STREAM is read until the character value specified by CHARACTER (defaulting to a newline) is reached, and that data upto and including the final CHARACTER is returned. One way to read all of the available data is to supply the empty string as the value of STOP-AT:

<with-open-stream stream www.ua.com:80 type=tcp mode=read-write>
  <stream-put stream "GET /welcome.mhtml HTTP/1.0\n\n">
  <set-var the-page = <stream-get stream stop-at="">>
</with-open-stream>

<stream-get-contents STREAM VAR &key [CHUNK-SIZE=SIZE] [STOP-AT=CHARACTER] Simple

Reads the contents of the stream STREAM into the binary variable VAR. You can easily use this in conjunction with stream-put-contents and coerce-var.

If STOP-AT is supplied, it is a character at which the function should stop reading data from the stream. Unlike stream-get, STOP-AT defaults to the empty character, thus causing the entire stream to be read.

If CHUNK-SIZE is supplied, it is the amount to read at one time. This is useful for when you have an unbounded amount of data to read, and you would like to process it in manageable chunks.

For example, the following code copies data from an open network stream to a file on the local disk, without using more than 32k of memory:

<with-open-stream src data-server.ua.com:2345 type=tcp mode=read>
  <with-open-stream dst /tmp/datafile type=file mode=write-create>
    <while <stream-readable s>>
      <stream-get-contents src chunk chunk-size=32768>
      <stream-put-contents dst chunk>
    </while>
  </with-open-stream>
</with-open-stream>

<stream-info STREAM Simple

Return an association list providing information about STREAM.

<stream-put STREAM STRING Simple

Writes STRING to the open STREAM.

<stream-put-contents STREAM VAR Simple

Writes the contents of the variable VAR to the open STREAM. This is the only way to get the contents of a binary variable written to a stream. Binary variables are generally created with stream-get-contents, or when uploading a file from a Web browser.

<stream-readable STREAM &key [DELAY=SECONDS] Simple

Returns "true" if STREAM is an open stream which was opened with a mode of read, or read-write, and which still has data pending.

The optional keyword DELAY is used to specify the amount of time in seconds that stream-readable should wait for the stream to become ready for reading. The default value is zero seconds; no waiting period is used.

<stream-shutdown STREAM Simple

Only for use with network streams, this tells the underlying operating system (and the other end of the network connection) that no additional input or output will be done using this object. In effect, it immediately closes the stream.

When used in conjunction with a network stream opened on *standard-output*, this can be used to close the HTTP connection to the client, and yet continue processing data.

<stream-writable STREAM &key [DELAY=SECONDS] Simple

Returns "true" if STREAM is an open stream which was opened with a mode of write, append, read-write, or write-create, and which is available to have data written to it.

The optional keyword DELAY is used to specify the amount of time in seconds that stream-writable should wait for the stream to become ready for writing. The default value is zero seconds; no waiting period is used.

<with-open-stream VAR NAME &key [TYPE=(FILE|TCP|PROG|FD)] [MODE=OPEN-MODE] [TIMEOUT=(VALUE|NEVER)] body </with-open-stream> Complex

Create an environment in which VAR is bound to the indicator of an open stream, named by NAME.

The stream is either of type FILE, in which case it is a simple file in the file system, of type TCP, in which case it is an open network connection, or of type PROG, in which case it is an open connection to a running process.

When TYPE is TCP, NAME specifies the host and port to connect to, in the form Hostname:Port-Number. PORT-NUMBER can either be a symbolic name which is widely recognized (e.g., SMTP), or the digits which make up the port number, (e.g., 25). PORT-NUMBER can either be a symbolic name which is widely recognized (e.g., SMTP), or the digits which make up the port number, (e.g., 25).

When TYPE is FD, NAME specifies an already open file descriptor to connect to. This should be used with caution, as the standard file descriptors for stdin, stdout, and stderr might not be what you expect. To talk to those streams, you should use *STANDARD-INPUT*, *STANDARD-OUTPUT*, and *STANDARD-ERROR* as the stream names, without passing a TYPE argument.

Finally, the keyword argument NOTIMEOUT=TRUE may be given, which indicates that the amount of time that Meta-HTML should wait during IO operations on this stream is infinite -- all processing will block until the stream is successfully read from or written to. The default timeout is dependent on which specific operation is being performed, and the amount of data which is being read or written, but is generally suitable for writing data at about 14.4kbps.

The possible values for MODE are:

READ:
The stream is opened for reading only. The underlying object must already exist.
WRITE:
The stream is opened for writing only. The underlying object must already exist.
READ-WRITE:
The stream is opened for both reading and writing. The underlying object must already exist.
APPEND:
The stream is opened for writing only. If the underlying object did not already exist, it is created. Information written to this stream appears after any information that was already present in the underlying object.
WRITE-CREATE:
The stream is opened for writing only. The underlying object is created fresh, even if it had already existed.

When one is opening, reading to, or writing from a network stream, the amount of time it can take to finish the operation is indeterminate. So, the keyword argument TIMEOUT=VALUE can be used to specify the maximum amount of time (in seconds) that these operations may take. If the value is specified as "never", then these operations can take "forever". If the value isn't specified, then the operations calculate the maximum wait time dynamically, based upon the amount of information to be read or written. Any other value specifies an absolute maximum number of seconds.

Edit Section
Function Index
Variable Index