txr-013 2009-09-30txr-013

1 files changed, 37 insertions, 1 deletions

diff --git a/txr.1 b/txr.1
index 4bf67a7c..191def67 100644
--- a/txr.1
+++ b/txr.1
@@ -21,7 +21,7 @@
 .\"IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
 .\"WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 
-.TH txr 1 2009-09-09 "txr v. 012" "Text Extraction Utility"
+.TH txr 1 2009-09-09 "txr v. 013" "Text Extraction Utility"
 .SH NAME
 txr \- text extractor
 .SH SYNOPSIS
@@ -637,6 +637,10 @@ Treat the remaining query as a subquery unit, and search the lines of
 the input file until that subquery matches somewhere.
 A skip is also an anonymous block.
 
+.IP @(trailer)
+Treat the remaining query or subquery as a match for a trailing context. That
+is to say, if the remainder matches, the data position is not advanced.
+
 .IP @(some)
 Match some clauses in parallel. At least one has to match.
 
@@ -804,6 +808,38 @@ be written instead:
   end @BEG_SYMBOL
   @(end)
 
+.SS The Trailer directive
+
+The trailer directive introduces a trailing portion of a query or subquery
+which matches input material normally, but in the event of a successful match,
+does not advance the current position. This can be used, for instance, to
+cause @(collect) to match partially overlapping regions.
+
+Example:
+
+  @(collect)
+  @line
+  @(trailer)
+  @(skip)
+  @line
+  @(end)
+
+This script collects each line which has a duplicate somewhere later
+in the input. Without the @(trailer) directive, this does not work properly
+for inputs like:
+
+  111
+  222
+  111
+  222
+
+Without @(trailer), the first duplicate pair constitutes a match which
+spans over the 222. After that pair is found, the matching continues
+after the second 111.
+
+With the @(trailer) directive in place, the collect body, on each
+iteration, only consumes the lines matched prior to @(trailer).
+
 .SS The Some, All, None and Maybe directives
 
 These directives combine multiple subqueries, which are applied at the same position in parallel. The syntax of all three follows this example: