1 |
.\" RCSid "$Id: rcalc.1,v 1.5 2004/01/01 19:31:45 greg Exp $" |
2 |
.TH RCALC 1 4/6/99 RADIANCE |
3 |
.SH NAME |
4 |
rcalc - record calculator |
5 |
.SH SYNOPSIS |
6 |
.B rcalc |
7 |
[ |
8 |
.B \-b |
9 |
][ |
10 |
.B \-l |
11 |
][ |
12 |
.B \-p |
13 |
][ |
14 |
.B \-n |
15 |
][ |
16 |
.B \-w |
17 |
][ |
18 |
.B \-u |
19 |
][ |
20 |
.B \-tS |
21 |
][ |
22 |
.B "\-i format" |
23 |
][ |
24 |
.B "\-o format" |
25 |
][ |
26 |
.B "\-f source" |
27 |
][ |
28 |
.B "\-e expr" |
29 |
][ |
30 |
.B "\-s svar=sval" |
31 |
] |
32 |
file .. |
33 |
.SH DESCRIPTION |
34 |
.I Rcalc |
35 |
transforms ``records'' from each |
36 |
.I file |
37 |
according to the given set of literal and relational information. |
38 |
By default, records are separated by newlines, and contain |
39 |
numeric fields separated by tabs. |
40 |
The |
41 |
.I \-tS |
42 |
option is used to specify an alternate tab character. |
43 |
.PP |
44 |
A |
45 |
.I \-i format |
46 |
option specifies a template for an alternate |
47 |
input record format. |
48 |
.I Format |
49 |
is interpreted as a specification string if it contains a dollar sign '$'. |
50 |
Otherwise, it is interpreted as the name of the file containing |
51 |
the format specification. |
52 |
In either case, if the format does not end with a newline, one will be added |
53 |
automatically. |
54 |
A special form of the |
55 |
.I \-i |
56 |
option may be followed immediately by a 'd' or an 'f' and an optional |
57 |
count, which defaults to 1, indicating the number of double or float |
58 |
binary values to read per record on the input file. |
59 |
If binary input is specified, no format string or file is needed. |
60 |
.PP |
61 |
A |
62 |
.I \-o format |
63 |
option specifies an alternate output record format. |
64 |
It is interpreted the same as an input specification, except that |
65 |
the special |
66 |
.I \-od |
67 |
or |
68 |
.I \-of |
69 |
options do not require a count, as this will be determined by the |
70 |
number of output channels in the given expressions. |
71 |
.PP |
72 |
The |
73 |
.I \-p |
74 |
option specifies "passive mode," where characters that do not |
75 |
match the input format are passed unaltered to the output. |
76 |
This option has no effect unless |
77 |
.I \-i |
78 |
is also specified, and does not make much sense unless |
79 |
.I \-o |
80 |
is also given. |
81 |
With both input and output formats, the passive mode can |
82 |
effectively substitute information in the middle of a file |
83 |
or stream without affecting the rest of the data. |
84 |
.PP |
85 |
The variable and function definitions in each |
86 |
.I \-f source |
87 |
file are read and compiled. |
88 |
The |
89 |
.I \-e expr |
90 |
option can be used to define variables on the command line. |
91 |
Since many of the characters in an expression have special meaning |
92 |
to the shell, it should usually be enclosed in single quotes. |
93 |
The |
94 |
.I \-s svar=sval |
95 |
option can be used to assign a string variable a string value. |
96 |
If this string variable appears in an input format, only records |
97 |
with the specified value will be processed. |
98 |
.PP |
99 |
The |
100 |
.I \-b |
101 |
option instructs the program to accept only exact matches. |
102 |
By default, tabs and spaces are ignored except |
103 |
as field separators. |
104 |
The |
105 |
.I \-l |
106 |
option instructs the program to ignore newlines in the input, |
107 |
basically treating them the same as tabs and spaces. |
108 |
Normally, the beginning of the input format matches the beginning of |
109 |
a line, and the end of the format matches the end of a line. |
110 |
With the |
111 |
.I \-l |
112 |
option, the input format can match anywhere on a line. |
113 |
.PP |
114 |
The |
115 |
.I \-w |
116 |
option causes non-fatal error messages (such as division by zero) to |
117 |
be supressed. |
118 |
The |
119 |
.I \-u |
120 |
option causes output to be flushed after each record. |
121 |
The |
122 |
.I \-n |
123 |
option tells the program not to get any input, but to produce a |
124 |
single output record. |
125 |
Otherwise, if no files are given, the standard input is read. |
126 |
.PP |
127 |
Format files associate names with string and numeric fields |
128 |
separated by literal information in a record. |
129 |
A numeric field is given in a format file as a dollar sign, followed |
130 |
by curly braces enclosing a variable name: |
131 |
.PP |
132 |
This is a numeric field: ${vname} |
133 |
.PP |
134 |
A string variable is enclosed in parentheses: |
135 |
.PP |
136 |
This is a string field: $(sname) |
137 |
.PP |
138 |
The program attempts to match literal information in |
139 |
the input format to its input and assign string and numeric |
140 |
fields accordingly. |
141 |
If a string or numeric field variable appears more than once in |
142 |
the input format, input values for the corresponding fields must |
143 |
match (ie. have the same value) for the whole record to match. |
144 |
Numeric values are allowed some deviation, on the order of 0.1%, but |
145 |
string variables must match exactly. |
146 |
Thus, dummy variables for "don't care" fields should be given unique |
147 |
names so that they are not all required to take on the same value. |
148 |
.PP |
149 |
For each valid input record, an output record is produced |
150 |
in its corresponding format. |
151 |
Output field widths are given implicitly by the space occupied |
152 |
in the format file, including the dollar sign and braces. |
153 |
This makes it impossible to produce fields with fewer than four |
154 |
characters. |
155 |
If the |
156 |
.I \-b |
157 |
option is specified, input records must exactly match the |
158 |
template. |
159 |
By default, the character following each input field is used as |
160 |
a delimiter. |
161 |
This implies that string fields that are followed by white space |
162 |
cannot contain strings with white space. |
163 |
Also, numeric fields followed but not preceded by white space |
164 |
will not accept numbers preceded by white space. |
165 |
Adjacent input fields are advisable only with the |
166 |
.I \-b |
167 |
option. |
168 |
Numeric output fields may contain expressions as well as variables. |
169 |
A dollar sign may appear in a literal as two dollar signs ($$). |
170 |
.PP |
171 |
The definitions specified in |
172 |
.I \-e |
173 |
and |
174 |
.I \-f |
175 |
options relate numeric output fields to numeric input fields. |
176 |
For the default record format, a field is a variable of the form |
177 |
$N, where N is the column number, beginning with 1. |
178 |
Output columns appear on the left-hand side of assignments, input |
179 |
columns appear on the right-hand side. |
180 |
.PP |
181 |
A variable definition has the form: |
182 |
.PP |
183 |
|
184 |
var = expression ; |
185 |
|
186 |
.PP |
187 |
Any instance of the variable in an expression will be replaced |
188 |
with its definition. |
189 |
.PP |
190 |
An expression contains real numbers, variable names, function calls, |
191 |
and the following operators: |
192 |
.PP |
193 |
+ - * / ^ |
194 |
.PP |
195 |
Operators are evaluated left to right. |
196 |
Powers have the highest precedence; multiplication and |
197 |
division are evaluated before addition and subtraction. |
198 |
Expressions can be grouped with parentheses. |
199 |
All values are double precision real. |
200 |
.PP |
201 |
A function definition has the form: |
202 |
.PP |
203 |
|
204 |
func(a1, a2, ..) = expression ; |
205 |
|
206 |
.PP |
207 |
The expression can contain instances of the function arguments |
208 |
as well as other variables and functions. |
209 |
Function names can be passed as arguments. |
210 |
Recursive functions can be defined using calls to the defined |
211 |
function or other functions calling the defined function. |
212 |
.PP |
213 |
The variable |
214 |
.I cond, |
215 |
if defined, will determine whether the current input record produces |
216 |
an output record. |
217 |
If |
218 |
.I cond |
219 |
is positive, output is produced. |
220 |
If |
221 |
.I cond |
222 |
is less than or equal to zero, the record is skipped and no other expressions |
223 |
are evaluated. |
224 |
This provides a convenient method for avoiding inappropriate calculations. |
225 |
The following library of pre-defined functions and variables is provided: |
226 |
.TP 10n |
227 |
.BR "in(n)" |
228 |
Return the value for input column |
229 |
.I n, |
230 |
or the number of columns available in this record if |
231 |
.I n |
232 |
is 0. |
233 |
This is an alternate way to get a column value instead of using |
234 |
the $N notation, and is more flexible since it is programmable. |
235 |
This function is disabled if an input format is used. |
236 |
.TP |
237 |
.BR "if(cond, then, else)" |
238 |
if cond is greater than zero, |
239 |
then is evaluated, otherwise else is evaluated. |
240 |
This function is necessary for recursive definitions. |
241 |
.TP |
242 |
.BR "select(N, a1, a2, ..)" |
243 |
return aN (N is rounded to the nearest integer). |
244 |
This function provides array capabilities. |
245 |
If |
246 |
.I N |
247 |
is zero, the number of available arguments is returned. |
248 |
.TP |
249 |
.BR "rand(x)" |
250 |
compute a random number between 0 and 1 based on x. |
251 |
.TP |
252 |
.BR "floor(x)" |
253 |
return largest integer not greater than x. |
254 |
.TP |
255 |
.BR "ceil(x)" |
256 |
return smallest integer not less than x. |
257 |
.TP |
258 |
.BR "sqrt(x)" |
259 |
return square root of x. |
260 |
.TP |
261 |
.BR "exp(x)" |
262 |
compute e to the power of x (e approx = 2.718281828). |
263 |
.TP |
264 |
.BR "log(x)" |
265 |
compute the logarithm of x to the base e. |
266 |
.TP |
267 |
.BR "log10(x)" |
268 |
compute the logarithm of x to the base 10. |
269 |
.TP |
270 |
.BR PI |
271 |
the ratio of a circle's circumference to its diameter. |
272 |
.TP |
273 |
.BR recno |
274 |
the number of records recognized thus far. |
275 |
.TP |
276 |
.BR outno |
277 |
the number or records output thus far (including this one). |
278 |
.TP |
279 |
.BR "sin(x), cos(x), tan(x)" |
280 |
trigonometric functions. |
281 |
.TP |
282 |
.BR "asin(x), acos(x), atan(x)" |
283 |
inverse trigonometric functions. |
284 |
.TP |
285 |
.BR "atan2(y, x)" |
286 |
inverse tangent of y/x (range -pi to pi). |
287 |
.SH EXAMPLE |
288 |
To print the square root of column two in column one, |
289 |
and column one times column three in column two: |
290 |
.IP "" .2i |
291 |
rcalc -e '$1=sqrt($2);$2=$1*$3' inputfile > outputfile |
292 |
.SH AUTHOR |
293 |
Greg Ward |
294 |
.SH BUGS |
295 |
String variables can only be used in input and output formats and |
296 |
.I \-s |
297 |
options, not in definitions. |
298 |
.PP |
299 |
Tabs count as single spaces inside fields. |
300 |
.SH "SEE ALSO" |
301 |
cnt(1), ev(1), getinfo(1), icalc(1), rlam(1), tabfunc(1), total(1) |