home *** CD-ROM | disk | FTP | other *** search
/ Audio 4.94 - Over 11,000 Files / audio-11000.iso / msdos / sndbords / proaudio / fddmairq / grep.doc < prev    next >
Text File  |  1991-08-23  |  8KB  |  252 lines
  1. GREP - Group Reduced Extremely Particularly
  2.  
  3. grep - a pattern matching utility
  4.  
  5. Syntax
  6.  
  7.     grep [-options] [-.xx[N]] [-e] pattern [filename ...]
  8.     grep [-options] [-.xx[N]] -l listfile [filename ...]
  9.     grep [-options] [-.xx[N]] -l listfile -ofile -Ofile [filename ...]
  10.  
  11. Options
  12.  
  13.     -f    shark expressions disabled
  14.     -c     case is significant 
  15.     -v     lines without pattern match
  16.     -S    input is sorted, quit after all matches
  17.     -W    write individual files of matches: pattern.grp
  18.     -p    display matched pattern only
  19.     -s    show progress of compare algorithm
  20.     -n    display line numbers of matching lines,
  21.             reset numbers to zero across files
  22.     -N    display line numbers of matching lines, no reset
  23.     -Q    suppress normal output
  24.     -F    suppress display of filenames on multiple files
  25.     -L    display filenames only 
  26.     -oname    name= file for normal output
  27.     -Oname    name= file for normal non-output
  28.     -dstr    str= expression for end of line delimiter
  29.     -e    next argument is pattern beginning with a dash
  30.  
  31.     -l listfile    patterns to match are contained in the
  32.             file specified by listfile
  33.     -m    output multiple lines on multiple matches when
  34.             using patterns from listfile
  35.     -.xx    xx = return value based on match count
  36.         nz (zr) = return TRUE (1) if not zero (zero) matches
  37.         nz    return TRUE (1) if not zero matches
  38.         gt N    if matches > N, return matches - N
  39.         lt N    if matches < N, return N - matches
  40.         ge N    if matches >=N, return matches - N, else -1
  41.         le N    if matches <=N, return N - matches, else -1
  42.  
  43.         Note: matches - N and N - matches, when greater than
  44.             254, lose their significance due to the DOS
  45.             maximum errorlevel of 255.
  46.         Note: the -m option affects the count for comparison
  47.  
  48.     -Z    reset all options to defaults (override environment
  49.         settings for use in batch files)
  50.  
  51.  
  52. Operation
  53.  
  54.     grep operates as a standard filter, reading the standard
  55.         input, unless filename arguments are present, and 
  56.         writing to standard output.
  57.  
  58.     Normal operation consists of a grep attempting to match
  59.         (using the "match" protocol described in match.doc)
  60.         a "pattern" on each of the newline-terminated lines
  61.         on its input, displaying each line as it matches.
  62.  
  63.     Options allow grep to display lines that do not contain the
  64.         specified pattern, display the line numbers of 
  65.         output lines, and even to accept a filename that
  66.         contains a list of patterns to match.  Also, the
  67.         ability to disable the "shark expressions" feature
  68.         and operate strictly as a string "finder".
  69.  
  70.     grep can separate a file into two files, lines that match
  71.         and lines that do not match, using the -o and -O
  72.         options.  This option was used to process a customer
  73.         transaction list:
  74.  
  75.     grep can output matching lines to individual files based on
  76.         the actual string matched using the -W option.
  77.         grep will generate a filename of "pattern.@@@" where
  78.         pattern is the actual matched string from the input
  79.         line.  Lines with no matches are written to 
  80.         "$nomatch.@@@",    and patterns that are bad file names 
  81.         are written to "$badname.@@@". 
  82.  
  83.             Particularly useful when processing large
  84.             amounts of data looking for key items.  
  85.             This option will create a file named by 
  86.             the item searched for, up to eight chars
  87.             in DOS, so that a list of keywords and 
  88.             patterns can be processed on information
  89.             such as listings of stock quotations, 
  90.             download listings, note files, and any
  91.             other groupings of information.
  92.  
  93.     With the -S option, grep will terminate on the first non-match
  94.         after successfully matching any lines.  When the input
  95.         is sorted, grep will not bother to look at lines after
  96.         the first non-match, allowing a little faster behavior
  97.         in certain situations.
  98.  
  99.     The -dstr option will cause grep to convert the str argument
  100.         and use the result as the output line delimiter.  str
  101.         can be a shark expression, or, if missing, no end of 
  102.         line delimiter is output.
  103.  
  104.     Default operation is as follows:
  105.  
  106.         shark expressions are enabled
  107.         case is not significant
  108.         output consists of lines containing specified patterns
  109.         line numbers are not displayed
  110.         line numbers, when displayed, are reset across files
  111.         filenames preface each line for multiple input files
  112.         only one output line per match on listfile patterns
  113.         newline as the end of line delimiter
  114.  
  115.     Note: if the pattern begins with a dash ("-") then the -e
  116.         option must be specified directly prior to the pattern
  117.         in order to prevent grep from interpreting the pattern
  118.         as an option string.
  119.  
  120.     Note: the -s option may result in extremely voluminous output,
  121.         although it may be interesting to observe.
  122.  
  123. Return Value
  124.  
  125.     grep normally returns zero, unless:
  126.  
  127.         an invalid option is specified
  128.         no pattern was specified
  129.         a listfile is specified but unopenable
  130.         outputfiles were requested but not specified 
  131.             or unopenable or unwritable
  132.  
  133.     grep returns -1 if a return value was requested and
  134.     one of the above errors were encountered
  135.         
  136.  
  137.     grep return values for the logic operations are as follows:
  138.  
  139.         nz    if some matches, return TRUE (1)
  140.         zr    if zero matches, return TRUE (1)
  141.         gt N    if > N matches, return matches - N
  142.         lt N    if < N matches, return N - matches
  143.         ge N    if >=N matches, return matches - N,
  144.                 else return ERROR (-1)
  145.         le N    if <=N matches, return N - matches,
  146.                 else return ERROR (-1)
  147.  
  148.         if the -v option is specified:
  149.  
  150.         nz     if some non-matches, return TRUE (1)
  151.         zr    if zero non-matches, return TRUE (1)
  152.         gt N    if > N non-matches, return matches - N
  153.         lt N    if < N non-matches, return N - matches
  154.         ge N    if >=N non-matches, return matches - N,
  155.                 else return ERROR (-1)
  156.         le N    if <=N non-matches, return N - matches,
  157.                 else return ERROR (-1)
  158.  
  159. Limitations
  160.  
  161.     Does not allow for multiple expressions except from    
  162.     a -l specified list file.
  163.  
  164.     Processing of backslash-character combinations and 
  165.     directory pathnames confuses the parser.
  166.  
  167.  
  168.     The Maximum Line Length of 512 can not be changed in this
  169.     version.
  170.             
  171.  
  172. Comments
  173.  
  174.     Please make any comments you have before you transfer this
  175.     to another.
  176.  
  177.     The -c option, with the opposite meaning here as it does
  178.     on Unix, was implemented because a lot of assembly language
  179.     was being processed and the case was not significant.  It
  180.     is a toggle value and the code can be patched.
  181.  
  182.     The 512 character per line maximum... should it be variable?
  183.  
  184.     Matches across lines: now that would be a handy feature.
  185.  
  186. Thanks
  187.  
  188.     I am glad that a feature I was reluctant to incorporate, 
  189.     but was insisted upon by Mr. Reich, the return to DOS 
  190.     of errorvalues based on the number of matches, was included,
  191.     as I use this in situations others might disbelieve:
  192.  
  193.         :chknet
  194.         grep -Q.nz "^device=*ramdrive.sys"
  195.         if errorlevel 1 goto haveram
  196.         set bat=c:\bat
  197.         goto quit
  198.  
  199.         :haveram
  200.         echo d | xcopy c:\bat d:\bat
  201.         set bat=d:\bat
  202.  
  203.         :quit
  204.         set path=%bat%;%bin%
  205.         
  206.  
  207.     Thanks also to Mr. Nicholson as he gave me cause to 
  208.     access the environment.  
  209.  
  210.     And to Mr. Bernstein for having the need for writing
  211.     output files based on the pattern and for splitting the 
  212.     output of matches and nonmatches to separate files:
  213.  
  214.         grep -W -lsubject.lst list.txt
  215.         more *.@@@
  216.  
  217.         grep -oisin.lst -Onotin.lst list.txt
  218.         more *.lst
  219.         
  220.  
  221. Versions
  222.  
  223.     See the executable for the version and syntax specifics.
  224.     Entering   grep --   will cause the program to put the
  225.     syntax statement on standard output.
  226.  
  227. =======================================================================
  228.  
  229. grep - copyright SHARK 1991 - Programmer Bart Crane
  230. All Rights Reserved - Distribution Encouraged 
  231. Software Provided As Is, No Warranty Express Or Implied 
  232.  
  233. For More Information on SHARK, Upgrades, and other Utilities:
  234.  
  235.     Mail: 
  236.  
  237.     SHARK
  238.     922 San Leandro Ave. Suite C
  239.     Mountain View, CA  94043
  240.     Telephone:     (415) 969-3015
  241.     Fax:         (415) 969-6600
  242.  
  243.     Internet:
  244.  
  245.     shark@parallax.com
  246.  
  247.     Mediavision BBS:
  248.  
  249.     (415) 770-0968    - Messages To: Bart Crane
  250.  
  251.  
  252.