190 lines
7.6 KiB
Plaintext
190 lines
7.6 KiB
Plaintext
USING: help io styles network ;
|
|
|
|
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."
|
|
$nl
|
|
"Stream words are in the " { $vocab-link "io" } " vocabulary."
|
|
{ $subsection "stream-protocol" }
|
|
"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> }
|
|
"Further topics:"
|
|
{ $subsection "stream-utils" }
|
|
{ $subsection "stdio" }
|
|
{ $subsection "styles" }
|
|
{ $subsection "stream-binary" } ;
|
|
|
|
ARTICLE: "stream-protocol" "Stream protocol"
|
|
"The stream protocol consists of a large number of generic words, many of which are optional."
|
|
$nl
|
|
"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-read-until }
|
|
{ $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."
|
|
$nl
|
|
"Seven words are required for output streams:"
|
|
{ $subsection stream-flush }
|
|
{ $subsection stream-write1 }
|
|
{ $subsection stream-write }
|
|
{ $subsection stream-format }
|
|
{ $subsection stream-nl }
|
|
{ $subsection with-nested-stream }
|
|
{ $subsection with-stream-style }
|
|
{ $subsection stream-write-table }
|
|
{ $subsection make-table-cell }
|
|
"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."
|
|
$nl
|
|
"First, a simple composition of " { $link stream-write } " and " { $link stream-nl } ":"
|
|
{ $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 format }
|
|
{ $subsection nl }
|
|
{ $subsection bl }
|
|
{ $subsection with-style }
|
|
{ $subsection with-nesting }
|
|
"Tabular output:"
|
|
{ $subsection tabular-output }
|
|
{ $subsection with-row }
|
|
{ $subsection with-cell }
|
|
{ $subsection write-cell }
|
|
"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 tabular-output } " words take a hashtable of style attributes. Output stream implementations are free to ignore style information."
|
|
$nl
|
|
"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 presented } ;
|
|
|
|
ARTICLE: "table-styles" "Table styles"
|
|
"Table styles for " { $link tabular-output } ":"
|
|
{ $subsection table-gap }
|
|
{ $subsection table-border } ;
|
|
|
|
ARTICLE: "presentations" "Presentations"
|
|
"The " { $link presented } " style can be used to emit clickable objects. A utility word should be used instead of setting this directly:"
|
|
{ $subsection write-object } ;
|
|
|
|
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" } ")."
|
|
$nl
|
|
"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."
|
|
$nl
|
|
"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: "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 }
|
|
"Pathname manipulation:"
|
|
{ $subsection parent-dir }
|
|
{ $subsection path+ }
|
|
{ $see-also "os" } ;
|
|
|
|
ARTICLE: "network-streams" "Networking"
|
|
"Both TCP/IP and UDP/IP network protocls are supported. Only the former is built on the stream protocol, however both are documented in this section for completeness."
|
|
{ $subsection "network-tcp" }
|
|
{ $subsection "network-udp" } ;
|
|
|
|
ARTICLE: "network-tcp" "TCP/IP networking"
|
|
"TCP/IP connections can be established with this word:"
|
|
{ $subsection <client> }
|
|
"TCP/IP 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 }
|
|
"TCP/IP server sockets are closed by calling " { $link stream-close } "."
|
|
$nl
|
|
"The " { $module-link "libs/server" } " library defines a nice wrapper around the above words." ;
|
|
|
|
ARTICLE: "network-udp" "UDP/IP networking"
|
|
"A connectionless UDP/IP socket can be opened with this word:"
|
|
{ $subsection <datagram> }
|
|
"Packets can be sent and received with a pair of words:"
|
|
{ $subsection send }
|
|
{ $subsection receive }
|
|
"UDP/IP sockets are closed by calling " { $link stream-close } "." ;
|
|
|
|
ARTICLE: "string-streams" "String streams"
|
|
"Streams:"
|
|
{ $subsection <string-reader> }
|
|
{ $subsection <string-writer> }
|
|
"Utility combinators:"
|
|
{ $subsection string-in }
|
|
{ $subsection string-out }
|
|
"An efficient way of splitting a string up into lines without constructing a string stream:"
|
|
{ $subsection string-lines } ;
|