home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 22 gnu / 22-gnu.zip / GNUTUE.ZIP / man / tr.man < prev    next >
Text File  |  1992-07-18  |  9KB  |  224 lines
  1. NAME
  2.      tr - translate or delete characters
  3.  
  4. SYNOPSIS
  5.      tr [-cst] [--complement]  [--squeeze-repeats]  [--truncate-set1]  string1
  6.      string2
  7.      tr {-s,--squeeze-repeats} [-c] [--complement] string1
  8.      tr {-d,--delete} [-c] string1
  9.      tr  {-d,--delete}  {-s,--squeeze-repeats}  [-c]  [--complement]   string1
  10.      string2
  11.  
  12. DESCRIPTION
  13.  
  14.      This manual page documents the GNU version of tr. tr copies the  standard
  15.      input to the standard output, performing one of the following operations:
  16.  
  17.           o translate, and  optionally  squeeze  repeated  characters  in  the
  18.           result
  19.           o squeeze repeated characters
  20.           o delete characters
  21.           o delete characters,  then  squeeze  repeated  characters  from  the
  22.           result.
  23.  
  24.      The string1 and (if given)  string2  arguments  define  ordered  sets  of
  25.      characters,  referred  to  below  as  set1  and set2.  These sets are the
  26.      characters of the input that  tr  operates  on.   The  --complement  (-c)
  27.      option  replaces set1 with its complement (all of the characters that are
  28.      not in set1).
  29.  
  30.      SPECIFYING SETS OF CHARACTERS
  31.  
  32.      The format of the string1 and string2 arguments resembles the  format  of
  33.      regular  expressions;  however,  they  are  not regular expressions, only
  34.      lists of characters.  Most  characters  simply  represent  themselves  in
  35.      these  strings,  but the strings can contain the shorthands listed below,
  36.      for convenience.  Some of them can be used only in string1 or string2, as
  37.      noted below.
  38.  
  39.      Backslash excapes.  A backslash followed by a character not listed  below
  40.      causes an error message.
  41.  
  42.      \a   Control-G.
  43.  
  44.      \b   Control-H.
  45.  
  46.      \f   Control-L.
  47.  
  48.      \n   Control-J.
  49.  
  50.      \r   Control-M.
  51.  
  52.      \t   Control-I.
  53.  
  54.      \v   Control-K.
  55.  
  56.      \ooo The character with the value given by ooo, which is  1  to  3  octal
  57.           digits.
  58.  
  59.      \\   A backslash.
  60.  
  61.      Ranges.  The notation `m-n' expands to  all  of  the  characters  from  m
  62.      through n, in ascending order.  m should collate before n; if it doesn't,
  63.      an error results.  As an example, `0-9'  is  the  same  as  `0123456789'.
  64.      Ranges can optionally be enclosed in square brackets, which has no effect
  65.      but is supported for compatibility with historical System V  versions  of
  66.      tr.
  67.  
  68.      Repeated characters.  The notation `[c*n]' in string2 expands to n copies
  69.      of  character  c.   Thus,  `[y*6]' is the same as `yyyyyy'.  The notation
  70.      `[c*]' in string2 expands to as many copies of c as are  needed  to  make
  71.      set2  as long as set1.  If n begins with a 0, it is interpreted in octal,
  72.      otherwise in decimal.
  73.  
  74.      Character classes.  The notation `[:class-name:]' expands to all  of  the
  75.      characters  in  the  (predefined) class named class-name.  The characters
  76.      expand in no  particular  order,  except  for  the  `upper'  and  `lower'
  77.      classes,  which  expand  in  ascending order.  When the --delete (-d) and
  78.      --squeeze-repeats (-s) options are both given, any character class can be
  79.      used  in  string2.   Otherwise,  only  the  character classes `lower' and
  80.      `upper' are accepted in string2,  and  then  only  if  the  corresponding
  81.      character  class  (`upper' and `lower', respectively) is specified in the
  82.      same relative position in string1.  Doing this specifies case conversion.
  83.      The  class  names are given below; an error results when an invalid class
  84.      name is given.
  85.  
  86.      alnum
  87.           Letters and digits.
  88.  
  89.      alpha
  90.           Letters.
  91.  
  92.      blank
  93.           Horizontal whitespace.
  94.  
  95.      cntrl
  96.           Control characters.
  97.  
  98.      digit
  99.           Digits.
  100.  
  101.      graph
  102.           Printable characters, not including space.
  103.  
  104.      lower
  105.           Lowercase letters.
  106.  
  107.      print
  108.           Printable characters, including space.
  109.  
  110.      punct
  111.           Punctuation characters.
  112.  
  113.      space
  114.           Horizontal or vertical whitespace.
  115.  
  116.      upper
  117.           Uppercase letters.
  118.  
  119.      xdigit
  120.           Hexadecimal digits.
  121.  
  122.      Equivalence classes.  The syntax `[=c=]' expands to all of the characters
  123.      that  are  equivalent  to c, in no particular order.  Equivalence classes
  124.      are a recent invention intended to support  non-English  alphabets.   But
  125.      there  seems  to  be  no  standard  way to define them or determine their
  126.      contents.  Therefore, they are not fully  implemented  in  GNU  tr;  each
  127.      character's  equivalence  class  consists  only  of that character, which
  128.      makes this a useless construction currently.
  129.  
  130.      TRANSLATING
  131.  
  132.      tr performs translation when string1 and string2 are both given  and  the
  133.      --delete  (-d)  option is not given.  tr translates each character of its
  134.      input that is in set1 to the corresponding character in set2.  Characters
  135.      not  in set1 are passed through unchanged.  When a character appears more
  136.      than once in set1 and the corresponding characters in set2  are  not  all
  137.      the  same,  only  the final one is used.  For example, these two commands
  138.      are equivalent:
  139.           tr aaa xyz
  140.           tr a z
  141.  
  142.      A common use of tr is to convert lowercase characters to uppercase.  This
  143.      can be done in many ways.  Here are three of them:
  144.           tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
  145.           tr a-z A-Z
  146.           tr '[:lower:]' '[:upper:]'
  147.  
  148.      When tr is performing translation, set1 and set2 should normally have the
  149.      same  length.   If set1 is shorter than set2, the extra characters at the
  150.      end of set2 are ignored.
  151.  
  152.      On the other hand, making set1 longer than set2 is not portable;  POSIX.2
  153.      says  that  the  result is undefined.  In this situation, the BSD tr pads
  154.      set2 to the length of set1 by repeating the last  character  of  set2  as
  155.      many times as necessary.  The System V tr truncates set1 to the length of
  156.      set2.
  157.  
  158.      By default, GNU tr handles this case like the  BSD  tr  does.   When  the
  159.      --truncate-set1  (-t)  option is given, GNU tr handles this case like the
  160.      System V tr instead.  This option is ignored for  operations  other  than
  161.      translation.
  162.  
  163.      Acting like the System V tr in this case breaks the relatively common BSD
  164.      idiom:
  165.           tr -cs A-Za-z0-9 '\012'
  166.      because it converts only zero bytes (the first element in the  complement
  167.      of set1), rather than all non-alphanumerics, to newlines.
  168.  
  169.      SQUEEZING REPEATS AND DELETING
  170.  
  171.      When given just the --delete (-d) option, tr removes any input characters
  172.      that are in set1.
  173.  
  174.      When given just the --squeeze-repeats (-s) option, tr replaces each input
  175.      sequence of a repeated character that is in set1 with a single occurrence
  176.      of that character.
  177.  
  178.      When given both the --delete and the --squeeze-repeats options, tr  first
  179.      performs  any  deletions  using  set1,  then  squeezes  repeats  from any
  180.      remaining characters using set2.
  181.  
  182.      The --squeeze-repeats option may also be used when translating, in  which
  183.      case  tr  first  peforms  translation,  then  squeezes  repeats  from any
  184.      remaining characters using set2.
  185.  
  186.      Here are some examples to illustrate various combinations of options:
  187.  
  188.      Remove all zero bytes:
  189.           tr -d '\000'
  190.  
  191.      Put all words on lines by themselves.  This converts all non-alphanumeric
  192.      characters  to  newlines,  then squeezes each string of repeated newlines
  193.      into a single newline:
  194.           tr -cs '[a-zA-Z0-9]' '[\n*]'
  195.  
  196.      Convert each sequence of repeated newlines to a single newline:
  197.           tr -s '\n'
  198.  
  199.      WARNING MESSAGES
  200.  
  201.      Setting  the  environment  variable  POSIXLY_CORRECT  turns  off  several
  202.      warning  and  error  messages,  for  strict compliance with POSIX.2.  The
  203.      messages normally occur in the following circumstances:
  204.  
  205.      1.  When the --delete option is given but --squeeze-repeats is  not,  and
  206.      string2  is  given,  GNU  tr by default prints a usage message and exits,
  207.      because string2 would not be used.  The  POSIX  specification  says  that
  208.      string2  must  be ignored in this case.  Silently ignoring arguments is a
  209.      bad idea.
  210.  
  211.      2.  When an ambiguous octal  escape  is  given.   For  example,  \400  is
  212.      actually  \40  followed  by the digit 0, because the value 400 octal does
  213.      not fit into a single byte.
  214.  
  215.      Note that GNU tr does not provide complete BSD or System V compatibility.
  216.      For  example,  there  is no option to disable interpretation of the POSIX
  217.      constructs [:alpha:], [=c=], and [c*10].  Also, GNU tr  does  not  delete
  218.      zero bytes automatically, unlike traditional UNIX versions, which provide
  219.      no way to preserve zero bytes.
  220.  
  221.      The long-named options can be introduced with `+' as well  as  `--',  for
  222.      compatibility with previous releases.  Eventually support for `+' will be
  223.      removed, because it is incompatible with the POSIX.2 standard.
  224.