1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
.help texpand Dec90 tables
.ih
NAME
texpand -- Expand table rows according to a set of rules.
.ih
USAGE
texpand input output rbase
.ih
DESCRIPTION
This task uses a set of rules to convert each row in the input table
into one or more rows in the output table. Except for these
conversions, the output table is identical to the input table. The set
of rules is contained in a text file specified by the 'rbase' parameter.
Each rule has two parts, the target and
the action.
Rules are applied in the following ways. The task reads a row
from the input table. It then looks at the target part of each rule in
the rules file in the order that they were placed in the file. If the
input row does not match the target part of any rule, it is written to
the output table without being changed.
Otherwise, the first rule whose target matches the
input row is used to convert the input row. The columns and values
contained in the action part of the rule are used to modify the
input row to produce a new output row. After the new row is produced, the set
of rules is searched again to see if any of the rules can be applied
to the new row. This process continues until no further matches can be
found, at which point the new rows are written to the output table.
For example, suppose the following rules are contained in the rules
file:
.nf
SEX = M && NAME = ANY => NAME = Tom || NAME = Dick || NAME = Harry;
SEX = F && NAME = ANY => NAME = Mary || NAME = Jane;
SEX = X => SEX = M || SEX = F;
.fi
And suppose the input table contains the following information:
.nf
NAME SEX TITLE
ANY X Astronomer
.fi
The first two rules impose two conditions, the first on the value of
the 'SEX' column and the second on the value of the 'NAME' column. While
the value of the 'NAME' column matches the conditions in the first two
rules, the value of 'SEX' does not. The third rule only imposes one
condition, which does match the row in the input table. Thus the third
rule of the rule file is applied to the input table and the following
intermediate result is produced:
.nf
NAME SEX TITLE
ANY M Astronomer
ANY F Astronomer
.fi
The rules file is searched again, and now the first rule matches the
first row and the second rule matches the second row. So the following
result is produced when these two rules are applied:
.nf
NAME SEX TITLE
Tom M Astronomer
Dick M Astronomer
Harry M Astronomer
Mary F Astronomer
Jane F Astronomer
.fi
The rules file is searched again, and because no matches are found,
the results are written to the output table.
The above example shows some of the syntax of the rules file. The
target and action parts of a rule are separated by the symbol "=>" and
the entire rule is terminated by a semicolon. Unlike the above
example, a rule need not be contained on a single line; it can be
split among as many lines as desired, since the semicolon marks the
end of the rule. The amount of white space used is also optional,
symbols and identifiers may be run together or separated by blanks,
tabs, and blank lines. Comments may be placed on any line; they begin
with the "#" character and run to the end of the line. The different
conditions in the target part of a rule are separated by the symbol
"&&". Each condition consists of a column name and a column value
separated by an equals sign. The different results in the action part
of a rule are separated by the symbol "||". Each result consists of a
set of column names and values separated by equals signs. If there is
more than one column name and value in the result, the different
name/value pairs are separated by "&&" symbols. An example of a rule
with all these syntax elements is:
.nf
TARGET = ANY && OBSERVER = ANY => # Two conditions
TARGET=M31 && OBSERVER = HUBBLE || # First result
TARGET='OMEGA CENT' && OBSERVER = STRUVE ; # Second result
.fi
Notice that in the above example that an identifier containing a blank
can be used if the identifier is enclosed in quotes. Double quotes
could also have been used. Case is significant in an identifier. If a
syntax error is detected in a rules file or a column is named which
does occur in the input table, the task is terminated with a syntax
error. The error message contains the line and line number where the
error was detected and a brief message indicating the type of error.
This task can also be used to process more than one table by using file
name templates for the 'input' and 'output' parameters instead of file names.
Because processing each table takes a relatively long time, the
parameter 'verbose' can be set to "yes" so that the name of each table
will be displayed when it is processed.
.ih
PARAMETERS
.ls input [file name template]
Name of a table, or list of tables, used as input to the task
.le
.ls output [file name template]
Name of a table, or list of tables, to be produced as output to the task. The
number of input and output tables must be equal.
.le
.ls rbase [file name]
The file containing the rules used to expand the tables.
.le
.ls (debug = "") [file name]
The file containing the debugging output. If the file name is blank or null,
no debugging output is produced. When creating a set of rules, the output
produced by this task is not always what you expect. Turning on the debugging
output prints all the intermediate rule expansions to the designated file
as an aid in debugging the set of rules.
.le
.ls (verbose = no) [boolean]
Display the names of the input and output tables on the terminal screen (i.e.,
STDOUT) after each file is processed?
.le
.ih
EXAMPLES
1. Expand the table 'example' into 'example_2' using the rules in
'xrules.txt':
.nf
tt> texpand example.tab example_2.tab xrules.txt
.fi
2. Expand a set of fos tables using the rules in 'fosrules.txt':
.nf
tt> texpand y*.tab y*%%_2%.tab fosrules.txt verbose+
.fi
.ih
BUGS
The task cannot expand tables with boolean columns.
.ih
REFERENCES
This task was written by Bernie Simon.
.ih
SEE ALSO
.endhelp
|
