diff options
| author | Kaz Kylheku <kaz@kylheku.com> | 2011-09-25 10:28:41 -0700 |
|---|---|---|
| committer | Kaz Kylheku <kaz@kylheku.com> | 2011-09-25 10:28:41 -0700 |
| commit | 4ce8dde9cafa8a77a0c623043fded0a751ad4b02 (patch) | |
| tree | 2b18b7c7e838da2491327fdd8a9d291f31c2b46c /txr.1 | |
| parent | 658eb97af000aa0598e3544c2c7ea2cdd60b5b06 (diff) | |
| download | txr-4ce8dde9cafa8a77a0c623043fded0a751ad4b02.tar.gz txr-4ce8dde9cafa8a77a0c623043fded0a751ad4b02.tar.bz2 txr-4ce8dde9cafa8a77a0c623043fded0a751ad4b02.zip | |
Filtering feature for variable substitution in output.
* filter.c, filter.h: New files.
* Makefile (OBJS): filter.o added.
* gc.c (mark_obj): Mark new alloc field of string objets.
* hash.c (struct hash): New member, userdata.
(hash_mark): Mark new userdata member of hash.
(make_hash): Initialize userdata.
(get_hash_userdata, set_hash_userdata, hashp): New functions.
* hash.h (get_hash_userdata, set_hash_userdata, hashp): New functions
declared.
* lib.c (getplist, string_extend, cobjp): New functions.
(string_own, string, string_utf8): Initialize new alloc field to nil.
(mkstring, mkustring): Initialize new alloc field to actual size.
(length_str): When length is computed and cached, also compute
and cache alloc.
(init): Call filter_init.
* lib.h (string string): New member, alloc.
(num_fast): Macro converted to inline function.
(getplist, string_extend, cobjp): New functions declared.
* match.c (match_line): Follows change of modifier s-exp syntax.
(format_field): New parameter, filter.
New modifier syntax parsed. Filter retrieved, and applied.
(subst_vars): New parameter, filter. Filter is either applied
in this function or passed to format_field, as needed.
(eval_form): Pass nil to new parameter of subst_vars.
(do_output_line): New parameter, filter. Passed down to subst_vars.
(do_output): New parameter, filter. Passed down to do_output_line.
(match_files): Pass nil filter to subst_vars in cat directive.
Output directive refactored to parse keywords, extract the
filter and pass down to do_output.
* parser.y (regex): Generate (sys:regex regex syntax ...)
instead of (regex syntax ...).
(elem, expr): Updated w.r.t. regex syntax change.
(var): Cases '{' IDENT regex '}' and '{' IDENT NUMBER '}'
are removed. new syntax '{' IDENT exprs '}' to handle these
more generally and allow for keywords.
* txr.1: Updated.
Diffstat (limited to 'txr.1')
| -rw-r--r-- | txr.1 | 37 |
1 files changed, 36 insertions, 1 deletions
@@ -2274,7 +2274,7 @@ usual printing of the variable bindings or the word false. The syntax of the @(output) directive is: - @(output [ DESTINATION ] [ :nothrow ]) + @(output [ DESTINATION ] [ :nothrow ] [ { keyword value } * ]) . . one or more output directives or lines . @@ -2295,6 +2295,12 @@ asynchronously, a failing command will not throw an immediate exception that can be suppressed with :nothrow. This is for synchronous errors, like trying to open a destination file, but not having permissions, etc. +The keyword value list is used for passing additional options. +Currently, the only keyword supported is the :filter keyword. +This specifies a filter to be applied to the variable substitutions occuring +within the output clause. + + .SS Output Text Text in an output clause is not matched against anything, but is output @@ -2318,6 +2324,9 @@ field. If the text is shorter than the field, then it is left-adjusted within that field, if the width is specified as a positive number, and right-adjusted if the width is specified as negative. +An output variable may specify a filter which overrides any filter established +for the output clause. The syntax for this is @(NAME :filter <filtername>}. + .SS The Repeat Directive The repeat directive is generates repeated text from a ``boilerplate'', @@ -2465,6 +2474,32 @@ 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 Output Filtering + +Often it is necessary to transform the output to preserve its meaning +under the convention of a given data format. For instance, if a piece of +text contains the characters < or >, then if that text is being +substituted into HTML, these should be replaced by < and >. +This is what filtering is for. Filtering is applied to the contents of output +variables, not to any template text. +.B txr +implements named filters. Currently, the only built-in filter available is +called :to_html and user-defined filters are not possible. + +To escape HTML characters in all variable substitutions occuring in +an output clause, specify :filter :to_html in the directive: + + @(output :filter :to_html) + ... + @(end) + +To filter an individual variable, add the syntax to the variable spec: + + @(output) + @{x :filter :to_html} + @(end) + + .SH EXCEPTIONS .SS Introduction |