diff --git a/library/io/server.facts b/library/io/server.facts index ce083b3cbb..6f8c505470 100644 --- a/library/io/server.facts +++ b/library/io/server.facts @@ -1,3 +1,5 @@ +USING: help io ; + HELP: log-stream f { $description "Variable. Holds an output stream for logging messages." } { $see-also log-error log-client with-log-file with-logging } ; diff --git a/library/io/stdio.factor b/library/io/stdio.factor index 164001b71f..a6c3542d93 100644 --- a/library/io/stdio.factor +++ b/library/io/stdio.factor @@ -27,29 +27,24 @@ SYMBOL: stdio : print ( string -- ) stdio get stream-print ; : with-stream ( stream quot -- ) - #! Close the stream no matter what happens. [ swap stdio set [ close ] cleanup ] with-scope ; inline : with-stream* ( stream quot -- ) - #! Close the stream if there is an error. [ swap stdio set [ close rethrow ] recover ] with-scope ; inline SYMBOL: style-stack : >style ( style -- ) - #! Push a style on the style stack. dup hashtable? [ "Style must be a hashtable" throw ] unless style-stack [ ?push ] change ; -: style> ( -- style ) - style-stack get pop ; +: style> ( -- style ) style-stack get pop ; : with-style ( style quot -- ) [ >r >style r> call style> drop ] with-scope ; inline : current-style ( -- style ) - #! Always returns a fresh hashtable. style-stack get hash-concat ; : format* ( string -- ) current-style format ; @@ -63,7 +58,6 @@ SYMBOL: style-stack >r presented associate r> with-style ; : simple-object ( string object -- ) - #! Writes a clickable presentation with the specified string. [ format* ] write-object ; : write-outliner ( content caption -- ) diff --git a/library/io/stdio.facts b/library/io/stdio.facts index d93b78dcee..e5dc34f7cc 100644 --- a/library/io/stdio.facts +++ b/library/io/stdio.facts @@ -1,3 +1,5 @@ +USING: help io ; + HELP: stdio f { $description "Variable. Holds a stream, used for various implicit stream operations. Rebound using " { $link with-stream } " and " { $link with-stream* } "." } ; @@ -55,7 +57,7 @@ $io-error ; HELP: with-nesting "( style quot -- )" { $values { "style" "a hashtable" } { "quot" "a quotation" } } -{ $contract "Calls the quotation in a new dynamic scope, where the " { $link stdio } " stream is rebound to a nested stream of the current " { $link stdio } " stream, with formatting information applied." } +{ $contract "Calls the quotation in a new dynamic scope with the " { $link stdio } " stream rebound to a nested paragraph stream, with formatting information applied." } { $notes "Details are in the documentation for " { $link stream-format } "." } $io-error ; @@ -63,3 +65,65 @@ HELP: print "( style quot -- )" { $values { "style" "a hashtable" } { "quot" "a quotation" } } { $description "Outputs a newline-terminated string to the " { $link stdio } " stream." } $io-error ; + +HELP: with-stream "( stream quot -- )" +{ $values { "stream" "an input or output stream" } { "quot" "a quotation" } } +{ $description "Calls the quotation in a new dynamic scope, with the " { $link stdio } " variable rebound to " { $snippet "stream" } ". The stream is closed if the quotation returns or throws an error." } +{ $see-also with-stream* } ; + +HELP: with-stream* "( stream quot -- )" +{ $values { "stream" "an input or output stream" } { "quot" "a quotation" } } +{ $description "Calls the quotation in a new dynamic scope, with the " { $link stdio } " variable rebound to " { $snippet "stream" } ". The stream is closed if the quotation throws an error, however it is " { $emphasis "not" } " closed if the quotation returns without incident." } +{ $see-also with-stream } ; + +HELP: style-stack f +{ $description "Variable. Holds a vector of hashtables." } +{ $see-also with-style format* } ; + +HELP: with-style "( style quot -- )" +{ $values { "style" "a hashtable" } { "quot" "a quotation" } } +{ $description "Pushes a style on the style stack, and calls the quotation." } +{ $see-also format* with-nesting* } ; + +HELP: current-style "( -- style )" +{ $values { "style" "a hashtable" } } +{ $description "Creates a new hashtable by concatenating all styles on the style stack, with keys in more recently pushed styles taking precedence." } +{ $see-also format* with-nesting* } ; + +HELP: format* "( str -- )" +{ $values { "str" "a string" } } +{ $description "Writes formatted text to the " { $link stdio } " stream using the current style." } +{ $see-also current-style } +$io-error ; + +HELP: bl "( -- )" +{ $description "Writes a word break to the " { $link stdio } " stream using the current style." } +{ $notes "This word is useful even when not doing formatting. If " { $link stdio } " is a plain text stream, it simply outputs a space." } +{ $see-also current-style } +$io-error ; + +HELP: with-nesting* "( style quot -- )" +{ $values { "style" "a hashtable" } { "quot" "a quotation" } } +{ $description "Calls the quotation in a new dynamic scope with the " { $link stdio } " stream rebound to a nested paragraph stream with the current style." } +$io-error +{ $see-also current-style } ; + +HELP: write-object "( obj quot -- )" +{ $values { "obj" "an object" } { "quot" "a quotation" } } +{ $description "Pushes a style on the style stack associating all output with the object, and calls the quotation. If the " { $link stdio } " stream supports it, any text output by the quotation will become a clickable presentation of the object." } +$io-error ; + +HELP: simple-object "( str obj -- )" +{ $values { "str" "a string" } { "obj" "an object" } } +{ $description "Writes a string to the " { $link stdio } " stream, associating it with the object. If formatted output is supported, the string will become a clickable presentation of the object, otherwise this word behaves like a call to " { $link write } "." } +$io-error ; + +HELP: write-outliner "( content caption -- )" +{ $values { "content" "a quotation" } { "caption" "a quotation" } } +{ $description "Writes an outliner to the " { $link stdio } " stream. The " { $snippet "caption" } " quotation is called to produce a label for an outliner. Expanding the outliner calls " { $snippet "content" } " in a new dynamic scope with " { $link stdio } " rebound to the body of the outliner. If the stream does not support formatted output, this simply calls " { $snippet "caption" } " and ignores " { $snippet "content" } "." } +$io-error ; + +HELP: simple-outliner "( str obj content -- )" +{ $values { "str" "a string" } { "obj" "an object" } { "content" "a quotation" } } +{ $description "Writes an outliner to the " { $link stdio } " stream. The outliner's caption is a the string " { $snippet "str" } " with an associated presentation of " { $snippet "obj" } ". Expanding the outliner calls " { $snippet "content" } " in a new dynamic scope with " { $link stdio } " rebound to the body of the outliner. If the stream does not support formatted output, this simply writes " { $snippet "str" } " and ignores everything else." } +$io-error ;