<h1>
      Unicode stream editing and transcription
</h1>

<pre>
Usage: java -jar tr.jar [ -i inputfile 
                        | -o outputfile 
                        | -s specfile 
                        | -I inputencoding 
                        | -O outputencoding 
                        | -S specencoding
                        ]* [--] [pattern replacement]*
</pre>

<p>
      Transforms standard input (or specified input file) in input
      encoding to standard output (or specified output file) in
      output encoding, substituting replacements for patterns in
      each line. Substitutions are specified in the specfile 
      (it it is given) which is interpreted in the specified encoding, 
      (for notation see below) and by the command line.
</p>

<p>
      Substitutions are performed in order of their appearance in
      the specfile then on the command line. Every occurence of
      each pattern on each line is replaced.
</p>

<p>
      Default encodings are UTF8
</p>


<p>
      (C) 2004, Collegium Vigorniensis Oxon. (All wrongs reversed)
</p>

<p>
      This is free software. Do what you want with it.
</p>

<pre>
$Id$        
</pre>

<h2>Pattern notation</h2>

<pre>      
   Characters
      x         The character x
      
   Escaped character sequences start with \ and are followed by
   
      Char(s)  Meaning
      
      \        The backslash character
      0nnn     The character with octal value 0nnn 
      xhh      The character with hexadecimal value 0xhh
      uhhhh    The character with hexadecimal value 0xhhhh
      t        The tab character 
      n        The newline (line feed) character 
      r        The carriage-return character 
      f        The form-feed character 
      a        The alert (bell) character 
      e        The escape character 
       
   Character classes
      [abc]             a, b, or c (simple class)
      [^abc]            Any character except a, b, or c (negation)
      [a-zA-Z]          a through z or A through Z, inclusive (range)
      [a-d[m-p]]        a through d, or m through p: [a-dm-p] (union)
      [a-z&&[def]]      d, e, or f (intersection)
      [a-z&&[^bc]]      a through z, except for b and c: [ad-z] (subtraction)
      [a-z&&[^m-p]]     a through z, and not m through p: [a-lq-z](subtraction)
       
   Predefined character classes
      .         Any character (may or may not match line terminators)
      \d        A digit: [0-9]
      \D        A non-digit: [^0-9]
      \s        A whitespace character: [ \t\n\x0B\f\r]
      \S        A non-whitespace character: [^\s]
      \w        A word character: [a-zA-Z_0-9]
      \W        A non-word character: [^\w]
       
   POSIX character classes (US-ASCII only)
      \p{Lower}         A lower-case alphabetic character: [a-z]
      \p{Upper}         An upper-case alphabetic character:[A-Z]
      \p{ASCII}         All ASCII:[\x00-\x7F]
      \p{Alpha}         An alphabetic character:[\p{Lower}\p{Upper}]
      \p{Digit}         A decimal digit: [0-9]
      \p{Alnum}         An alphanumeric character:[\p{Alpha}\p{Digit}]
      \p{Punct}         Punctuation: One of !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~
      \p{Graph}         A visible character: [\p{Alnum}\p{Punct}]
      \p{Print}         A printable character: [\p{Graph}]
      \p{Blank}         A space or a tab: [ \t]
      \p{Cntrl}         A control character: [\x00-\x1F\x7F]
      \p{XDigit}        A hexadecimal digit: [0-9a-fA-F]
      \p{Space}         A whitespace character: [ \t\n\x0B\f\r]
       
   Classes for Unicode blocks and categories
      \p{InGreek}        A character in the Greek block (simple block)
      \p{Lu}             An uppercase letter (simple category)
      \p{Sc}             A currency symbol
      \P{InGreek}        Any character except one in the Greek block (negation)
      [\p{L}&&[^\p{Lu}]] Any letter except an uppercase letter (subtraction)
       
   Boundary matchers
      ^         The beginning of a line
      $         The end of a line
      \b        A word boundary
      \B        A non-word boundary
      \A        The beginning of the input
      \G        The end of the previous match
      \Z        The end of the input but for the final terminator, if any
      \z        The end of the input
       
   Greedy quantifiers
      X?        X, once or not at all
      X*        X, zero or more times
      X+        X, one or more times
      X{n}      X, exactly n times
      X{n,}     X, at least n times
      X{n,m}    X, at least n but not more than m times
       
   Reluctant quantifiers
      X??       X, once or not at all
      X*?       X, zero or more times
      X+?       X, one or more times
      X{n}?     X, exactly n times
      X{n,}?    X, at least n times
      X{n,m}?   X, at least n but not more than m times
       
   Possessive quantifiers
      X?+       X, once or not at all
      X*+       X, zero or more times
      X++       X, one or more times
      X{n}+     X, exactly n times
      X{n,}+    X, at least n times
      X{n,m}+   X, at least n but not more than m times
       
   Logical operators
      XY        X followed by Y
      X|Y       Either X or Y
      (X)       X, as a capturing group
       
   Back references
      \n        Whatever the nth capturing group matched
       
   Quotation
      \         Nothing, but quotes the following character
      \Q        Nothing, but quotes all characters until \E
      \E        Nothing, but ends quoting started by \Q
       
   Special constructs (non-capturing)
      (?:X)     X, as a non-capturing group
      (?=X)     X, via zero-width positive lookahead
      (?!X)     X, via zero-width negative lookahead
      (?<=X)    X, via zero-width positive lookbehind
      (?<!X)    X, via zero-width negative lookbehind
      (?>X)     X, as an independent, non-capturing group
      (?idmsux-idmsux)    Nothing, but turns match flags on - off
      (?idmsux-idmsux:X)  X, as a non-capturing group with the given flags on - off
</pre>

<h2>Specfile Notation</h2>
<P>
Lines in the specfile are comments if their first non-space character is '#', and
otherwise they specify a substitution. The form of a substitution is:
</P>

<pre>
<I>any amount of whitespace</I><B>/</B><I>pattern</I><B>/</B><I>replacement</I><B>/</B><I>any amount of whitespace</I>
</pre>

<P>
The '/' can be any character other than '#' or '\' or a space character, and
the trailing '/' can be omitted if the replacement has no trailing whitespace.
Comments can appear after the trailing '/'.
</P>


