TROWS v2.00 - a table row filter
Revised 2-Jan-99. Copyright (c) 1996-99 by Rune Berg. TextTools Freeware.

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


IntroductionTop | Next

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.


UsageTop | Previous | Next

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

Where:

[] 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.


OptionsTop | Previous | Next

trows recognizes the following command line options:


ConditionsTop | Previous | Next

Comparison Operators | Pattern Matching | Boolean Operators

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.

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.

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.

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.

Comparison Operators

Let e and f denote expressions in the below table:

Comparison is numerical if e and f both evaluate to integers.
Comparison is numerical to 6 decimal digits (but see -fpp option) if one of e and f evaluates to a floating point number and the other evaluates to either a floating point number or an integer.
Otherwise, comparison is ASCII-wise.

Here are some examples:

Pattern Matching

The general form of a condition using pattern matching (where e denotes an expression, and p a pattern) is:

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

Here are some examples of conditions with pattern matching:

For precise details, see the Pattern Syntax section.

Boolean Operators

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

! 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}"


ErrorsTop | Previous | Next

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 SyntaxTop | Previous | Next

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 SyntaxTop | Previous | Next

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: - ] ^


LimitationsTop | Previous | Next

As for tcols.


Return CodesTop | Previous | Next

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


Version HistoryTop | Previous

These are the released versions:

End of document