info > tr(1)

File: coreutils.info,  Node: tr invocation,  Next: expand invocation,  Up: Operating on characters

9.1 'tr': Translate, squeeze, and/or delete characters

Synopsis:

     tr [OPTION]... STRING1 [STRING2]

   'tr' copies standard input to standard output, performing one of the
following operations:

   * translate, and optionally squeeze repeated characters in the
     result,
   * squeeze repeated characters,
   * delete characters,
   * delete characters, then squeeze repeated characters from the
     result.

   The STRING1 and STRING2 operands define arrays of characters ARRAY1
and ARRAY2.  By default ARRAY1 lists input characters that 'tr' operates
on, and ARRAY2 lists corresponding translations.  In some cases the
second operand is omitted.

   The program accepts the following options.  Also see *note Common
options::.  Options must precede operands.

'-c'
'-C'
'--complement'
     Instead of ARRAY1, use its complement (all characters not specified
     by STRING1), in ascending order.  Use this option with caution in
     multibyte locales where its meaning is not always clear or
     portable; see *note Character arrays::.

'-d'
'--delete'
     Delete characters in ARRAY1; do not translate.

'-s'
'--squeeze-repeats'
     Replace each sequence of a repeated character that is listed in the
     last specified ARRAY, with a single occurrence of that character.

'-t'
'--truncate-set1'
     Truncate ARRAY1 to the length of ARRAY2.

   An exit status of zero indicates success, and a nonzero value
indicates failure.

* Menu:

* Character arrays::            Specifying arrays of characters.
* Translating::                 Changing characters to other characters.
* Squeezing and deleting::      Removing characters.

File: coreutils.info,  Node: Character arrays,  Next: Translating,  Up: tr invocation

9.1.1 Specifying arrays of characters

The STRING1 and STRING2 operands are not regular expressions, even
though they may look similar.  Instead, they merely represent arrays of
characters.  As a GNU extension to POSIX, an empty string operand
represents an empty array of characters.

   The interpretation of STRING1 and STRING2 depends on locale.  GNU
'tr' fully supports only safe single-byte locales, where each possible
input byte represents a single character.  Unfortunately, this means GNU
'tr' will not handle commands like 'tr o" ??' the way you might expect,
since (assuming a UTF-8 encoding) this is equivalent to 'tr '\303\266'
'\305\201'' and GNU 'tr' will simply transliterate all '\303' bytes to
'\305' bytes, etc.  POSIX does not clearly specify the behavior of 'tr'
in locales where characters are represented by byte sequences instead of
by individual bytes, or where data might contain invalid bytes that are
encoding errors.  To avoid problems in this area, you can run 'tr' in a
safe single-byte locale by using a shell command like 'LC_ALL=C tr'
instead of plain 'tr'.

   Although most characters simply represent themselves in STRING1 and
STRING2, the strings can contain shorthands listed below, for
convenience.  Some shorthands can be used only in STRING1 or STRING2, as
noted below.

Backslash escapes

     The following backslash escape sequences are recognized:

     '\a'
          Bell (BEL, Control-G).
     '\b'
          Backspace (BS, Control-H).
     '\f'
          Form feed (FF, Control-L).
     '\n'
          Newline (LF, Control-J).
     '\r'
          Carriage return (CR, Control-M).
     '\t'
          Tab (HT, Control-I).
     '\v'
          Vertical tab (VT, Control-K).
     '\OOO'
          The eight-bit byte with the value given by OOO, which is the
          longest sequence of one to three octal digits following the
          backslash.  For portability, OOO should represent a value that
          fits in eight bits.  As a GNU extension to POSIX, if the value
          would not fit, then only the first two digits of OOO are used,
          e.g., '\400' is equivalent to '\0400' and represents a
          two-byte sequence.
     '\\'
          A backslash.

     It is an error if no character follows an unescaped backslash.  As
     a GNU extension, a backslash followed by a character not listed
     above is interpreted as that character, removing any special
     significance; this can be used to escape the characters '[' and '-'
     when they would otherwise be special.

Ranges

     The notation 'M-N' expands to the characters from M through N, in
     ascending order.  M should not collate after N; if it does, an
     error results.  As an example, '0-9' is the same as '0123456789'.

     GNU 'tr' does not support the System V syntax that uses square
     brackets to enclose ranges.  Translations specified in that format
     sometimes work as expected, since the brackets are often
     transliterated to themselves.  However, they should be avoided
     because they sometimes behave unexpectedly.  For example, 'tr -d
     '[0-9]'' deletes brackets as well as digits.

     Many historically common and even accepted uses of ranges are not
     fully portable.  For example, on EBCDIC hosts using the 'A-Z' range
     will not do what most would expect because 'A' through 'Z' are not
     contiguous as they are in ASCII.  One way to work around this is to
     use character classes (see below).  Otherwise, it is most portable
     (and most ugly) to enumerate the members of the ranges.

Repeated characters

     The notation '[C*N]' in STRING2 expands to N copies of character C.
     Thus, '[y*6]' is the same as 'yyyyyy'.  The notation '[C*]' in
     STRING2 expands to as many copies of C as are needed to make ARRAY2
     as long as ARRAY1.  If N begins with '0', it is interpreted in
     octal, otherwise in decimal.  A zero-valued N is treated as if it
     were absent.

Character classes

     The notation '[:CLASS:]' expands to all characters in the
     (predefined) class CLASS.  When the '--delete' ('-d') and
     '--squeeze-repeats' ('-s') options are both given, any character
     class can be used in STRING2.  Otherwise, only the character
     classes 'lower' and 'upper' are accepted in STRING2, and then only
     if the corresponding character class ('upper' and 'lower',
     respectively) is specified in the same relative position in
     STRING1.  Doing this specifies case conversion.  Except for case
     conversion, a class's characters appear in no particular order.
     The class names are given below; an error results when an invalid
     class name is given.

     'alnum'
          Letters and digits.
     'alpha'
          Letters.
     'blank'
          Horizontal whitespace.
     'cntrl'
          Control characters.
     'digit'
          Digits.
     'graph'
          Printable characters, not including space.
     'lower'
          Lowercase letters.
     'print'
          Printable characters, including space.
     'punct'
          Punctuation characters.
     'space'
          Horizontal or vertical whitespace.
     'upper'
          Uppercase letters.
     'xdigit'
          Hexadecimal digits.

Equivalence classes

     The syntax '[=C=]' expands to all characters equivalent to C, in no
     particular order.  These equivalence classes are allowed in STRING2
     only when '--delete' ('-d') and '--squeeze-repeats' '-s' are both
     given.

     Although equivalence classes are intended to support non-English
     alphabets, there seems to be no standard way to define them or
     determine their contents.  Therefore, they are not fully
     implemented in GNU 'tr'; each character's equivalence class
     consists only of that character, which is of no particular use.

File: coreutils.info,  Node: Translating,  Next: Squeezing and deleting,  Prev: Character arrays,  Up: tr invocation

9.1.2 Translating

'tr' performs translation when STRING1 and STRING2 are both given and
the '--delete' ('-d') option is not given.  'tr' translates each
character of its input that is in ARRAY1 to the corresponding character
in ARRAY2.  Characters not in ARRAY1 are passed through unchanged.

   As a GNU extension to POSIX, when a character appears more than once
in ARRAY1, only the final instance is used.  For example, these two
commands are equivalent:

     tr aaa xyz
     tr a z

   A common use of 'tr' is to convert lowercase characters to uppercase.
This can be done in many ways.  Here are three of them:

     tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
     tr a-z A-Z
     tr '[:lower:]' '[:upper:]'

However, ranges like 'a-z' are not portable outside the C locale.

   When 'tr' is performing translation, ARRAY1 and ARRAY2 typically have
the same length.  If ARRAY1 is shorter than ARRAY2, the extra characters
at the end of ARRAY2 are ignored.

   On the other hand, making ARRAY1 longer than ARRAY2 is not portable;
POSIX says that the result is undefined.  In this situation, BSD 'tr'
pads ARRAY2 to the length of ARRAY1 by repeating the last character of
ARRAY2 as many times as necessary.  System V 'tr' truncates ARRAY1 to
the length of ARRAY2.

   By default, GNU 'tr' handles this case like BSD 'tr'.  When the
'--truncate-set1' ('-t') option is given, GNU 'tr' handles this case
like the System V 'tr' instead.  This option is ignored for operations
other than translation.

   Acting like System V 'tr' in this case breaks the relatively common
BSD idiom:

     tr -cs A-Za-z0-9 '\012'

because it converts only zero bytes (the first element in the complement
of ARRAY1), rather than all non-alphanumerics, to newlines.

By the way, the above idiom is not portable because it uses ranges, and
it assumes that the octal code for newline is 012.  Here is a better way
to write it:

     tr -cs '[:alnum:]' '[\n*]'

File: coreutils.info,  Node: Squeezing and deleting,  Prev: Translating,  Up: tr invocation

9.1.3 Squeezing repeats and deleting

When given just the '--delete' ('-d') option, 'tr' removes any input
characters that are in ARRAY1.

   When given just the '--squeeze-repeats' ('-s') option and not
translating, 'tr' replaces each input sequence of a repeated character
that is in ARRAY1 with a single occurrence of that character.

   When given both '--delete' and '--squeeze-repeats', 'tr' first
performs any deletions using ARRAY1, then squeezes repeats from any
remaining characters using ARRAY2.

   The '--squeeze-repeats' option may also be used when translating, in
which case 'tr' first performs translation, then squeezes repeats from
any remaining characters using ARRAY2.

   Here are some examples to illustrate various combinations of options:

   * Remove all zero bytes:

          tr -d '\0'

   * Put all words on lines by themselves.  This converts all
     non-alphanumeric characters to newlines, then squeezes each string
     of repeated newlines into a single newline:

          tr -cs '[:alnum:]' '[\n*]'

   * Convert each sequence of repeated newlines to a single newline.
     I.e., delete empty lines:

          tr -s '\n'

   * Find doubled occurrences of words in a document.  For example,
     people often write "the the" with the repeated words separated by a
     newline.  The Bourne shell script below works first by converting
     each sequence of punctuation and blank characters to a single
     newline.  That puts each "word" on a line by itself.  Next it maps
     all uppercase characters to lower case, and finally it runs 'uniq'
     with the '-d' option to print out only the words that were
     repeated.

          #!/bin/sh
          cat -- "$@" \
            | tr -s '[:punct:][:blank:]' '[\n*]' \
            | tr '[:upper:]' '[:lower:]' \
            | uniq -d

   * Deleting a small set of characters is usually straightforward.  For
     example, to remove all 'a's, 'x's, and 'M's you would do this:

          tr -d axM

     However, when '-' is one of those characters, it can be tricky
     because '-' has special meanings.  Performing the same task as
     above but also removing all '-' characters, we might try 'tr -d
     -axM', but that would fail because 'tr' would try to interpret '-a'
     as a command-line option.  Alternatively, we could try putting the
     hyphen inside the string, 'tr -d a-xM', but that wouldn't work
     either because it would make 'tr' interpret 'a-x' as the range of
     characters 'a'...'x' rather than the three.  One way to solve the
     problem is to put the hyphen at the end of the list of characters:

          tr -d axM-

     Or you can use '--' to terminate option processing:

          tr -d -- -axM