more I/O docs

library/bootstrap/boot-stage1.factor

@@ -238,6 +238,8 @@ vectors words ;
         "/library/io/plain-stream.facts"
         "/library/io/server.facts"
         "/library/io/stdio.facts"
+        "/library/io/stream.facts"
+        "/library/io/string-streams.facts"
         "/library/math/arc-trig-hyp.facts"
         "/library/math/complex.facts"
         "/library/math/constants.facts"

library/io/stdio.factor

@@ -61,7 +61,6 @@ SYMBOL: style-stack
     [ format* ] write-object ;
 
 : write-outliner ( content caption -- )
-    #! Takes a pair of quotations.
     >r outline associate r> with-nesting terpri ;
 
 : simple-outliner ( string object content -- )

library/io/stdio.facts

@@ -24,7 +24,7 @@ $io-error ;
 
 HELP: write1 "( ch -- )"
 { $values { "ch" "a character" } }
-{ $contract "Writes a character of output to the " { $link stdio } " stream." }
+{ $contract "Writes a character of output to the " { $link stdio } " stream. If the stream does buffering, output may not be performed immediately; use " { $link flush } " to force output." }
 $io-error ;
 
 HELP: write1 "( ch -- )"
@@ -51,7 +51,7 @@ $io-error ;
 
 HELP: format "( str style -- )"
 { $values { "str" "a string" } { "style" "a hashtable" } }
-{ $contract "Writes formatted text to the " { $link stdio } " stream." }
+{ $contract "Writes formatted text to the " { $link stdio } " stream. If the stream does buffering, output may not be performed immediately; use " { $link flush } " to force output." }
 { $notes "Details are in the documentation for " { $link stream-format } "." }
 $io-error ;
 
@@ -63,7 +63,7 @@ $io-error ;
 
 HELP: print "( style quot -- )"
 { $values { "style" "a hashtable" } { "quot" "a quotation" } }
-{ $description "Outputs a newline-terminated string to the " { $link stdio } " stream." }
+{ $description "Writes a newline-terminated string to the " { $link stdio } " stream." }
 $io-error ;
 
 HELP: with-stream "( stream quot -- )"

library/io/stream.factor

@@ -1,5 +1,5 @@
 ! Copyright (C) 2003, 2005 Slava Pestov.
-! See http://factor.sf.net/license.txt for BSD license.
+! See http://factorcode.org/license.txt for BSD license.
 IN: io
 USING: errors hashtables generic kernel math namespaces
 sequences strings ;

library/io/stream.facts

@@ -0,0 +1,73 @@
+USING: help io ;
+
+HELP: stream-close "( stream -- )"
+{ $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 "( n stream -- )"
+{ $values { "n" "an integer" } { "stream" "a stream" } }
+{ $contract "" } 
+$io-error ;
+
+HELP: stream-readln "( stream -- str )"
+{ $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 "( stream -- ch/f )"
+{ $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 "( n stream -- str )"
+{ $values { "n" "a non-negative integer" } { "stream" "an input stream" } { "str" "a string" } }
+{ $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 "( ch stream -- )"
+{ $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 "( str stream -- )"
+{ $values { "str" "a string" } { "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-flush "( stream -- )"
+{ $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 "( stream -- )"
+{ $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-terpri* "( stream -- )"
+{ $values { "stream" "an output stream" } }
+{ $contract "Writes a line terminator unless the stream is already positioned at the start of a line, in which case this word does nothing. If the stream does buffering, output may not be performed immediately; use " { $link stream-flush } " to force output." }
+$io-error ;
+
+HELP: stream-format "( str style stream -- )"
+{ $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." }
+$io-error ;
+
+HELP: with-nested-stream "( quot style 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." }
+$io-error ;
+
+HELP: stream-print "( str stream -- )"
+{ $values { "str" "a string" } { "stream" "an output stream" } }
+{ $description "Writes a newline-terminated string." }
+$io-error ;
+
+HELP: stream-copy "( in out -- )"
+{ $values { "in" "an input stream" } { "out" "an output stream" } }
+{ $description "" } 
+$io-error ;

library/io/string-streams.facts

@@ -0,0 +1,22 @@
+USING: help io ;
+
+HELP: <string-writer> "( -- stream )"
+{ $values { "stream" "an output stream" } }
+{ $description "" } ;
+
+HELP: string-out "( quot -- str )"
+{ $values { "quot" "a quotation" } { "str" "a string" } }
+{ $description "" } ;
+
+HELP: <string-reader> "( str -- stream )"
+{ $values { "str" "a string" } { "stream" "an input stream" } }
+{ $description "" } ;
+
+HELP: string-in "( str quot -- )"
+{ $values { "str" "a string" } { "quot" "a quotation" } }
+{ $description "" } ;
+
+HELP: contents "( stream -- str )"
+{ $values { "stream" "an input stream" } { "str" "a string" } }
+{ $description "" }
+$io-error ;