factor/core/handbook/streams.facts

USING:
help
io
styles ;

ARTICLE: "streams" "Streams"
"Input and output centers on the concept of a " { $emphasis "stream" } ", which is a source or sink of characters. Streams also support formatted output, which may be used to present styled text in a manner independent of output medium."
$terpri
"Stream words are in the " { $vocab-link "io" } " vocabulary."
{ $subsection "stream-protocol" }
{ $subsection "stream-utils" }
{ $subsection "stdio" }
{ $subsection "styles" }
{ $subsection "stream-binary" }
{ $subsection "stream-impls" }
;

ARTICLE: "stream-protocol" "Stream protocol"
"The stream protocol consists of a large number of generic words, many of which are optional."
$terpri
"A word required to be implemented for all streams:"
{ $subsection stream-close }
"Three words are required for input streams:"
{ $subsection stream-read1 }
{ $subsection stream-read }
{ $subsection stream-readln }
"If your stream supports the first two but not the last one, wrap it in a " { $link <line-reader> } " to get a default implementation."
$terpri
"Seven words are required for output streams:"
{ $subsection stream-flush }
{ $subsection stream-write1 }
{ $subsection stream-write }
{ $subsection stream-terpri }
{ $subsection stream-format }
{ $subsection with-nested-stream }
"If your stream supports the first three but not the rest, wrap it in a " { $link <plain-writer> } ", which provides plain text implementations of the stream formatting words (the so called " { $emphasis "extended stream output protocol" } ")." ;

ARTICLE: "stream-utils" "Stream utilities"
"There are a few useful stream-related words which are not generic, but merely built up from the stream protocol."
$terpri
"First, a simple composition of " { $link stream-write } " and " { $link stream-terpri } ":"
{ $subsection stream-print }
"Next up, a pair of words for reading the entire contents of a stream as an array of lines, or a single string:"
{ $subsection lines }
{ $subsection contents }
"Finally, a word to copy the contents of one stream to another:"
{ $subsection stream-copy } ;

ARTICLE: "stdio" "The default stream"
"Various words take an implicit stream parameter from a variable to reduce stack shuffling."
{ $subsection stdio }
"Unless rebound in a child namespace, this variable will be set to a console stream for interacting with the user."
{ $subsection close }
{ $subsection read1 }
{ $subsection read }
{ $subsection readln }
{ $subsection flush }
{ $subsection write1 }
{ $subsection write }
{ $subsection print }
{ $subsection terpri }
{ $subsection format }
{ $subsection with-nesting }
"A pair of combinators support rebinding the " { $link stdio } " variable:"
{ $subsection with-stream }
{ $subsection with-stream* } ;

ARTICLE: "styles" "Formatted output"
"The " { $link stream-format } ", " { $link with-nested-stream } " and " { $link with-stream-table } " words take a hashtable of style attributes. Output stream implementations are free to ignore style information."
$terpri
"Style hashtables are keyed by symbols from the " { $vocab-link "styles" } " vocabulary."
{ $subsection "character-styles" }
{ $subsection "paragraph-styles" }
{ $subsection "table-styles" }
{ $subsection "presentations" } ;

ARTICLE: "character-styles" "Character styles"
"Character styles for " { $link stream-format } ":"
{ $subsection foreground }
{ $subsection background }
{ $subsection font }
{ $subsection font-size }
{ $subsection font-style }
{ $subsection presented } ;

ARTICLE: "paragraph-styles" "Paragraph styles"
"Paragraph styles for " { $link with-nested-stream } ":"
{ $subsection page-color }
{ $subsection border-color }
{ $subsection border-width }
{ $subsection wrap-margin }
{ $subsection outline }
{ $subsection presented } ;

ARTICLE: "table-styles" "Table styles"
"Table styles for " { $link with-stream-table } ":"
{ $subsection table-gap }
{ $subsection table-border } ;

ARTICLE: "presentations" "Presentations and outliners"
"The " { $link presented } " and " { $link outline } " styles can be used to build sophisticated user interfaces in the Factor UI. Instead of setting them directly, two utility words should be used:"
{ $subsection write-object }
{ $subsection write-outliner } ;

ARTICLE: "stream-binary" "Working with binary data"
"The core stream words read and write strings. Packed binary integers can be read and written by converting to and from sequences of bytes. Floating point numbers can be read and written by converting them into a their bitwise integer representation (" { $link "floats" } ")."
$terpri
"There are two ways to order the bytes making up an integer; " { $emphasis "little endian" } " byte order outputs the least significant byte first, and the most significant byte last, whereas " { $emphasis "big endian" } " is the other way around."
$terpri
"Consider the hexadecimal integer "{ $snippet "HEX: cafebabe" } ". Big endian byte order yields the following sequence of bytes:"
{ $code
    "Byte:   1  2  3  4"
    "Value: be ba fe ca"
}
"Compare this with little endian byte order:"
{ $code
    "Byte:   1  2  3  4"
    "Value: ca fe ba be"                    
}                                                             
"Two words convert a sequence of bytes into an integer:"
{ $subsection be> }
{ $subsection le> }
"Two words convert an integer into a sequence of bytes:"
{ $subsection >be }
{ $subsection >le } ;

ARTICLE: "stream-impls" "Stream implementations"
"External resource streams communicate with the outside world:"
{ $subsection "file-streams" }
{ $subsection "network-streams" }
"Virtual streams serve as glue:"
{ $subsection "string-streams" }
"Wrapper streams convert partial implementations of the stream protocol into full-fledged streams:"
{ $subsection <line-reader> }
{ $subsection <plain-writer> }
"A utility to combine a complementary input and output stream pair into a single stream:"
{ $subsection <duplex-stream> }
"As a final note, the " { $link f } " object implements the stream protocol, by yielding end-of-file on input and discarding all output." ;

ARTICLE: "file-streams" "Reading and writing files"
{ $subsection <file-reader> }
{ $subsection <file-writer> }
"File system meta-data:"
{ $subsection exists? }
{ $subsection directory? }
{ $subsection file-length }
{ $subsection stat } ;

ARTICLE: "network-streams" "TCP/IP networking"
"Client connections are bidirectional streams opened with this word:"
{ $subsection <client> }
"Network servers are implemented by first opening a server socket, then waiting for connections:"
{ $subsection <server> }
{ $subsection accept }
"Some information can be obtained about incoming client connections:"
{ $subsection client-stream-host }
{ $subsection client-stream-port } ;

ARTICLE: "string-streams" "String streams"
"Streams:"
{ $subsection <string-reader> }
{ $subsection <string-writer> }
"Utility combinators:"
{ $subsection string-in }
{ $subsection string-out } ;