diff options
| author | Kaz Kylheku <kaz@kylheku.com> | 2011-09-26 20:22:06 -0700 |
|---|---|---|
| committer | Kaz Kylheku <kaz@kylheku.com> | 2011-09-26 20:22:06 -0700 |
| commit | 070d3dfe7759943406cd76e7aebe72bf92ab3503 (patch) | |
| tree | 254d02889a993cb4caeb568422291e7cf2726cca /txr.1 | |
| parent | f3fe0151fc4116f0fec40e7454d8866f11908560 (diff) | |
| download | txr-070d3dfe7759943406cd76e7aebe72bf92ab3503.tar.gz txr-070d3dfe7759943406cd76e7aebe72bf92ab3503.tar.bz2 txr-070d3dfe7759943406cd76e7aebe72bf92ab3503.zip | |
New feature: @(deffilter)
Bugfix in @(throw) when non-symbol is thrown: exception message
referred to the symbol throw rather than the erroneous object.
* filter.c (build_filter_from_list, register_filter): New functions.
* filter.h (register_filter): New function declared.
* lib.c (deffilter_s): New variable defined.
(chain): Function changed from single list argument to variable
argument list to reduce the complexity of use.
(do_and, and): New functions.
(obj_init): deffilter_s initializatio added.
* lib.h (deffilter_s, and): New declarations.
(chain): Declaration updated to new function signature.
(eq): Changed from macro to inline function.
* match.c (do_output_line): Simplified expression involving chain.
(do_output): Likewise.
(match_files): Bugfix in error handling of throw.
Implementation of deffilter.
* txr.1: Documented deffilter.
Diffstat (limited to 'txr.1')
| -rw-r--r-- | txr.1 | 77 |
1 files changed, 76 insertions, 1 deletions
@@ -973,6 +973,13 @@ A directive understood within an @(output) section, for repeating multi-line text, with successive substitutions pulled from lists. A version @(rept) produces repeated text within one line. +.IP @(deffilter) +This directive is used for defining named filters, which are useful +for filtering variable substitutions in output blocks. Filters are useful +when data must be translated between different representations that +have different special characters or other syntax, requiring escaping +or similar treatment. + .PP .SS The Next Directive @@ -2484,7 +2491,8 @@ 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 filters available are -:to_html and :from_html. User-defined filters are not possible. +:to_html and :from_html. User-defined filters are possible, however. +See notes on the deffilter directive below. To escape HTML characters in all variable substitutions occuring in an output clause, specify :filter :to_html in the directive: @@ -2499,6 +2507,73 @@ To filter an individual variable, add the syntax to the variable spec: @{x :filter :to_html} @(end) +.SS The Deffilter Directive + +The deffilter directive allows a query to define a custom filter, which +can then be used in @(output) clauses to transform substituted data. + +This directive's syntax is illustrated in this example: + + Query: @(deffilter rot13 + ("a" "n") + ("b" "o") + ("c" "p") + ("d" "q") + ("e" "r") + ("f" "s") + ("g" "t") + ("h" "u") + ("i" "v") + ("j" "w") + ("k" "x") + ("l" "y") + ("m" "z") + ("n" "a") + ("o" "b") + ("p" "c") + ("q" "d") + ("r" "e") + ("s" "f") + ("t" "g") + ("u" "h") + ("v" "i") + ("w" "j") + ("x" "k") + ("y" "l") + ("z" "m")) + @(collect) + @line + @(end) + @(output :filter rot13) + @(repeat) + @line + @(end) + @(end) + + Input: hey there! + + Output: url gurer! + + +The deffilter symbol must be followed by the name of the filter to be defined, +followed by pairs of strings. Each pair specifies a piece of text to be +filtered from the left hand side to the right hand side. + +Filtering works using a longest match algorithm. The input is scanned from left +to right, and the longest piece of text is identified at every character +position which matches a string on the left hand side, and that text is +replaced with the right hand string. + +If none of the strings matches at a given character position, then that +character is passed through untranslated, and the scan continues at the next +character in the input. + +If a filter definition accidentally +contains two or more repetitions of the same left hand string with different +right hand translations, the later ones take precedence. No warning is issued. + + + .SH EXCEPTIONS |