FILTER  : Multi-purpose text filter.

Title   : FILTER
Version : 4.0
Date    : Mar 24,2000
Author  : J.R. Ferguson, Amsterdam, The Netherlands
Download: http://hello.to/ferguson (DOS Filters)
E-mail  : j.r.ferguson@iname.com


Usage : FILTER [[<]in] [>out] [/option[...]] [...]] [txtopt [...]]

option: C[n,s,d]   Copy n characters from position s to d.
        D[n,p]     Delete n characters at position p.
        E[+/-][n]  Expand tabs ([+]) or replace spacegroups by tabs (-),
                   where n [8] is tab field length.
        F[n,m]     Fill nonblank lines with dots to width n [70],
                   skipping first m [0] lines. Implies /T.
        H          Send this help text to (redirected) output.
        ?          Send this help text to screen (page by page)
        I[n,p]     Insert n spaces at position p.
        J[+/-]     Add/remove Carriage Return before Line Feed [+].
        L[+/-]     Add/remove Line Feed after Carriage Return [+].
        M[n,s,d]   Move n characters from position s to d.
        N[n]       Number lines, use n [4] digits,
        O[n,s,d]   Overwrite n chars from position s to d.
        P          Reset parity bit. Implied by /W.
        R[n]       Remove n trailing lines after processing /S and /X.
        S[n,m]     Skip m lines starting at line n.
        T          Trim trailing blanks. Implied by /F.
        U[+/-]     Convert to upper/lower case [+].
        V[n,s]     Reverse n [all] characters starting at position s.
        W          Wordstar document ==> ASCII textfile. Implies /P.
        X[n,m]     Extract m lines starting at line n.
        Z[+]       Remove NULLs. Z+: also ANSI screen control sequences.

txtopt: /A[+/-][I][p][*] text   Include lines after  specified text only.
        /B[+/-][I][p][*] text   Include lines before specified text only.
        /G[+/-][I][p][*] text   Include lines with the specified text only.

        + : Include matching line (default for /G).
        - : Do not include the matching line (default for /A and /B).
        I : Ignore upper/lower case.
        p : Search for text starting at column p. Default p=1.
        * : Text may be found at any column at or after p.

        These suboptions may appear in any order.

        The text to search for is a separate command argument, immediately
        following the /A, /B or /G argument. If it contains any spaces or
        tabs, it must be surrounded by single or double quotes.

The three filter action groups below are processed in the specified order:
  1. option  E,J,L,P,R,S,T,U,W,X and Z
  2. txtopt  A,B,G
  3. option  C,D,F,I,M,N,O,V

Uppercase letters must be typed as is. Lowercase letters are variables.

Parts surrounded by brackets [ and ] are optional. For numeric optional
parameters the default value is 1, unless specified otherwise.

If a group of numeric parameters is optional, like in /C[n,s,d], in fact
each of the individual numbers may be skipped. So 
  /C3,5  is the same as /C3,5,1
  /C2,,4 is the same as /C2,1,4 
  /C,,4  is the same as /C1,1,4 

Examples:

  FILTER <TEST.INP >TEST.OUT /D4
  Copy file TEST.INP to file TEST.OUT, deleting the first 4 characters of
  each line.

  FILTER TEST.INP /U-
  Display the contents of file TEST.INP on the screen, converting all
  uppercase letters to lowercase.

  FILTER /U >TEST.OUT
  Copy all lines typed at the keyboard to file TEST.OUT, converting all
  letters to uppercase. Stop when a Ctrl-Z (end-of-file) character is
  typed.

  FILTER /I5
  Echo the lines typed at the keyboard to the screen, inserting 5 spaces
  at the start of each output line. You may want to use this echo feature
  to test the result of the various options. Stop with Ctrl-Z.

  DIR |FILTER /S,3 /R2 |SORT
  Skip the first 3 lines and the latst 2 lines from the directory listing,
  then sort the remaining lines and display the result on the screen.
  (DIR and SORT are DOS commands).

  DIR |FILTER /S,3R2 |SORT
  Same as above.

  DIR <TEST.INP /A Start
  Display the lines in file TEST.INP that follow the first line starting
  with the word "Start". Text coparision is case sensitive, so "start" or
  "START" will not match.

  DIR <TEST.INP /AI Start
  Display the lines in file TEST.INP that follow the first line starting
  with the word "Start". Text coparision is not case sensitive, so "start"
  or "START" will match as well.

  DIR <TEST.INP /A+I Start
  Same as above, but include the line with the word "Start".

  DIR <TEST.INP /A+I* Start
  Same as before, but the word "Start" may be at any position in the line.

  DIR <TEST.INP /A+I5* "start here"
  Same as before, only now the trigger text has two words (you must use
  quotes in this case) and must be in column 5 or more.

  FILTER <TEST.INP /G trigger
  Display all lines from file TEST.INP that start with the text "trigger".

  FILTER <TEST.INP /GI "w 2"
  Display all lines from file TEST.INP that start with the text "w 2",
  ignoring case.

  FILTER <TEST.INP /GI* "w 2"
  Display all lines from file TEST.INP that contain the text "w 2" or "W 2"
  in any column.

  FILTER <TEST.INP /G-I* "w 2"
  Display all lines from file TEST.INP that do not contain the text "w 2"
  or "W 2".

  FILTER <TEST.INP /G10 "w 2"
  Display all lines from file TEST.INP that contain the text "w 2" starting 
  in column 10.

  FILTER <TEST.INP /G-10* "w 2"
  Display all lines from file TEST.INP that do not contain the text "w 2"
  at or after column 10.



History:
 v4.0 Mar 24,2000  Fix: Fixed bug in /G pattern recognition algorithm.
                   Add: /G- (exclude) suboption.
 v3.8 Feb 11,2000  New: Ooption /V (reverse).
                   Chg: Now all numeric parameters are optional.
                   Chg: Provided more explanation in this textfile.
 v3.7 Jan 22,1999  New: Option /G (get). Fix: /A and /B argument parsing.
 v3.6 Jun 26,1998  Fix: /C, /M and /O no longer remove trailing spaces.
 v3.5 Nov 30,1996  Included sources.
 v3.4 Feb 04,1995  New: text options /A (after) and /B (before).
                   Multi-page help support.
 v3.3 Jan 22,1995  New: option /Z+ (remove ANSI control sequences).
 v3.2 Dec 05,1994  New: option /J  (add/remove CR before LF).
 v3.1 Jun 18,1994  First released in public domain.
