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