home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-dist / textutils-1.19-bin.lha / info / textutils.info-2 < prev    next >
Encoding:
GNU Info File  |  1996-10-12  |  43.1 KB  |  1,123 lines
  1. This is Info file textutils.info, produced by Makeinfo-1.64 from the
  2. input file /ade-src/fsf/textutils/doc/textutils.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * Text utilities: (textutils).          GNU text utilities.
  6. * cat: (textutils)cat invocation.               Concatenate and write files.
  7. * cksum: (textutils)cksum invocation.           Print POSIX CRC checksum.
  8. * comm: (textutils)comm invocation.             Compare sorted files by line.
  9. * csplit: (textutils)csplit invocation.         Split by context.
  10. * cut: (textutils)cut invocation.               Print selected parts of lines.
  11. * expand: (textutils)expand invocation.         Convert tabs to spaces.
  12. * fmt: (textutils)fmt invocation.               Reformat paragraph text.
  13. * fold: (textutils)fold invocation.             Wrap long input lines.
  14. * head: (textutils)head invocation.             Output the first part of files.
  15. * join: (textutils)join invocation.             Join lines on a common field.
  16. * md5sum: (textutils)md5sum invocation.         Print or check message-digests.
  17. * nl: (textutils)nl invocation.                 Number lines and write files.
  18. * od: (textutils)od invocation.                 Dump files in octal, etc.
  19. * paste: (textutils)paste invocation.           Merge lines of files.
  20. * pr: (textutils)pr invocation.                 Paginate or columnate files.
  21. * sort: (textutils)sort invocation.             Sort text files.
  22. * split: (textutils)split invocation.           Split into fixed-size pieces.
  23. * sum: (textutils)sum invocation.               Print traditional checksum.
  24. * tac: (textutils)tac invocation.               Reverse files.
  25. * tail: (textutils)tail invocation.             Output the last part of files.
  26. * tr: (textutils)tr invocation.                 Translate characters.
  27. * unexpand: (textutils)unexpand invocation.     Convert spaces to tabs.
  28. * uniq: (textutils)uniq invocation.             Uniqify files.
  29. * wc: (textutils)wc invocation.                 Byte, word, and line counts.
  30. END-INFO-DIR-ENTRY
  31.  
  32.    This file documents the GNU text utilities.
  33.  
  34.    Copyright (C) 1994, 95, 96 Free Software Foundation, Inc.
  35.  
  36.    Permission is granted to make and distribute verbatim copies of this
  37. manual provided the copyright notice and this permission notice are
  38. preserved on all copies.
  39.  
  40.    Permission is granted to copy and distribute modified versions of
  41. this manual under the conditions for verbatim copying, provided that
  42. the entire resulting derived work is distributed under the terms of a
  43. permission notice identical to this one.
  44.  
  45.    Permission is granted to copy and distribute translations of this
  46. manual into another language, under the above conditions for modified
  47. versions, except that this permission notice may be stated in a
  48. translation approved by the Foundation.
  49.  
  50. 
  51. File: textutils.info,  Node: sort invocation,  Next: uniq invocation,  Up: Operating on sorted files
  52.  
  53. `sort': Sort text files
  54. =======================
  55.  
  56.    `sort' sorts, merges, or compares all the lines from the given
  57. files, or standard input if none are given or for a FILE of `-'.  By
  58. default, `sort' writes the results to standard output.  Synopsis:
  59.  
  60.      sort [OPTION]... [FILE]...
  61.  
  62.    `sort' has three modes of operation: sort (the default), merge, and
  63. check for sortedness.  The following options change the operation mode:
  64.  
  65. `-c'
  66.      Check whether the given files are already sorted: if they are not
  67.      all sorted, print an error message and exit with a status of 1.
  68.      Otherwise, exit successfully.
  69.  
  70. `-m'
  71.      Merge the given files by sorting them as a group.  Each input file
  72.      must always be individually sorted.  It always works to sort
  73.      instead of merge; merging is provided because it is faster, in the
  74.      case where it works.
  75.  
  76.    A pair of lines is compared as follows: if any key fields have been
  77. specified, `sort' compares each pair of fields, in the order specified
  78. on the command line, according to the associated ordering options,
  79. until a difference is found or no fields are left.
  80.  
  81.    If any of the global options `Mbdfinr' are given but no key fields
  82. are specified, `sort' compares the entire lines according to the global
  83. options.
  84.  
  85.    Finally, as a last resort when all keys compare equal (or if no
  86. ordering options were specified at all), `sort' compares the lines byte
  87. by byte in machine collating sequence.  The last resort comparison
  88. honors the `-r' global option.  The `-s' (stable) option disables this
  89. last-resort comparison so that lines in which all fields compare equal
  90. are left in their original relative order.  If no fields or global
  91. options are specified, `-s' has no effect.
  92.  
  93.    GNU `sort' (as specified for all GNU utilities) has no limits on
  94. input line length or restrictions on bytes allowed within lines.  In
  95. addition, if the final byte of an input file is not a newline, GNU
  96. `sort' silently supplies one.
  97.  
  98.    Upon any error, `sort' exits with a status of `2'.
  99.  
  100.    If the environment variable `TMPDIR' is set, `sort' uses its value
  101. as the directory for temporary files instead of `/tmp'.  The `-T
  102. TEMPDIR' option in turn overrides the environment variable.
  103.  
  104.    The following options affect the ordering of output lines.  They may
  105. be specified globally or as part of a specific key field.  If no key
  106. fields are specified, global options apply to comparison of entire
  107. lines; otherwise the global options are inherited by key fields that do
  108. not specify any special options of their own.
  109.  
  110. `-b'
  111.      Ignore leading blanks when finding sort keys in each line.
  112.  
  113. `-d'
  114.      Sort in "phone directory" order: ignore all characters except
  115.      letters, digits and blanks when sorting.
  116.  
  117. `-f'
  118.      Fold lowercase characters into the equivalent uppercase characters
  119.      when sorting so that, for example, `b' and `B' sort as equal.
  120.  
  121. `-g'
  122.      Sort numerically, but use strtod(3) to arrive at the numeric
  123.      values.  This allows floating point numbers to be specified in
  124.      scientific notation, like `1.0e-34' and `10e100'.  Use this option
  125.      only if there is no alternative;  it is much slower than `-n' and
  126.      numbers with too many significant digits will be compared as if
  127.      they had been truncated.  In addition, numbers outside the range
  128.      of representable double precision floating point numbers are
  129.      treated as if they were zeroes; overflow and underflow are not
  130.      reported.
  131.  
  132. `-i'
  133.      Ignore characters outside the printable ASCII range 040-0176 octal
  134.      (inclusive) when sorting.
  135.  
  136. `-M'
  137.      An initial string, consisting of any amount of whitespace, followed
  138.      by three letters abbreviating a month name, is folded to UPPER
  139.      case and compared in the order `JAN' < `FEB' < ... < `DEC'.
  140.      Invalid names compare low to valid names.
  141.  
  142. `-n'
  143.      Sort numerically: the number begins each line; specifically, it
  144.      consists of optional whitespace, an optional `-' sign, and zero or
  145.      more digits, optionally followed by a decimal point and zero or
  146.      more digits.
  147.  
  148.      `sort -n' uses what might be considered an unconventional method
  149.      to compare strings representing floating point numbers.  Rather
  150.      than first converting each string to the C `double' type and then
  151.      comparing those values, sort aligns the decimal points in the two
  152.      strings and compares the strings a character at a time.  One
  153.      benefit of using this approach is its speed.  In practice this is
  154.      much more efficient than performing the two corresponding
  155.      string-to-double (or even string-to-integer) conversions and then
  156.      comparing doubles.  In addition, there is no corresponding loss of
  157.      precision.  Converting each string to `double' before comparison
  158.      would limit precision to about 16 digits on most systems.
  159.  
  160.      Neither a leading `+' nor exponential notation is recognized.  To
  161.      compare such strings numerically, use the `-g' option.
  162.  
  163. `-r'
  164.      Reverse the result of comparison, so that lines with greater key
  165.      values appear earlier in the output instead of later.
  166.  
  167.    Other options are:
  168.  
  169. `-o OUTPUT-FILE'
  170.      Write output to OUTPUT-FILE instead of standard output.  If
  171.      OUTPUT-FILE is one of the input files, `sort' copies it to a
  172.      temporary file before sorting and writing the output to
  173.      OUTPUT-FILE.
  174.  
  175. `-t SEPARATOR'
  176.      Use character SEPARATOR as the field separator when finding the
  177.      sort keys in each line.  By default, fields are separated by the
  178.      empty string between a non-whitespace character and a whitespace
  179.      character.  That is, given the input line ` foo bar', `sort'
  180.      breaks it into fields ` foo' and ` bar'.  The field separator is
  181.      not considered to be part of either the field preceding or the
  182.      field following.
  183.  
  184. `-u'
  185.      For the default case or the `-m' option, only output the first of
  186.      a sequence of lines that compare equal.  For the `-c' option,
  187.      check that no pair of consecutive lines compares equal.
  188.  
  189. `-k POS1[,POS2]'
  190.      The recommended, POSIX, option for specifying a sort field.  The
  191.      field consists of the line between POS1 and POS2 (or the end of
  192.      the line, if POS2 is omitted), inclusive.  Fields and character
  193.      positions are numbered starting with 1.  See below.
  194.  
  195. `-z'
  196.      Treat the input as a set of lines, each terminated by a zero byte
  197.      (ASCII NUL (Null) character) instead of a ASCII LF (Line Feed.)
  198.      This option can be useful in conjunction with `perl -0' or `find
  199.      -print0' and `xargs -0' which do the same in order to reliably
  200.      handle arbitrary pathnames (even those which contain Line Feed
  201.      characters.)
  202.  
  203. `+POS1[-POS2]'
  204.      The obsolete, traditional option for specifying a sort field.  The
  205.      field consists of the line between POS1 and up to but *not
  206.      including* POS2 (or the end of the line if POS2 is omitted).
  207.      Fields and character positions are numbered starting with 0.  See
  208.      below.
  209.  
  210.    In addition, when GNU `sort' is invoked with exactly one argument,
  211. options `--help' and `--version' are recognized.  *Note Common
  212. options::.
  213.  
  214.    Historical (BSD and System V) implementations of `sort' have
  215. differed in their interpretation of some options, particularly `-b',
  216. `-f', and `-n'.  GNU sort follows the POSIX behavior, which is usually
  217. (but not always!) like the System V behavior.  According to POSIX, `-n'
  218. no longer implies `-b'.  For consistency, `-M' has been changed in the
  219. same way.  This may affect the meaning of character positions in field
  220. specifications in obscure cases.  The only fix is to add an explicit
  221. `-b'.
  222.  
  223.    A position in a sort field specified with the `-k' or `+' option has
  224. the form `F.C', where F is the number of the field to use and C is the
  225. number of the first character from the beginning of the field (for
  226. `+POS') or from the end of the previous field (for `-POS').  If the `.C'
  227. is omitted, it is taken to be the first character in the field.  If the
  228. `-b' option was specified, the `.C' part of a field specification is
  229. counted from the first nonblank character of the field (for `+POS') or
  230. from the first nonblank character following the previous field (for
  231. `-POS').
  232.  
  233.    A sort key option may also have any of the option letters `Mbdfinr'
  234. appended to it, in which case the global ordering options are not used
  235. for that particular field.  The `-b' option may be independently
  236. attached to either or both of the `+POS' and `-POS' parts of a field
  237. specification, and if it is inherited from the global options it will
  238. be attached to both.  If a `-n' or `-M' option is used, thus implying a
  239. `-b' option, the `-b' option is taken to apply to both the `+POS' and
  240. the `-POS' parts of a key specification.  Keys may span multiple fields.
  241.  
  242.    Here are some examples to illustrate various combinations of options.
  243. In them, the POSIX `-k' option is used to specify sort keys rather than
  244. the obsolete `+POS1-POS2' syntax.
  245.  
  246.    * Sort in descending (reverse) numeric order.
  247.  
  248.           sort -nr
  249.  
  250.      Sort alphabetically, omitting the first and second fields.  This
  251.      uses a single key composed of the characters beginning at the
  252.      start of field three and extending to the end of each line.
  253.  
  254.           sort -k3
  255.  
  256.    * Sort numerically on the second field and resolve ties by sorting
  257.      alphabetically on the third and fourth characters of field five.
  258.      Use `:' as the field delimiter.
  259.  
  260.           sort -t : -k 2,2n -k 5.3,5.4
  261.  
  262.      Note that if you had written `-k 2' instead of `-k 2,2' `sort'
  263.      would have used all characters beginning in the second field and
  264.      extending to the end of the line as the primary *numeric* key.
  265.      For the large majority of applications, treating keys spanning
  266.      more than one field as numeric will not do what you expect.
  267.  
  268.      Also note that the `n' modifier was applied to the field-end
  269.      specifier for the first key.  It would have been equivalent to
  270.      specify `-k 2n,2' or `-k 2n,2n'.  All modifiers except `b' apply
  271.      to the associated *field*, regardless of whether the modifier
  272.      character is attached to the field-start and/or the field-end part
  273.      of the key specifier.
  274.  
  275.    * Sort the password file on the fifth field and ignore any leading
  276.      white space.  Sort lines with equal values in field five on the
  277.      numeric user ID in field three.
  278.  
  279.           sort -t : -k 5b,5 -k 3,3n /etc/passwd
  280.  
  281.      An alternative is to use the global numeric modifier `-n'.
  282.  
  283.           sort -t : -n -k 5b,5 -k 3,3 /etc/passwd
  284.  
  285.    * Generate a tags file in case insensitive sorted order.
  286.           find src -type f -print0 | sort -t / -z -f | xargs -0 etags --append
  287.  
  288.      The use of `-print0', `-z', and `-0' in this case mean that
  289.      pathnames that contain Line Feed characters will not get broken up
  290.      by the sort operation.
  291.  
  292.      Finally, to ignore both leading and trailing white space, you
  293.      could have applied the `b' modifier to the field-end specifier for
  294.      the first key,
  295.  
  296.           sort -t : -n -k 5b,5b -k 3,3 /etc/passwd
  297.  
  298.      or by using the global `-b' modifier instead of `-n' and an
  299.      explicit `n' with the second key specifier.
  300.  
  301.           sort -t : -b -k 5,5 -k 3,3n /etc/passwd
  302.  
  303. 
  304. File: textutils.info,  Node: uniq invocation,  Next: comm invocation,  Prev: sort invocation,  Up: Operating on sorted files
  305.  
  306. `uniq': Uniqify files
  307. =====================
  308.  
  309.    `uniq' writes the unique lines in the given `input', or standard
  310. input if nothing is given or for an INPUT name of `-'.  Synopsis:
  311.  
  312.      uniq [OPTION]... [INPUT [OUTPUT]]
  313.  
  314.    By default, `uniq' prints the unique lines in a sorted file, i.e.,
  315. discards all but one of identical successive lines.  Optionally, it can
  316. instead show only lines that appear exactly once, or lines that appear
  317. more than once.
  318.  
  319.    The input must be sorted.  If your input is not sorted, perhaps you
  320. want to use `sort -u'.
  321.  
  322.    If no OUTPUT file is specified, `uniq' writes to standard output.
  323.  
  324.    The program accepts the following options.  Also see *Note Common
  325. options::.
  326.  
  327. `-N'
  328. `-f N'
  329. `--skip-fields=N'
  330.      Skip N fields on each line before checking for uniqueness.  Fields
  331.      are sequences of non-space non-tab characters that are separated
  332.      from each other by at least one spaces or tabs.
  333.  
  334. `+N'
  335. `-s N'
  336. `--skip-chars=N'
  337.      Skip N characters before checking for uniqueness.  If you use both
  338.      the field and character skipping options, fields are skipped over
  339.      first.
  340.  
  341. `-c'
  342. `--count'
  343.      Print the number of times each line occurred along with the line.
  344.  
  345. `-i'
  346. `--ignore-case'
  347.      Ignore differences in case when comparing lines.
  348.  
  349. `-d'
  350. `--repeated'
  351.      Print only duplicate lines.
  352.  
  353. `-u'
  354. `--unique'
  355.      Print only unique lines.
  356.  
  357. `-w N'
  358. `--check-chars=N'
  359.      Compare N characters on each line (after skipping any specified
  360.      fields and characters).  By default the entire rest of the lines
  361.      are compared.
  362.  
  363. 
  364. File: textutils.info,  Node: comm invocation,  Prev: uniq invocation,  Up: Operating on sorted files
  365.  
  366. `comm': Compare two sorted files line by line
  367. =============================================
  368.  
  369.    `comm' writes to standard output lines that are common, and lines
  370. that are unique, to two input files; a file name of `-' means standard
  371. input.  Synopsis:
  372.  
  373.      comm [OPTION]... FILE1 FILE2
  374.  
  375.    The input files must be sorted before `comm' can be used.
  376.  
  377.    With no options, `comm' produces three column output.  Column one
  378. contains lines unique to FILE1, column two contains lines unique to
  379. FILE2, and column three contains lines common to both files.  Columns
  380. are separated by TAB.
  381.  
  382.    The options `-1', `-2', and `-3' suppress printing of the
  383. corresponding columns.  Also see *Note Common options::.
  384.  
  385. 
  386. File: textutils.info,  Node: Operating on fields within a line,  Next: Operating on characters,  Prev: Operating on sorted files,  Up: Top
  387.  
  388. Operating on fields within a line
  389. *********************************
  390.  
  391. * Menu:
  392.  
  393. * cut invocation::              Print selected parts of lines.
  394. * paste invocation::            Merge lines of files.
  395. * join invocation::             Join lines on a common field.
  396.  
  397. 
  398. File: textutils.info,  Node: cut invocation,  Next: paste invocation,  Up: Operating on fields within a line
  399.  
  400. `cut': Print selected parts of lines
  401. ====================================
  402.  
  403.    `cut' writes to standard output selected parts of each line of each
  404. input file, or standard input if no files are given or for a file name
  405. of `-'.  Synopsis:
  406.  
  407.      cut [OPTION]... [FILE]...
  408.  
  409.    In the table which follows, the BYTE-LIST, CHARACTER-LIST, and
  410. FIELD-LIST are one or more numbers or ranges (two numbers separated by
  411. a dash) separated by commas.  Bytes, characters, and fields are
  412. numbered from starting at 1.  Incomplete ranges may be given: `-M'
  413. means `1-M'; `N-' means `N' through end of line or last field.
  414.  
  415.    The program accepts the following options.  Also see *Note Common
  416. options::.
  417.  
  418. `-b BYTE-LIST'
  419. `--bytes=BYTE-LIST'
  420.      Print only the bytes in positions listed in BYTE-LIST.  Tabs and
  421.      backspaces are treated like any other character; they take up 1
  422.      byte.
  423.  
  424. `-c CHARACTER-LIST'
  425. `--characters=CHARACTER-LIST'
  426.      Print only characters in positions listed in CHARACTER-LIST.  The
  427.      same as `-b' for now, but internationalization will change that.
  428.      Tabs and backspaces are treated like any other character; they
  429.      take up 1 character.
  430.  
  431. `-f FIELD-LIST'
  432. `--fields=FIELD-LIST'
  433.      Print only the fields listed in FIELD-LIST.  Fields are separated
  434.      by a TAB by default.
  435.  
  436. `-d DELIM'
  437. `--delimiter=DELIM'
  438.      For `-f', fields are separated by the first character in DELIM
  439.      (default is TAB).
  440.  
  441. `-n'
  442.      Do not split multi-byte characters (no-op for now).
  443.  
  444. `-s'
  445. `--only-delimited'
  446.      For `-f', do not print lines that do not contain the field
  447.      separator character.
  448.  
  449. 
  450. File: textutils.info,  Node: paste invocation,  Next: join invocation,  Prev: cut invocation,  Up: Operating on fields within a line
  451.  
  452. `paste': Merge lines of files
  453. =============================
  454.  
  455.    `paste' writes to standard output lines consisting of sequentially
  456. corresponding lines of each given file, separated by TAB.  Standard
  457. input is used for a file name of `-' or if no input files are given.
  458.  
  459.    Synopsis:
  460.  
  461.      paste [OPTION]... [FILE]...
  462.  
  463.    The program accepts the following options.  Also see *Note Common
  464. options::.
  465.  
  466. `-s'
  467. `--serial'
  468.      Paste the lines of one file at a time rather than one line from
  469.      each file.
  470.  
  471. `-d DELIM-LIST'
  472. `--delimiters DELIM-LIST'
  473.      Consecutively use the characters in DELIM-LIST instead of TAB to
  474.      separate merged lines.  When DELIM-LIST is exhausted, start again
  475.      at its beginning.
  476.  
  477. 
  478. File: textutils.info,  Node: join invocation,  Prev: paste invocation,  Up: Operating on fields within a line
  479.  
  480. `join': Join lines on a common field
  481. ====================================
  482.  
  483.    `join' writes to standard output a line for each pair of input lines
  484. that have identical join fields.  Synopsis:
  485.  
  486.      join [OPTION]... FILE1 FILE2
  487.  
  488.    Either FILE1 or FILE2 (but not both) can be `-', meaning standard
  489. input.  FILE1 and FILE2 should be already sorted in increasing order
  490. (not numerically) on the join fields; unless the `-t' option is given,
  491. they should be sorted ignoring blanks at the start of the join field,
  492. as in `sort -b'.  If the `--ignore-case' option is given, lines should
  493. be sorted without regard to the case of characters in the join field,
  494. as in `sort -f'.
  495.  
  496.    The defaults are: the join field is the first field in each line;
  497. fields in the input are separated by one or more blanks, with leading
  498. blanks on the line ignored; fields in the output are separated by a
  499. space; each output line consists of the join field, the remaining
  500. fields from FILE1, then the remaining fields from FILE2.
  501.  
  502.    The program accepts the following options.  Also see *Note Common
  503. options::.
  504.  
  505. `-a FILE-NUMBER'
  506.      Print a line for each unpairable line in file FILE-NUMBER (either
  507.      `1' or `2'), in addition to the normal output.
  508.  
  509. `-e STRING'
  510.      Replace those output fields that are missing in the input with
  511.      STRING.
  512.  
  513. `-i'
  514. `--ignore-case'
  515.      Ignore differences in case when comparing keys.  With this option,
  516.      the lines of the input files must be ordered in the same way.  Use
  517.      `sort -f' to produce this ordering.
  518.  
  519. `-1 FIELD'
  520. `-j1 FIELD'
  521.      Join on field FIELD (a positive integer) of file 1.
  522.  
  523. `-2 FIELD'
  524. `-j2 FIELD'
  525.      Join on field FIELD (a positive integer) of file 2.
  526.  
  527. `-j FIELD'
  528.      Equivalent to `-1 FIELD -2 FIELD'.
  529.  
  530. `-o FIELD-LIST...'
  531.      Construct each output line according to the format in FIELD-LIST.
  532.      Each element in FIELD-LIST is either the single character `0' or
  533.      has the form M.N where the file number, M, is `1' or `2' and N is
  534.      a positive field number.
  535.  
  536.      A field specification of `0' denotes the join field.  In most
  537.      cases, the functionality of the `0' field spec may be reproduced
  538.      using the explicit M.N that corresponds to the join field.
  539.      However, when printing unpairable lines (using either of the `-a'
  540.      or `-v' options), there is no way to specify the join field using
  541.      M.N in FIELD-LIST if there are unpairable lines in both files.  To
  542.      give `join' that functionality, POSIX invented the `0' field
  543.      specification notation.
  544.  
  545.      The elements in FIELD-LIST are separated by commas or blanks.
  546.      Multiple FIELD-LIST arguments can be given after a single `-o'
  547.      option; the values of all lists given with `-o' are concatenated
  548.      together.  All output lines - including those printed because of
  549.      any -a or -v option - are subject to the specified FIELD-LIST.
  550.  
  551. `-t CHAR'
  552.      Use character CHAR as the input and output field separator.
  553.  
  554. `-v FILE-NUMBER'
  555.      Print a line for each unpairable line in file FILE-NUMBER (either
  556.      `1' or `2'), instead of the normal output.
  557.  
  558.    In addition, when GNU `join' is invoked with exactly one argument,
  559. options `--help' and `--version' are recognized.  *Note Common
  560. options::.
  561.  
  562. 
  563. File: textutils.info,  Node: Operating on characters,  Next: Opening the software toolbox,  Prev: Operating on fields within a line,  Up: Top
  564.  
  565. Operating on characters
  566. ***********************
  567.  
  568.    This commands operate on individual characters.
  569.  
  570. * Menu:
  571.  
  572. * tr invocation::               Translate, squeeze, and/or delete characters.
  573. * expand invocation::           Convert tabs to spaces.
  574. * unexpand invocation::         Convert spaces to tabs.
  575.  
  576. 
  577. File: textutils.info,  Node: tr invocation,  Next: expand invocation,  Up: Operating on characters
  578.  
  579. `tr': Translate, squeeze, and/or delete characters
  580. ==================================================
  581.  
  582.    Synopsis:
  583.  
  584.      tr [OPTION]... SET1 [SET2]
  585.  
  586.    `tr' copies standard input to standard output, performing one of the
  587. following operations:
  588.  
  589.    * translate, and optionally squeeze repeated characters in the
  590.      result,
  591.  
  592.    * squeeze repeated characters,
  593.  
  594.    * delete characters,
  595.  
  596.    * delete characters, then squeeze repeated characters from the
  597.      result.
  598.  
  599.    The SET1 and (if given) SET2 arguments define ordered sets of
  600. characters, referred to below as SET1 and SET2.  These sets are the
  601. characters of the input that `tr' operates on.  The `--complement'
  602. (`-c') option replaces SET1 with its complement (all of the characters
  603. that are not in SET1).
  604.  
  605. * Menu:
  606.  
  607. * Character sets::              Specifying sets of characters.
  608. * Translating::                 Changing one characters to another.
  609. * Squeezing::                   Squeezing repeats and deleting.
  610. * Warnings in tr::              Warning messages.
  611.  
  612. 
  613. File: textutils.info,  Node: Character sets,  Next: Translating,  Up: tr invocation
  614.  
  615. Specifying sets of characters
  616. -----------------------------
  617.  
  618.    The format of the SET1 and SET2 arguments resembles the format of
  619. regular expressions; however, they are not regular expressions, only
  620. lists of characters.  Most characters simply represent themselves in
  621. these strings, but the strings can contain the shorthands listed below,
  622. for convenience.  Some of them can be used only in SET1 or SET2, as
  623. noted below.
  624.  
  625. Backslash escapes.
  626.      A backslash followed by a character not listed below causes an
  627.      error message.
  628.  
  629.     `\a'
  630.           Control-G,
  631.  
  632.     `\b'
  633.           Control-H,
  634.  
  635.     `\f'
  636.           Control-L,
  637.  
  638.     `\n'
  639.           Control-J,
  640.  
  641.     `\r'
  642.           Control-M,
  643.  
  644.     `\t'
  645.           Control-I,
  646.  
  647.     `\v'
  648.           Control-K,
  649.  
  650.     `\OOO'
  651.           The character with the value given by OOO, which is 1 to 3
  652.           octal digits,
  653.  
  654.     `\\'
  655.           A backslash.
  656.  
  657. Ranges.
  658.      The notation `M-N' expands to all of the characters from M through
  659.      N, in ascending order.  M should collate before N; if it doesn't,
  660.      an error results.  As an example, `0-9' is the same as
  661.      `0123456789'.  Although GNU `tr' does not support the System V
  662.      syntax that uses square brackets to enclose ranges, translations
  663.      specified in that format will still work as long as the brackets
  664.      in STRING1 correspond to identical brackets in STRING2.
  665.  
  666. Repeated characters.
  667.      The notation `[C*N]' in SET2 expands to N copies of character C.
  668.      Thus, `[y*6]' is the same as `yyyyyy'.  The notation `[C*]' in
  669.      STRING2 expands to as many copies of C as are needed to make SET2
  670.      as long as SET1.  If N begins with `0', it is interpreted in
  671.      octal, otherwise in decimal.
  672.  
  673. Character classes.
  674.      The notation `[:CLASS:]' expands to all of the characters in the
  675.      (predefined) class CLASS.  The characters expand in no particular
  676.      order, except for the `upper' and `lower' classes, which expand in
  677.      ascending order.  When the `--delete' (`-d') and
  678.      `--squeeze-repeats' (`-s') options are both given, any character
  679.      class can be used in SET2.  Otherwise, only the character classes
  680.      `lower' and `upper' are accepted in SET2, and then only if the
  681.      corresponding character class (`upper' and `lower', respectively)
  682.      is specified in the same relative position in SET1.  Doing this
  683.      specifies case conversion.  The class names are given below; an
  684.      error results when an invalid class name is given.
  685.  
  686.     `alnum'
  687.           Letters and digits.
  688.  
  689.     `alpha'
  690.           Letters.
  691.  
  692.     `blank'
  693.           Horizontal whitespace.
  694.  
  695.     `cntrl'
  696.           Control characters.
  697.  
  698.     `digit'
  699.           Digits.
  700.  
  701.     `graph'
  702.           Printable characters, not including space.
  703.  
  704.     `lower'
  705.           Lowercase letters.
  706.  
  707.     `print'
  708.           Printable characters, including space.
  709.  
  710.     `punct'
  711.           Punctuation characters.
  712.  
  713.     `space'
  714.           Horizontal or vertical whitespace.
  715.  
  716.     `upper'
  717.           Uppercase letters.
  718.  
  719.     `xdigit'
  720.           Hexadecimal digits.
  721.  
  722. Equivalence classes.
  723.      The syntax `[=C=]' expands to all of the characters that are
  724.      equivalent to C, in no particular order.  Equivalence classes are
  725.      a relatively recent invention intended to support non-English
  726.      alphabets.  But there seems to be no standard way to define them
  727.      or determine their contents.  Therefore, they are not fully
  728.      implemented in GNU `tr'; each character's equivalence class
  729.      consists only of that character, which is of no particular use.
  730.  
  731. 
  732. File: textutils.info,  Node: Translating,  Next: Squeezing,  Prev: Character sets,  Up: tr invocation
  733.  
  734. Translating
  735. -----------
  736.  
  737.    `tr' performs translation when SET1 and SET2 are both given and the
  738. `--delete' (`-d') option is not given.  `tr' translates each character
  739. of its input that is in SET1 to the corresponding character in SET2.
  740. Characters not in SET1 are passed through unchanged.  When a character
  741. appears more than once in SET1 and the corresponding characters in SET2
  742. are not all the same, only the final one is used.  For example, these
  743. two commands are equivalent:
  744.  
  745.      tr aaa xyz
  746.      tr a z
  747.  
  748.    A common use of `tr' is to convert lowercase characters to
  749. uppercase.  This can be done in many ways.  Here are three of them:
  750.  
  751.      tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
  752.      tr a-z A-Z
  753.      tr '[:lower:]' '[:upper:]'
  754.  
  755.    When `tr' is performing translation, SET1 and SET2 typically have
  756. the same length.  If SET1 is shorter than SET2, the extra characters at
  757. the end of SET2 are ignored.
  758.  
  759.    On the other hand, making SET1 longer than SET2 is not portable;
  760. POSIX.2 says that the result is undefined.  In this situation, BSD `tr'
  761. pads SET2 to the length of SET1 by repeating the last character of SET2
  762. as many times as necessary.  System V `tr' truncates SET1 to the length
  763. of SET2.
  764.  
  765.    By default, GNU `tr' handles this case like BSD `tr'.  When the
  766. `--truncate-set1' (`-t') option is given, GNU `tr' handles this case
  767. like the System V `tr' instead.  This option is ignored for operations
  768. other than translation.
  769.  
  770.    Acting like System V `tr' in this case breaks the relatively common
  771. BSD idiom:
  772.  
  773.      tr -cs A-Za-z0-9 '\012'
  774.  
  775. because it converts only zero bytes (the first element in the
  776. complement of SET1), rather than all non-alphanumerics, to newlines.
  777.  
  778. 
  779. File: textutils.info,  Node: Squeezing,  Next: Warnings in tr,  Prev: Translating,  Up: tr invocation
  780.  
  781. Squeezing repeats and deleting
  782. ------------------------------
  783.  
  784.    When given just the `--delete' (`-d') option, `tr' removes any input
  785. characters that are in SET1.
  786.  
  787.    When given just the `--squeeze-repeats' (`-s') option, `tr' replaces
  788. each input sequence of a repeated character that is in SET1 with a
  789. single occurrence of that character.
  790.  
  791.    When given both `--delete' and `--squeeze-repeats', `tr' first
  792. performs any deletions using SET1, then squeezes repeats from any
  793. remaining characters using SET2.
  794.  
  795.    The `--squeeze-repeats' option may also be used when translating, in
  796. which case `tr' first performs translation, then squeezes repeats from
  797. any remaining characters using SET2.
  798.  
  799.    Here are some examples to illustrate various combinations of options:
  800.  
  801.    * Remove all zero bytes:
  802.  
  803.           tr -d '\000'
  804.  
  805.    * Put all words on lines by themselves.  This converts all
  806.      non-alphanumeric characters to newlines, then squeezes each string
  807.      of repeated newlines into a single newline:
  808.  
  809.           tr -cs '[a-zA-Z0-9]' '[\n*]'
  810.  
  811.    * Convert each sequence of repeated newlines to a single newline:
  812.  
  813.           tr -s '\n'
  814.  
  815. 
  816. File: textutils.info,  Node: Warnings in tr,  Prev: Squeezing,  Up: tr invocation
  817.  
  818. Warning messages
  819. ----------------
  820.  
  821.    Setting the environment variable `POSIXLY_CORRECT' turns off the
  822. following warning and error messages, for strict compliance with
  823. POSIX.2.  Otherwise, the following diagnostics are issued:
  824.  
  825.   1. When the `--delete' option is given but `--squeeze-repeats' is
  826.      not, and SET2 is given, GNU `tr' by default prints a usage message
  827.      and exits, because SET2 would not be used.  The POSIX
  828.      specification says that SET2 must be ignored in this case.
  829.      Silently ignoring arguments is a bad idea.
  830.  
  831.   2. When an ambiguous octal escape is given.  For example, `\400' is
  832.      actually `\40' followed by the digit `0', because the value 400
  833.      octal does not fit into a single byte.
  834.  
  835.  
  836.    GNU `tr' does not provide complete BSD or System V compatibility.
  837. For example, it is impossible to disable interpretation of the POSIX
  838. constructs `[:alpha:]', `[=c=]', and `[c*10]'.  Also, GNU `tr' does not
  839. delete zero bytes automatically, unlike traditional Unix versions,
  840. which provide no way to preserve zero bytes.
  841.  
  842. 
  843. File: textutils.info,  Node: expand invocation,  Next: unexpand invocation,  Prev: tr invocation,  Up: Operating on characters
  844.  
  845. `expand': Convert tabs to spaces
  846. ================================
  847.  
  848.    `expand' writes the contents of each given FILE, or standard input
  849. if none are given or for a FILE of `-', to standard output, with tab
  850. characters converted to the appropriate number of spaces.  Synopsis:
  851.  
  852.      expand [OPTION]... [FILE]...
  853.  
  854.    By default, `expand' converts all tabs to spaces.  It preserves
  855. backspace characters in the output; they decrement the column count for
  856. tab calculations.  The default action is equivalent to `-8' (set tabs
  857. every 8 columns).
  858.  
  859.    The program accepts the following options.  Also see *Note Common
  860. options::.
  861.  
  862. `-TAB1[,TAB2]...'
  863. `-t TAB1[,TAB2]...'
  864. `--tabs=TAB1[,TAB2]...'
  865.      If only one tab stop is given, set the tabs TAB1 spaces apart
  866.      (default is 8).  Otherwise, set the tabs at columns TAB1, TAB2,
  867.      ... (numbered from 0), and replace any tabs beyond the last
  868.      tabstop given with single spaces.  If the tabstops are specified
  869.      with the `-t' or `--tabs' option, they can be separated by blanks
  870.      as well as by commas.
  871.  
  872. `-i'
  873. `--initial'
  874.      Only convert initial tabs (those that precede all non-space or
  875.      non-tab characters) on each line to spaces.
  876.  
  877. 
  878. File: textutils.info,  Node: unexpand invocation,  Prev: expand invocation,  Up: Operating on characters
  879.  
  880. `unexpand': Convert spaces to tabs
  881. ==================================
  882.  
  883.    `unexpand' writes the contents of each given FILE, or standard input
  884. if none are given or for a FILE of `-', to standard output, with
  885. strings of two or more space or tab characters converted to as many
  886. tabs as possible followed by as many spaces as are needed.  Synopsis:
  887.  
  888.      unexpand [OPTION]... [FILE]...
  889.  
  890.    By default, `unexpand' converts only initial spaces and tabs (those
  891. that precede all non space or tab characters) on each line.  It
  892. preserves backspace characters in the output; they decrement the column
  893. count for tab calculations.  By default, tabs are set at every 8th
  894. column.
  895.  
  896.    The program accepts the following options.  Also see *Note Common
  897. options::.
  898.  
  899. `-TAB1[,TAB2]...'
  900. `-t TAB1[,TAB2]...'
  901. `--tabs=TAB1[,TAB2]...'
  902.      If only one tab stop is given, set the tabs TAB1 spaces apart
  903.      instead of the default 8.  Otherwise, set the tabs at columns
  904.      TAB1, TAB2, ... (numbered from 0), and leave spaces and tabs
  905.      beyond the tabstops given unchanged.  If the tabstops are specified
  906.      with the `-t' or `--tabs' option, they can be separated by blanks
  907.      as well as by commas.  This option implies the `-a' option.
  908.  
  909. `-a'
  910. `--all'
  911.      Convert all strings of two or more spaces or tabs, not just initial
  912.      ones, to tabs.
  913.  
  914. 
  915. File: textutils.info,  Node: Opening the software toolbox,  Next: Index,  Prev: Operating on characters,  Up: Top
  916.  
  917. Opening the software toolbox
  918. ****************************
  919.  
  920.    This chapter originally appeared in `Linux Journal', volume 1,
  921. number 2, in the `What's GNU?' column. It was written by Arnold Robbins.
  922.  
  923. * Menu:
  924.  
  925. * Toolbox introduction::
  926. * I/O redirection::
  927. * The `who' command::
  928. * The `cut' command::
  929. * The `sort' command::
  930. * The `uniq' command::
  931. * Putting the tools together::
  932.  
  933. 
  934. File: textutils.info,  Node: Toolbox introduction,  Next: I/O redirection,  Up: Opening the software toolbox
  935.  
  936. Toolbox introduction
  937. ====================
  938.  
  939.    This month's column is only peripherally related to the GNU Project,
  940. in that it describes a number of the GNU tools on your Linux system and
  941. how they might be used.  What it's really about is the "Software Tools"
  942. philosophy of program development and usage.
  943.  
  944.    The software tools philosophy was an important and integral concept
  945. in the initial design and development of Unix (of which Linux and GNU
  946. are essentially clones).  Unfortunately, in the modern day press of
  947. Internetworking and flashy GUIs, it seems to have fallen by the
  948. wayside.  This is a shame, since it provides a powerful mental model
  949. for solving many kinds of problems.
  950.  
  951.    Many people carry a Swiss Army knife around in their pants pockets
  952. (or purse).  A Swiss Army knife is a handy tool to have: it has several
  953. knife blades, a screwdriver, tweezers, toothpick, nail file, corkscrew,
  954. and perhaps a number of other things on it.  For the everyday, small
  955. miscellaneous jobs where you need a simple, general purpose tool, it's
  956. just the thing.
  957.  
  958.    On the other hand, an experienced carpenter doesn't build a house
  959. using a Swiss Army knife.  Instead, he has a toolbox chock full of
  960. specialized tools--a saw, a hammer, a screwdriver, a plane, and so on.
  961. And he knows exactly when and where to use each tool; you won't catch
  962. him hammering nails with the handle of his screwdriver.
  963.  
  964.    The Unix developers at Bell Labs were all professional programmers
  965. and trained computer scientists.  They had found that while a
  966. one-size-fits-all program might appeal to a user because there's only
  967. one program to use, in practice such programs are
  968.  
  969.   a. difficult to write,
  970.  
  971.   b. difficult to maintain and debug, and
  972.  
  973.   c. difficult to extend to meet new situations.
  974.  
  975.    Instead, they felt that programs should be specialized tools.  In
  976. short, each program "should do one thing well."  No more and no less.
  977. Such programs are simpler to design, write, and get right--they only do
  978. one thing.
  979.  
  980.    Furthermore, they found that with the right machinery for hooking
  981. programs together, that the whole was greater than the sum of the
  982. parts.  By combining several special purpose programs, you could
  983. accomplish a specific task that none of the programs was designed for,
  984. and accomplish it much more quickly and easily than if you had to write
  985. a special purpose program.  We will see some (classic) examples of this
  986. further on in the column.  (An important additional point was that, if
  987. necessary, take a detour and build any software tools you may need
  988. first, if you don't already have something appropriate in the toolbox.)
  989.  
  990. 
  991. File: textutils.info,  Node: I/O redirection,  Next: The `who' command,  Prev: Toolbox introduction,  Up: Opening the software toolbox
  992.  
  993. I/O redirection
  994. ===============
  995.  
  996.    Hopefully, you are familiar with the basics of I/O redirection in the
  997. shell, in particular the concepts of "standard input," "standard
  998. output," and "standard error".  Briefly, "standard input" is a data
  999. source, where data comes from.  A program should not need to either
  1000. know or care if the data source is a disk file, a keyboard, a magnetic
  1001. tape, or even a punched card reader.  Similarly, "standard output" is a
  1002. data sink, where data goes to.  The program should neither know nor
  1003. care where this might be.  Programs that only read their standard
  1004. input, do something to the data, and then send it on, are called
  1005. "filters", by analogy to filters in a water pipeline.
  1006.  
  1007.    With the Unix shell, it's very easy to set up data pipelines:
  1008.  
  1009.      program_to_create_data | filter1 | .... | filterN > final.pretty.data
  1010.  
  1011.    We start out by creating the raw data; each filter applies some
  1012. successive transformation to the data, until by the time it comes out
  1013. of the pipeline, it is in the desired form.
  1014.  
  1015.    This is fine and good for standard input and standard output.  Where
  1016. does the standard error come in to play?  Well, think about `filter1' in
  1017. the pipeline above.  What happens if it encounters an error in the data
  1018. it sees?  If it writes an error message to standard output, it will just
  1019. disappear down the pipeline into `filter2''s input, and the user will
  1020. probably never see it.  So programs need a place where they can send
  1021. error messages so that the user will notice them.  This is standard
  1022. error, and it is usually connected to your console or window, even if
  1023. you have redirected standard output of your program away from your
  1024. screen.
  1025.  
  1026.    For filter programs to work together, the format of the data has to
  1027. be agreed upon.  The most straightforward and easiest format to use is
  1028. simply lines of text.  Unix data files are generally just streams of
  1029. bytes, with lines delimited by the ASCII LF (Line Feed) character,
  1030. conventionally called a "newline" in the Unix literature. (This is
  1031. `'\n'' if you're a C programmer.)  This is the format used by all the
  1032. traditional filtering programs.  (Many earlier operating systems had
  1033. elaborate facilities and special purpose programs for managing binary
  1034. data.  Unix has always shied away from such things, under the
  1035. philosophy that it's easiest to simply be able to view and edit your
  1036. data with a text editor.)
  1037.  
  1038.    OK, enough introduction. Let's take a look at some of the tools, and
  1039. then we'll see how to hook them together in interesting ways.   In the
  1040. following discussion, we will only present those command line options
  1041. that interest us.  As you should always do, double check your system
  1042. documentation for the full story.
  1043.  
  1044. 
  1045. File: textutils.info,  Node: The `who' command,  Next: The `cut' command,  Prev: I/O redirection,  Up: Opening the software toolbox
  1046.  
  1047. The `who' command
  1048. =================
  1049.  
  1050.    The first program is the `who' command.  By itself, it generates a
  1051. list of the users who are currently logged in.  Although I'm writing
  1052. this on a single-user system, we'll pretend that several people are
  1053. logged in:
  1054.  
  1055.      $ who
  1056.      arnold   console Jan 22 19:57
  1057.      miriam   ttyp0   Jan 23 14:19(:0.0)
  1058.      bill     ttyp1   Jan 21 09:32(:0.0)
  1059.      arnold   ttyp2   Jan 23 20:48(:0.0)
  1060.  
  1061.    Here, the `$' is the usual shell prompt, at which I typed `who'.
  1062. There are three people logged in, and I am logged in twice.  On
  1063. traditional Unix systems, user names are never more than eight
  1064. characters long.  This little bit of trivia will be useful later.  The
  1065. output of `who' is nice, but the data is not all that exciting.
  1066.  
  1067. 
  1068. File: textutils.info,  Node: The `cut' command,  Next: The `sort' command,  Prev: The `who' command,  Up: Opening the software toolbox
  1069.  
  1070. The `cut' command
  1071. =================
  1072.  
  1073.    The next program we'll look at is the `cut' command.  This program
  1074. cuts out columns or fields of input data.  For example, we can tell it
  1075. to print just the login name and full name from the `/etc/passwd file'.
  1076. The `/etc/passwd' file has seven fields, separated by colons:
  1077.  
  1078.      arnold:xyzzy:2076:10:Arnold D. Robbins:/home/arnold:/bin/ksh
  1079.  
  1080.    To get the first and fifth fields, we would use cut like this:
  1081.  
  1082.      $ cut -d: -f1,5 /etc/passwd
  1083.      root:Operator
  1084.      ...
  1085.      arnold:Arnold D. Robbins
  1086.      miriam:Miriam A. Robbins
  1087.      ...
  1088.  
  1089.    With the `-c' option, `cut' will cut out specific characters (i.e.,
  1090. columns) in the input lines.  This command looks like it might be
  1091. useful for data filtering.
  1092.  
  1093. 
  1094. File: textutils.info,  Node: The `sort' command,  Next: The `uniq' command,  Prev: The `cut' command,  Up: Opening the software toolbox
  1095.  
  1096. The `sort' command
  1097. ==================
  1098.  
  1099.    Next we'll look at the `sort' command.  This is one of the most
  1100. powerful commands on a Unix-style system; one that you will often find
  1101. yourself using when setting up fancy data plumbing. The `sort' command
  1102. reads and sorts each file named on the command line.  It then merges
  1103. the sorted data and writes it to standard output.  It will read
  1104. standard input if no files are given on the command line (thus making
  1105. it into a filter).  The sort is based on the machine collating sequence
  1106. (ASCII) or based on  user-supplied ordering criteria.
  1107.  
  1108. 
  1109. File: textutils.info,  Node: The `uniq' command,  Next: Putting the tools together,  Prev: The `sort' command,  Up: Opening the software toolbox
  1110.  
  1111. The `uniq' command
  1112. ==================
  1113.  
  1114.    Finally (at least for now), we'll look at the `uniq' program.  When
  1115. sorting data, you will often end up with duplicate lines, lines that
  1116. are identical.  Usually, all you need is one instance of each line.
  1117. This is where `uniq' comes in. The `uniq' program reads its standard
  1118. input, which it expects to be sorted.  It only prints out one copy of
  1119. each duplicated line.  It does have several options.  Later on, we'll
  1120. use the `-c' option, which prints each unique line, preceded by a count
  1121. of the number of times that line occurred in the input.
  1122.  
  1123.