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