home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / utlos2.zip / Doc / TXTCUT.DOC < prev    next >
Text File  |  1997-10-24  |  7KB  |  182 lines
  1. $Id: TXTCUT.DOC 1.3 1997/10/25 02:03:41 brian Exp $
  2.  
  3.                      txtcut : The 'txtcut' command
  4.                            By:  Brian Yoder.
  5.  
  6.         (c) Copyright International Business Machines Corporation 1997
  7.         All rights reserved.
  8.  
  9. ========================================================================
  10. Introduction
  11. ========================================================================
  12.  
  13. Files that contain blank lines, comments preceded by # (pound signs), a
  14. verying amount of whitespace between tokens, and other features to make
  15. them well-documented and readable (such as INI-style ASCII text files)
  16. are not easily processed by a Korn shell or REXX script. Additional
  17. logic can be used to skip over blank lines and remove comments, but this
  18. logic adds undesirable complexity and slow performance to the script.
  19.  
  20. One solution is txtcut. This program prepares a text file, stripping out
  21. comments and blank lines and handling simple strings. It was originally
  22. developed as a fast preprocessor for the AIX cut command. However, the
  23. output of txtcut can be piped into rxqueue, giving OS/2's REXX the
  24. ability to easily and quickly handle text-style INI-like files. Even awk
  25. and Perl (of which very good native OS/2 ports exist) can benefit from
  26. txtcut.
  27.  
  28. Information can be stored in an INI-style text file in an easily-
  29. maintained and readable fashion using comments, strings, and blank
  30. space. The txtcut program preprocesses this text file, removing comments
  31. and blank lines, processing simple strings, and delimiting the tokens in
  32. a consistent manner. The tokens produced by txtcut can be easily
  33. extracted using the AIX cut command, a REXX script, or even an awk or
  34. Perl script.
  35.  
  36. The REXX, awk, Perl, and the *ix shells cover a lot of ground, but I
  37. have wished for a long time for the capabilities of txtcut to make the
  38. basic AIX and OS/2 toolsets more complete. Text INI-style files that are
  39. highly readable by people *and* easily processed by command scripts:
  40. txtcut gives you the best of both worlds!
  41.  
  42. ========================================================================
  43. Command Usage
  44. ========================================================================
  45.  
  46.         txtcut [ -dchar ] [ -n ] [ -l ] [ -c ] [ textfile ]
  47.  
  48. This program prepares a text file for the AIX cut command. If the name
  49. of the text file is missing, then txtcut reads from standard input.
  50.  
  51. For each line that contains one or more tokens, txtcut writes one line
  52. to stdout that contains the tokens. A delimiter character is placed
  53. between each pair of tokens.
  54.  
  55. The default delimiter character is a tab. You may use the -d option to
  56. change it to another character.
  57.  
  58. Flags:
  59.  
  60. -dchar  Specify a character to be used as the token delimiter. This
  61.         character is specified just as it is for the cut command.
  62.         The default is a tab character.
  63.  
  64. -n      List the filename as the first token in each line. If the text
  65.         file is being read from standard input, then the filename is
  66.         listed as "(stdin)". See example 4 for more information.
  67.  
  68. -l      List the line number within the file as a token.
  69.  
  70. -c      List the number of tokens on the line as a token. This count
  71.         does not include the additional tokens that may be added by the
  72.        -n, -l or -c flags.
  73.  
  74. -?      List brief help.
  75.  
  76. ========================================================================
  77. Format of a text file
  78. ========================================================================
  79.  
  80. Blank lines are ignored. Lines that begin with a # or ; are assumed to
  81. be comments and are ignored.
  82.  
  83. Each nonblank, noncomment line consists of one or more tokens. A token
  84. can be:
  85.  
  86.         An = sign.
  87.  
  88.         A string of characters enclosed by either double quotes, single
  89.         quotes, or square brackets.
  90.  
  91.         A series of contiguous nonblank characters.
  92.  
  93. If a non-string token that begins with a # or a ; is encountered on a
  94. line, it and the remaining tokens are assumed to be comments and are
  95. ignored.
  96.  
  97. ========================================================================
  98. Example 1
  99. ========================================================================
  100.  
  101. Assume that the sample.txt file contains the following:
  102.  
  103.         # This is a comment line
  104.  
  105.         f1 = a b c    # First line of tokens
  106.         x y z         # Second line of tokens
  107.         aaa bbbb  "cccc   ddddd"  # Last line of tokens
  108.  
  109. Run the command:
  110.  
  111.         txtcut -d: sample.txt
  112.  
  113. The txtcut command writes the following to stdout:
  114.  
  115.         f1:=:a:b:c
  116.         x:y:z
  117.         aaa:bbbb:cccc   ddddd
  118.  
  119. ========================================================================
  120. Example 2
  121. ========================================================================
  122.  
  123. Using the same sample.txt file in example 1, we'll cut the 3rd field
  124. from each line of the file. Run the command:
  125.  
  126.         txtcut sample.txt | cut -f3
  127.  
  128. The following is written to stdout:
  129.  
  130.         a
  131.         z
  132.         cccc   ddddd
  133.  
  134. ========================================================================
  135. Example 3
  136. ========================================================================
  137.  
  138. Again, using the same sample.txt file in example 1, we'll cut the 3rd
  139. field from each line of the file. But this time we'll pipe the file into
  140. txtcut's standard input. And we'll use a colon for the delimiter:
  141.  
  142.         cat sample.txt | txtcut -d: | cut -f3 -d:
  143.  
  144. Again, the following is written to stdout:
  145.  
  146.         a
  147.         z
  148.         cccc   ddddd
  149.  
  150. ========================================================================
  151. Example 4: Use of -n and -l flags
  152. ========================================================================
  153.  
  154. Using the same sample.txt file in example 1, we will add the filename,
  155. the line number within the file where each line of tokens was found, and
  156. the number of tokens in the line. The following commands and the output
  157. of each illustrate this:
  158.  
  159.     ----------------------------    ----------------------------------
  160.     Command                         Output
  161.     ----------------------------    ----------------------------------
  162.     txtcut -d: sample.txt           f1:=:a:b:c
  163.                                     x:y:z
  164.                                     aaa:bbbb:cccc   ddddd
  165.  
  166.     txtcut -d: -n sample.txt        sample.txt:f1:=:a:b:c
  167.                                     sample.txt:x:y:z
  168.                                     sample.txt:aaa:bbbb:cccc   ddddd
  169.  
  170.     txtcut -d: -l sample.txt        3:f1:=:a:b:c
  171.                                     4:x:y:z
  172.                                     5:aaa:bbbb:cccc   ddddd
  173.  
  174.  
  175.     txtcut -d: -n -l sample.txt     sample.txt:3:f1:=:a:b:c
  176.                                     sample.txt:4:x:y:z
  177.                                     sample.txt:5:aaa:bbbb:cccc   ddddd
  178.  
  179.     txtcut -d: -n -l -c sample.txt  sample.txt:3:5:f1:=:a:b:c
  180.                                     sample.txt:4:3:x:y:z
  181.                                     sample.txt:5:3:aaa:bbbb:cccc   ddddd
  182.