man/man1/rcalc.1

.\" RCSid "$Id: rcalc.1,v 1.14 2019/06/10 13:56:52 greg Exp $"
.TH RCALC 1 4/6/99 RADIANCE
.SH NAME
rcalc - record calculator
.SH SYNOPSIS
.B rcalc
[
.B \-b
][
.B \-l
][
.B \-p
][
.B \-n
][
.B \-w
][
.B \-u
][
.B \-tS
][
.B "\-i format"
][
.B "\-o format"
][
.B "\-in M"
][
.B "\-on M"
][
.B "\-f source"
][
.B "\-e expr"
][
.B "\-s svar=sval"
]
file ..
.SH DESCRIPTION
.I Rcalc
transforms ``records'' from each
.I file
according to the given set of literal and relational information.
By default, records are separated by newlines, and contain
numeric fields separated by tabs.
The
.I \-tS
option is used to specify an alternate tab character.
.PP
A
.I \-i format
option specifies a template for an alternate
input record format.
.I Format
is interpreted as a specification string if it contains a dollar sign '$'.
Otherwise, it is interpreted as the name of the file containing
the format specification.
In either case, if the format does not end with a newline, one will be added
automatically.
A special form of the
.I \-i
option may be followed immediately by a 'd' or an 'f' and an optional
count, which defaults to 1, indicating the number of double or float
binary values to read per record on the input file.
If the input is byte-swapped, the
.I \-iD
or
.I \-iF
options may be substituted.
If binary input is specified, no format string or file is needed.
.PP
A
.I \-o format
option specifies an alternate output record format.
It is interpreted the same as an input specification, except that
the special
.I \-od
or
.I \-of
options do not require a count, as this will be determined by the
number of output channels in the given expressions.
If byte-swapped output is desired, the
.I \-oD
or
.I \-oF
options may be substituted.
.PP
The
.I \-p
option specifies "passive mode," where characters that do not
match the input format are passed unaltered to the output.
This option has no effect unless
.I \-i
is also specified, and does not make much sense unless
.I \-o
is also given.
With both input and output formats, the passive mode can
effectively substitute information in the middle of a file
or stream without affecting the rest of the data.
.PP
If a
.I \-in
option is given with a positive integer argument,
.I rcalc
will stop processing input once it has loaded this number of records.
Similarly, if a
.I \-on
option is present,
.I rcalc
will stop after producing this many records, which may be a smaller
number if the
.I cond
variable is used.
If multiple input files are given, these counts are continuous over
the input and do not reset on each file.
.PP
The variable and function definitions in each
.I \-f source
file are read and compiled from the RADIANCE library where it is found.
The
.I \-e expr
option can be used to define variables on the command line.
Since many of the characters in an expression have special meaning
to the shell, it should usually be enclosed in single quotes.
The
.I \-s svar=sval
option can be used to assign a string variable a string value.
If this string variable appears in an input format, only records
with the specified value will be processed.
.PP
The
.I \-b
option instructs the program to accept only exact matches.
By default, tabs and spaces are ignored except
as field separators.
The
.I \-l
option instructs the program to ignore newlines in the input,
basically treating them the same as tabs and spaces.
Normally, the beginning of the input format matches the beginning of
a line, and the end of the format matches the end of a line.
With the
.I \-l
option, the input format can match anywhere on a line.
.PP
The
.I \-w
option causes non-fatal error messages (such as division by zero) to
be supressed.
The
.I \-u
option causes output to be flushed after each record.
The
.I \-n
option tells the program not to get any input, but to produce a
single output record.
Otherwise, if no files are given, the standard input is read.
.PP
Format files associate names with string and numeric fields
separated by literal information in a record.
A numeric field is given in a format file as a dollar sign, followed
by curly braces enclosing a variable name:
.PP
        This is a numeric field: ${vname}
.PP
A string variable is enclosed in parentheses:
.PP
        This is a string field: $(sname)
.PP
The program attempts to match literal information in
the input format to its input and assign string and numeric
fields accordingly.
If a string or numeric field variable appears more than once in
the input format, input values for the corresponding fields must
match (ie. have the same value) for the whole record to match.
Numeric values are allowed some deviation, on the order of 0.1%, but
string variables must match exactly.
Thus, dummy variables for "don't care" fields should be given unique
names so that they are not all required to take on the same value.
.PP
For each valid input record, an output record is produced
in its corresponding format.
Output field widths are given implicitly by the space occupied
in the format file, including the dollar sign and braces.
This makes it impossible to produce fields with fewer than four
characters.
If the
.I \-b
option is specified, input records must exactly match the
template.
By default, the character following each input field is used as
a delimiter.
This implies that string fields that are followed by white space
cannot contain strings with white space.
Also, numeric fields followed but not preceded by white space
will not accept numbers preceded by white space.
Adjacent input fields are advisable only with the
.I \-b
option.
Numeric output fields may contain expressions as well as variables.
A dollar sign may appear in a literal as two dollar signs ($$).
.PP
The definitions specified in
.I \-e
and
.I \-f
options relate numeric output fields to numeric input fields.
For the default record format, a field is a variable of the form
$N, where N is the column number, beginning with 1.
Output columns appear on the left-hand side of assignments, input
columns appear on the right-hand side.
.PP
A variable definition has the form:
.PP

        var = expression ;

.PP
Any instance of the variable in an expression will be replaced
with its definition.
.PP
An expression contains real numbers, variable names, function calls,
and the following operators:
.PP
        +  -  *  /  ^
.PP
Operators are evaluated left to right, except '^',
which is right associative.
Powers have the highest precedence; multiplication and
division are evaluated before addition and subtraction.
Expressions can be grouped with parentheses.
All values are double precision real.
.PP
A function definition has the form:
.PP

        func(a1, a2, ..) = expression ;

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