# TROWS v1.50 - a table row filter

#### Revised 22-Jul-97. Copyright (c) 1996-97 by Rune Berg. TextTools Freeware.

Introduction
Usage
Options
Conditions
Errors During Processing
Condition Syntax
Pattern Syntax
Limitations
Return Codes

### INTRODUCTION

trows is a filter for selecting lines of data that meet given conditions.

trows runs from the command line or from batch files.

Input and output data are plain ASCII text lines, each line consisting of (by default) whitespace-separated fields; see tcols for a more detailed discussion of fields and separators. Files are typically used for input and output data.

For example, consider a text file "data", containing the following table:

            john  45   tennis
            al   31    squash
            tom   25   beer
            paul  38  women

The command:

            trows from data "$2<35"

writes, to the screen, all lines whose second field is numerically less than 35:

            al   31    squash
            tom   25   beer

Here's another example. The command:

            trows from data to results "$1=/john/|$3=/women/"

copies, from "data" to a new file "results", all rows whose first field equals 'john' or whose third field equals 'women':

            john  45   tennis
            paul  38  women

The above examples should give you an idea of what trows can do. But there's more, so read the next sections. Since trows has much in common with its sibling program tcols, you should also read tcols's documentation.

Note: All usage examples in this document are for trows running on MS-DOS. Running trows on a Unix shell requires quoting appropriate for the particular shell.

### USAGE

trows [log logfile] [options] [from infile] [to outfile] condition [...]

Where:

log logfile
  Append error messages, summary, etc. to logfile instead of writing them to standard error (the screen).
  If logfile does not exist, trows will create it.
options
  Flags to control various aspects of trows's behaviour. See Options section.
from infile
  Make trows read from infile. If not given, trows reads from standard input.
to outfile
  Make trows write to outfile. If not given, trows writes to standard output.
condition
  A condition that must hold for a line to be printed, e.g. $2=176.
...
  Further conditions.

[] denotes an optional item.

Upper/lower case for the 'log', 'from', and 'to' keywords is not significant. Also, these keywords should not be used as file names.

### OPTIONS

trows recognizes the following command line options:

Option | Function
--- | ---
-iC | Separate input fields by character C (except \). Use \t to form a tab.
-sN | Stop processing after having evaluated (and copied) N lines that meet the given condition(s). N must be in range 1..2147483647.
-w | Don't abort on a processing error, just skip bad line, write a warning to standard error (or logfile, if used), and continue processing the next line.
-r | Print a one-line report to standard error (or logfile, if used), when processing is completed. This option will have no effect if processing is aborted due to an error.
-hc | Print summary of condition usage to standard output, then exit.
-he | Print summary of expression usage to standard output, then exit.
-hf | Print summary of all functions to standard output, then exit.
-hf name | Print summary of named function to standard output, then exit.
-hp | Print summary of pattern syntax to standard output, then exit.
-v | Print banner with version number to standard error (or logfile, if used), then exit.

### CONDITIONS

A condition is a statement which, applied to an input line, evaluates to either True or False.
trows copies only those lines that meet the given conditions. Lines that contain only whitespace are never copied.

On MS-DOS, conditions that contain '|', '<', or '>' must be surrounded by double quotes "".
This to prevent the MS-DOS shell from treating '<' and '>' as redirection of standard input and output, and '|' as a pipe.

In its simplest form, a condition consists of an expression, a comparison operator, and a second expression.
For example, in:

            "$3>=/Zappa/"

$3 is the first expression, >= is the comparison operator, and /Zappa/ is the second expression.

Expressions work the same way as in tcols.

The second expression in a comparison must evaluate to exactly one string.

Now for the comparison operators. Let e and f denote expressions in the below table:

            COMPARISON:  TRUE IF:
            -----------------------------------------------------------

            e=f          e is equal to f.

            e<>f         e is not equal to f.

            e<f          e is less than f.

            e>f          e is greater than f.

            e<=f         e is less than or equal to f.

            e>=f         e is greater than or equal to f.

Comparison is numerical if e and f both evaluate to integers; otherwise, comparison is ASCII-wise.

Here are some examples:

            CONDITION:           TRUE IF:
            -----------------------------------------------------------

            $1=$4                1st field is equal to 4th field .

            "$2>25"              2nd field is greater than 25.

            "$l<>$3.upp"         last field is not equal to 3rd field in upper case.

            "$1..3>76"           1st, 2nd, and 3rd field are all greater than 76.

            "$1..3.sum<1050"     sum of 1st, 2nd, and 3rd field is less than 1050.

            $2..3=/hey/          both 2nd and 3rd field are both equal to hey.

Pattern matching. The general form (where e denotes an expression, and p a pattern) is:

            e~/p/        whole of e matches pattern p.

Patterns must be in the form of regular expressions, as illustrated by the below table:

            PATTERN:      MATCHES:
            -----------------------------------------------------------

            a             the character 'a'.

            \x78          the character with ASCII code hex 78 ('x').

            \+            the character '+' (escaped meta-character).

            .             any character.

            [a-zXYZ]      one of the characters a, b, ..., z, X, Y, or Z.
                          (character group).

            [^a-zXYZ]     any character but a, b, ..., z, X, Y, or Z.
                          (inverted character group).

            abc           a sequence of characters.

            a*            zero or more 'a's.

            a+            one or more 'a's.

            a?            zero or one 'a's.

            a|b           an 'a' or a 'b'.

            (ab)+         one or more occurences of the sequence 'ab'.

Here are some examples of conditions with pattern matching:

            CONDITION:            TRUE IF:
            -----------------------------------------------------------

            "$1~/-?[0-9]+/"       1st field is a literal integer,
                                  possibly with a leading '-'.

            "$2~/a+b.*/"          2nd field begins with one or more 'a's and a 'b'.

            "$1..l~/.*[A-Z].*/"   all fields contain an upper case letter.

            "$1~/.*(12|42|93)m/"  1st field ends with '12m', '42m', or '93m'.

For precise details, see the Pattern Syntax section.

Boolean operators can be used to form composite conditions. Let c and d denote conditions in the table below:

            CONDITION:   TRUE IF:
            -----------------------------------------------------------

            !c           c is not True.

            c&d          c and d are True.
                         (Note that d is not evaluated if c evaluates to False)

            c^d          c or d, but not both, is True. Exclusive or.

            c|d          c or d, or both, is True.
                         (Note that d is not evaluated if c evaluates to True)

! has the highest precedence, | the lowest.

Curly brackets { } can be used to override precedence.

Here are some examples of conditions with boolean operators:

            "$3=55&!{$1=/ok/&$2<8}"

            $1=/jeep/&$3=45

            "$2>10|$2<25"

            "{$2=/ok/|$2=/allright/}&$4>=78"

If more than one condition is given, all conditions must evaluate to True for a line to be copied.
Thus, the following two conditions:

            $1=/zap/ "$2>35"

are equivalent to the one condition:

            "$1=/zap/&$2>35"

Likewise, the following two conditions:

            "$1=67|$2=100"  "$3=44^$4=0"

are equivalent to:

            "{$1=67|$2=100}&{$3=44^$4=0}"

Syntax errors in conditions will cause trows to exit with an appropriate error message, before any processing.

The Condition Syntax section describes the exact condition syntax rules.

### ERRORS DURING PROCESSING

A processing error occurs if the contents of an input line prevents trows from evaluating your condition(s).

trows's default error action is to write a relevant error message and exit. However, if you set the -w command line option, trows will skip the bad input line and continue processing the next input line. trows writes a warning anyway.

trows writes error messages and warnings to standard error (or logfile, if used).

### CONDITION SYNTAX

This section describes the precise syntax of trows conditions. Note: The spaces used in these rules are for clarity; spaces are not allowed in actual conditions (except to denote a space in a literal string).

            condition     ::=  xorcond
                            |  xorcond | condition

            xorcond       ::=  andcond
                            |  andcond ^ xorcond

            andcond       ::=  notcond
                            |  notcond & andcond

            notcond       ::=  ! factor
                            |  factor

            factor        ::=  { condition }   ; that's curly brackets
                            |  expression = expression
                            |  expression <> expression
                            |  expression < expression
                            |  expression > expression
                            |  expression <= expression
                            |  expression >= expression
                            |  expression ~ / pattern /

            expression    ::=  as for tcols

            pattern       ::=  see below

### PATTERN SYNTAX

This section describes the precise syntax of patterns to be used with the ~ operator. Note: The spaces used in these rules are for clarity; spaces are not allowed in actual patterns (except to denote a literal space).

            pattern    ::=  or

            or         ::=  sequence | or
                        |   sequence

            sequence   ::=  closure sequence
                        |   closure

            closure    ::=  consumable *
                        |   consumable +
                        |   consumable ?
                        |   consumable

            consumable ::=  .
                        |   char
                        |   group
                        |   ( or )

            group      ::=  [ members ]
                        |   [ ^ members ]

            members    ::=  member members
                        |   member

            member     ::=  membchar - membchar
                        |   membchar

            char       ::=  \ any char. other than t
                        |   \t   ; a tab
                        |   \n   ; a newline
                        |   \xHH ; HH being two hex. digits
                        |   any char. except: ( ) | * + ? [ ] .

            membchar   ::=  \ any char. other than t and n
                        |   \t   ; a tab
                        |   \n   ; a newline
                        |   \xHH ; HH being two hex. digits
                        |   any char. except: - ] ^

### LIMITATIONS

As for tcols.

### RETURN CODES

trows returns with one of the following codes ("error levels"):

Code | Meaning
--- | ---
0 | Success
1 | Skipped bad input data (trows was invoked with -w option)
101 | Out of memory
102 | Incorrect command line arguments
104 | Error opening file
105 | I/O error
106 | Capacity overrun
107 | File name clash
109 | Bad input data

##### End of document