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
Introduction | Top | 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.
Usage | Top | 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.
Options | Top | Previous | Next |
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. |
-fppN | Use floating-point precision N (0..15, default 6) decimal digits for
internal representation and for comparisons. See separate discussion on floating point numbers for more details. |
-hc | Print summary of condition usage to standard output, then exit. |
-he | Print summary of expression usage to standard output, then exit. |
-hfc | Print summary of character functions to standard output, then exit. |
-hfs | Print summary of string functions to standard output, then exit. |
-hfv | Print summary of conversion functions to standard output, then exit. |
-hfm | Print summary of maths functions to standard output, then exit. |
-hfx | Print summary of miscellanous 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 | Top | 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:
Condition | 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.
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:
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 of a condition using pattern matching (where e denotes an expression, and p a pattern) is:
Condition | True if |
---|---|
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' |
\x77 | the character with ASCII code hex 77 ('w') |
\+ | 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 |
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}"
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 ::= as for tcols pattern ::= see below
Pattern Syntax | Top | 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: - ] ^
Limitations | Top | Previous | Next |
As for tcols.
Return Codes | Top | Previous | Next |
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 |
Version History | Top | Previous |
These are the released versions:
Version | Date | Changes |
---|---|---|
1.10 | 25-Feb-96 | n/a |
1.20 | 13-May-96 | * Pattern matching operator. * New function .nl : append newline char. * New function .prf : print formatted. * New function .tr : trim leading and trailing blanks. |
1.30 | 24-Sep-96 | * New expression $n : yields current data line number. * New expression $e(/NAME/) : yields value of environment variable. * New function .dup(n) : yields n duplicates of what it's applied to. * Improved function .prf : now does field width, left-just., integers, etc. * Improved functions .trl .trt .tr : they now trim any whitespace, not just blanks. |
1.31 | 8-Apr-97 | * Available as Win32 console mode version. * Bug-fix: Condition "" caused assert-error. |
1.50 | 21-Jun-97 | * Proper return codes. * New option -sN : stop after N hits. * Bug-fix: -r option didn't work properly on Win32 when taking interactive input. |
2.00 | 2-Jan-99 | * Supports floating point numbers. * New functions .cc & family: various forms of character replacement. * New functions .dc & family: various forms of character deletion. * Win32 version has increased max. input line length / fields per line. * Win32 version has coloured response texts. * New options -hfc -hfs -hfv -hfm -hfx : these replace the -hf option. |
End of document |