home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / tr100.zip / TR.DOC next >
Text File  |  1993-04-12  |  7KB  |  169 lines
  1. --------------------------------------------------------------------------
  2.  This program is distributed as shareware.  If you like and use this
  3. program, please send $5 via check or banknote to :
  4.  
  5.     Ms. Shuyi Chen
  6.     206 West 99th Street #6A
  7.     NYC NY 10025
  8.  
  9.  If you have comments or find bugs, please write to the address above
  10. or send an electronic mail message to fernand@cs.nyu.edu, with a
  11. Subject line indicating the message is for SHUYI CHEN.
  12. --------------------------------------------------------------------------
  13.  
  14. NAME:        TR    - translate characters (and a little more).
  15.  
  16. SYNOPSIS:    TR, run without arguments prints :
  17.  
  18.    tr (Version 1.0) USAGE : tr [options] FROMSTRING TOSTRING
  19.     -d[c] "..."       Deletes characters in [complement of] ...
  20.     -s[c] "..."       Squeezes characters in [complement of] ...
  21.     -S                Squeeze All
  22.     -(l/u/t)          (Lower/Raise/Toggle) Case
  23.     -w                List Words : Whitespace -> Squeezed Newline
  24.     -W "..."          List Words : "..." -> Squeezed Newline
  25.     -ff               Flatten : Flat (Deletes Newline)
  26.     -f                Flatten : (Newline -> Squeezed Space)
  27.     -fr "..."         Flatten : Join with (rotating) ... characters
  28.     -F# "s1" ... "s#" Flatten : Join with # (rotating) strings
  29.     -p                Pad output if shorter (default Delete)
  30.     -b                Binary Processing (Default Off)
  31.     -DU,              Dos-To-Unix (Deletes Return and Control-Z)
  32.     -UD, -UDZ         Unix-To-Dos (\n -> \r\n), Control-Z Termination
  33.     -e[c] "..." ",,," Transforms characters in [complement of] "..." to ",,,"
  34.     a-z == Inclusive Range e.g. a-z, Z-A, l-z etc
  35.     \ Octal Escape.  e.g. \012 == Newline
  36.     \\ == \, \n == Newline, \- == -, \w == Whitespace == " \t\n"
  37.     \r == Return, \t == Tab
  38.  
  39. DESCRIPTION
  40.  
  41.     TR is a pure filter.  i.e it copies standard in to standard
  42.     out with substitution or deletion of selected characters.  The
  43.     arguments FROMSTRING and TOSTRING are considered sets of
  44.     characters.  Any input character found in FROMSTRING is mapped
  45.     into the character in the corresponding position within
  46.     TOSTRING.  Normally, FROMSTRING and TOSTRING need not be
  47.     enclosed in quotes.
  48.  
  49. NOTATION: 
  50.  
  51.           a-e
  52.  
  53.     (for example) denotes a range of characters from a to e in
  54.     increasing or decreasing ASCII order.  How about when you want
  55.     to use  "-" as a regular character?  In this case, you use the
  56.     \ character to escape the range interpretation of "-", i.e.
  57.     "a\-z" will indicate the characters "a", "-" and "z", not the
  58.     range a to z.
  59.  
  60.     In the same way, "\" is used to escape the special meaning of
  61.     "\" itself.  The "\" character may also be used to indicate
  62.     nonprinting characters.  In fact, if you know the octal
  63.     representation of the character, it may be represented as a
  64.     "\" followed by 3 octal digits that denote the character whose
  65.     ASCII code is given by those digits. For example "\012" is a
  66.     Newline.  Several short forms are defined for the more common
  67.     nonprinting characters.  Specifically: 
  68.  
  69.     \\ == \
  70.     \- == -
  71.     \t == Tab
  72.     \n == Newline
  73.     \r == Return
  74.     \w == Whitespace == " \t\n"
  75.  
  76. OPTIONS
  77.  
  78. "-p"    Used to change the default course of action of the program
  79.     when TOSTRING is shorter than FROMSTRING.  The default action
  80.     is to ignore the excess characters appearing in FROMSTRING,
  81.     but the "-p" option instead results in padding out TOSTRING to
  82.     the length of FROMSTRING, using the last character in TOSTRING
  83.     as the padding character.  For instance, if you typed :
  84.  
  85.     tr abcde ABC
  86.  
  87.     the default action would be to ignore 'd' and 'e' in the 
  88.     argument "abcde", but the "-p" option causes the following
  89.     interpretation:
  90.  
  91.     tr abcde ABCCC
  92.  
  93. "-d"    If specified, the next argument should be a string, all of
  94.     whose characters are removed by TR.
  95.  
  96. "-dc"    As above, except characters in the complement of the string
  97.     argument are deleted.
  98.  
  99. "-S"    Squeezes all characters.  i.e. multiple (consecutive)
  100.     occurrences of any character are replaced with a single
  101.     occurrence.
  102.  
  103. "-s"    Applies the afore-mentioned squeezing to characters in the
  104.     string following this option.
  105.  
  106. "-sc"    As above, except characters in the complement of the string
  107.     argument are squeezed.
  108.  
  109. "-l"    Lowers case
  110. "-u"    Raises case
  111. "-t"    Toggles case
  112.  
  113. "-w"    Replaces whitespace with a squeezed newline.  This may be used
  114.     to make a list of "words".
  115.  
  116. "-W"    Replaces whitespace as above but redefines the meaning of
  117.     "whitespace" to the set of characters comprising the string
  118.     following the option.
  119.  
  120. "-f"    Performs the inverse of the "-w" option, by deleting newlines
  121.     and replacing them with a single space.  This can be used to
  122.     get a list of words on a single line from a list of words that
  123.     are one to a line.
  124.  
  125. "-ff"    Like the "-f" option but it does not add a separating space
  126.     when it joins lines.
  127.  
  128. "-fr"    Provides flexibility in specifying the character that is used
  129.     to join lines.  The characters in the string following the
  130.     option are used sequentially.  If the string runs out and
  131.     there are still lines to be joined, then the string is reused. 
  132.  
  133. "-F"    Provides still greater flexibility, in that instead of using
  134.     characters, one may specify strings to be used to join lines.
  135.     When using this option, you must tell the program how many
  136.     strings you are providing.  For example, "-F2" says 2 strings
  137.     will follow, and ofcourse you must provide 2 strings after the option. 
  138.  
  139. "-DU"    (Dos-To-Unix) option converts the input from DOS text to Unix
  140.     text.  i.e. Carriage Returns are deleted and so are Control Z
  141.     characters.
  142.  
  143. "-UD"    (Unix-To-Dos) does the reverse, replacing Newlines with
  144.     Carriage-Return Newline pairs.
  145.  
  146. "-UDZ"    (Unix-To-Dos-with-Control-Z) terminates the output with a
  147.     Control-Z character, besides replacing Newlines with
  148.     Carriage-Return Newline pairs.
  149.  
  150. "-e"    Should be followed by 2 strings which are interpreted just
  151.     like the aforementioned FROMSTRING and TOSTRING.
  152.  
  153. "-ec"    As above, except the characters in the complement of FROMSTRING
  154.     are translated.
  155.  
  156. "-b"    Toggles binary processing.  The program default is to delete
  157.     carriage returns from the input and to emit a carriage return
  158.     prior to every newline emitted.  Use of the "-b" option turns
  159.     this off; carriage returns are treated like any other
  160.     character.  This option is useful if a binary file is being
  161.     processed.
  162.  
  163. NOTE:    This program is not a direct superset of UNIX tr.  In
  164.     particular repetitions are not supported, options must be 
  165.     specified separately and octal representations require all 3
  166.     characters.  On the plus side, a few common tasks are directly
  167.     specifiable, lines may be joined more flexibly and multiple
  168.     options may be used.
  169.