summaryrefslogtreecommitdiffstats
path: root/txr.1
diff options
context:
space:
mode:
authorKaz Kylheku <kaz@kylheku.com>2013-10-11 21:21:28 -0700
committerKaz Kylheku <kaz@kylheku.com>2013-10-11 21:21:28 -0700
commit5d7d623bbcbda34354972af2ce608b8e110b1d3e (patch)
tree97a39fbbd79e5f6c8693e60f9127b6bf4110f2eb /txr.1
parenteab83b3a45281d15a7c03d395ba8d4b5e19732b1 (diff)
downloadtxr-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.164
1 files changed, 63 insertions, 1 deletions
diff --git a/txr.1 b/txr.1
index b9f9c0da..49d235c4 100644
--- a/txr.1
+++ b/txr.1
@@ -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