diff options
author | Kaz Kylheku <kaz@kylheku.com> | 2013-10-11 21:21:28 -0700 |
---|---|---|
committer | Kaz Kylheku <kaz@kylheku.com> | 2013-10-11 21:21:28 -0700 |
commit | 5d7d623bbcbda34354972af2ce608b8e110b1d3e (patch) | |
tree | 97a39fbbd79e5f6c8693e60f9127b6bf4110f2eb /txr.1 | |
parent | eab83b3a45281d15a7c03d395ba8d4b5e19732b1 (diff) | |
download | txr-5d7d623bbcbda34354972af2ce608b8e110b1d3e.tar.gz txr-5d7d623bbcbda34354972af2ce608b8e110b1d3e.tar.bz2 txr-5d7d623bbcbda34354972af2ce608b8e110b1d3e.zip |
Task #11433. Implement continuation of multiple
output blocks across the same stream.
* match.c (close_s, named_k, continue_k, finish_k): New symbol
variables.
(v_output): Implement :named, :finish and :continue.
(v_close): New static function.
(syms_init): New symbols interned.
(dir_tables_init): New entry associating v_close
function with symbol stored in close_s.
* match.h (close_s): Declared.
* txr.1: New features documented.
Diffstat (limited to 'txr.1')
-rw-r--r-- | txr.1 | 64 |
1 files changed, 63 insertions, 1 deletions
@@ -3537,7 +3537,7 @@ usual printing of the variable bindings or the word false. The syntax of the @(output) directive is: - @(output [ DESTINATION ] { bool-keyword | keyword value }* ) + @(output [ <destination> ] { bool-keyword | keyword value }* ) . . one or more output directives or lines . @@ -3590,6 +3590,35 @@ the new content will be appened to the previous content of the variable, after flattening the content to a list, as if by the @(flatten) directive. +.IP :named + +The argument of :named is a symbol which denotes a variable. +The file or pipe stream which is opened for the output is +stored in this variable, and is not closed at the end of the +output block. This allows a subsequent output block to continue +output on the same stream, which is possible using the +next two keywords, :continue or :finish. +A new binding is established for the variable, even if it +already has an existing binding. + +.IP :continue + +A destination should not be specified if :continue is used. The argument of +:continue is an expression, such as a variable name, that must evaluates to a +stream object. That stream object is used for the output block. +At the end of the output block, the stream is flushed, but not +closed. A usage example is given in the documentation for the Close Directive +below. + +.IP :finish + +A destination should not be specified if :finish is used. The argument of +:continue is an expression, such as a variable name, that must evaluates to a +stream object. That stream object is used for the output block. +At the end of the output block, the stream is closed. +An example is given in the documentation for the Close Directive +below. + .SS Output Text Text in an output clause is not matched against anything, but is output @@ -3893,6 +3922,39 @@ spaces each one, except the last which has no space. If the list has exactly one item, then the @(last) applies to it instead of the main clause: it is produced with no trailing space. +.SS The Close Directive + +The syntax of the @(close) directive is: + + @(close <expr>) + +Where <expr> evaluates to a stream. The close directive can be +used to explicitly close streams created using @(output ... :named <var>) +syntax, as an alternative to the @(output :finish <expr>) + +Examples: + +Write two lines to "foo.txt" over two output blocks using +a single stream: + + @(output "foo.txt" :named foo) + Hello, + @(end) + @(output :continue foo) + world! + @(end) + @(close foo) + +The same as above, using :finish rather than :continue +so that the stream is closed at the end of the second block: + + @(output "foo.txt" :named foo) + Hello, + @(end) + @(output :finish foo) + world! + @(end) + .SS Output Filtering Often it is necessary to transform the output to preserve its meaning |