TROWS v2.10 - a table row filter
Documentation revised 21 Oct 00 - Copyright (c) 1996-2000 by Rune Berg. TextTools Freeware.

Contents:


Usage Top || Next

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

See Understanding The Usage Section for details.


Description Top || Previous || 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 a Win95/98/NT command prompt. Running trows on a Unix(-like) shell requires quoting appropriate for the particular shell.


Options Top || Previous || Next

trows recognizes the following command line options:


Conditions Top || Previous || Next

  • Comparison Operators
  • Pattern Matching Operators
  • 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.

    Conditions that contain '|', '<', or '>' must be surrounded by double quotes "".
    This to prevent the command line interpreter 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 Operators

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

    A pattern must be a regular expression, as shown by the examples in table below:

    Here are some examples of conditions with pattern matching:

    The difference between the ~ operator (whole string match) and the ~~ operator (substring match) can be shown by the table below (where e is an expression and p is a pattern):

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


    Errors Top || 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 Syntax Top || 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 ~~ / pattern /
    
    
            expression    ::=  as for tcols
    
            pattern       ::=  see below
    


    Pattern Syntax Top || Previous || Next

    This section describes the precise syntax of patterns to be used with the ~ and ~~ operators. 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         ::=  anchored | or
                        |   anchored
    
            anchored   ::=  ^ sequence
                        |   ^ sequence $
                        |   sequence $
                        |   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 and n
                        |   \t   ; a tab
                        |   \n   ; a newline
                        |   \xHH ; HH being two hex. digits (\00 not allowed)
                        |   any char. except: ( ) | * + ? [ ] ^ $ .
    
            membchar   ::=  \ any char. other than t and n
                        |   \t   ; a tab
                        |   \n   ; a newline
                        |   \xHH ; HH being two hex. digits (\00 not allowed)
                        |   any char. except: - ] ^
    


    Limitations Top || Previous || Next

    As for tcols.


    Return Codes Top || Previous || Next

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


    Version History Top || Previous

    These are the released versions of trows:

    End of document