factor/library/io/stream.facts

USING: help io ;

HELP: stream-close
{ $values { "stream" "a stream" } }
{ $contract "Closes the stream. This releases any external resources associated with the stream, such as file handles and network connections. No further operations can be performed on the stream after this call." }
{ $notes "You must close streams after you are finished working with them. A convenient way to automate this is by using the " { $link with-stream } " word." }
$io-error ;

HELP: set-timeout
{ $values { "n" "an integer" } { "stream" "a stream" } }
{ $contract "Sets a timeout, in milliseconds, for closing the stream if there is no activity. Not all streams support timeouts." } 
$io-error ;

HELP: stream-readln
{ $values { "stream" "an input stream" } { "str" "a string" } }
{ $contract "Reads a line of input from the stream. Outputs " { $link f } " on stream exhaustion." }
$io-error ;

HELP: stream-read1
{ $values { "stream" "an input stream" } }
{ $contract "Reads a character of input from the stream. Outputs " { $link f } " on stream exhaustion." }
$io-error ;

HELP: stream-read
{ $values { "n" "a non-negative integer" } { "stream" "an input stream" } { "str/f" "a string or " { $link f } } }
{ $contract "Reads " { $snippet "n" } " characters of input from the stream. Outputs a truncated string or " { $link f } " on stream exhaustion." }
$io-error ;

HELP: stream-write1
{ $values { "ch" "a character" } { "stream" "an output stream" } }
{ $contract "Writes a character of output to the stream. If the stream does buffering, output may not be performed immediately; use " { $link stream-flush } " to force output." }
$io-error ;

HELP: stream-write
{ $values { "str" "a string" } { "stream" "an output stream" } }
{ $contract "Writes a string of output to the stream. If the stream does buffering, output may not be performed immediately; use " { $link stream-flush } " to force output." }
$io-error ;

HELP: stream-flush
{ $values { "stream" "an output stream" } }
{ $contract "Waits for any pending output to complete." }
{ $notes "With many output streams, written output is buffered and not sent to the underlying resource until either the buffer is full, or this word is called." }
$io-error ;

HELP: stream-terpri
{ $values { "stream" "an output stream" } }
{ $contract "Writes a line terminator. If the stream does buffering, output may not be performed immediately; use " { $link stream-flush } " to force output." }
$io-error ;

HELP: stream-format
{ $values { "str" "a string" } { "style" "a hashtable" } { "stream" "an output stream" } }
{ $contract "Writes formatted text to the stream. If the stream does buffering, output may not be performed immediately; use " { $link stream-flush } " to force output."
$terpri
"The " { $snippet "style" } " hashtable holds character style information. See " { $link "character-styles" } "." }
$io-error ;

HELP: with-nested-stream
{ $values { "quot" "a quotation" } { "style" "a hashtable" } { "stream" "an output stream" } }
{ $contract "Calls the quotation in a new dynamic scope with the " { $link stdio } " stream rebound to a nested paragraph stream, with formatting information applied."
$terpri
"Unlike " { $link with-stream-style } ", this creates a new paragraph block in the output."
$terpri
"The " { $snippet "style" } " hashtable holds paragraph style information. See " { $link "paragraph-styles" } "." }
$io-error ;

HELP: with-stream-table
{ $values { "grid" "a sequence of equal-length sequences" } { "quot" "a quotation" } { "style" "a hashtable" } { "stream" "an output stream" } }
{ $description "Calls the quotation with each element of the grid in turn, each time in a new dynamic scope with " { $link stdio } " rebound to a new stream. The results are laid out in a tabular fashion on " { $snippet "stream" } "."
$terpri
"The " { $snippet "style" } " hashtable holds table style information. See " { $link "table-styles" } "." }
$io-error ;

HELP: with-stream-style
{ $values { "style" "a hashtable" } { "quot" "a quotation" } { "stream" "an output stream" } }
{ $description "Calls the quotation in a new dynamic scope where calls to " { $link write } ", " { $link format } " and other stream output words automatically inherit style settings from " { $snippet "style" } "."
$terpri
"Unlike " { $link with-nested-stream } ", the quotation's output is inline, and not nested in a paragraph block." }
{ $notes "Details are in the documentation for " { $link with-stream-style } "." }
$io-error ;

HELP: stream-print
{ $values { "str" "a string" } { "stream" "an output stream" } }
{ $description "Writes a newline-terminated string." }
$io-error ;

HELP: stream-copy
{ $values { "in" "an input stream" } { "out" "an output stream" } }
{ $description "Copies the contents of one stream into another, closing both streams when done." } 
$io-error ;