man/man1/rcalc.1

.\" RCSid "$Id: rcalc.1,v 1.10 2013/09/05 17:53:22 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 "\-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
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 "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), tabfunc(1), total(1)
Revision:	1.11
Committed:	Thu Dec 19 16:38:12 2013 UTC (11 years, 4 months ago) by greg
Branch:	MAIN
CVS Tags:	rad4R2P2, rad5R0, rad4R2, rad4R2P1
Changes since 1.10:	+4 -2 lines
Log Message:	Changed rcalc and icalc to search RAYPATH for input *.cal files
#	User	Rev	Content
1	greg	1.11	.\" RCSid "$Id: rcalc.1,v 1.10 2013/09/05 17:53:22 greg Exp $"
2	greg	1.1	.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	greg	1.6	.B \-p
13			][
14	greg	1.1	.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	greg	1.2	.PP
44	greg	1.1	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	greg	1.2	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	greg	1.7	If the input is byte-swapped, the
60			.I \-iD
61			or
62			.I \-iF
63			options may be substituted.
64	greg	1.2	If binary input is specified, no format string or file is needed.
65			.PP
66	greg	1.1	A
67			.I \-o format
68			option specifies an alternate output record format.
69	greg	1.2	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	greg	1.7	If byte-swapped output is desired, the
77			.I \-oD
78			or
79			.I \-oF
80			options may be substituted.
81	greg	1.2	.PP
82	greg	1.6	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	greg	1.1	The variable and function definitions in each
96			.I \-f source
97	greg	1.11	file are read and compiled from the RADIANCE library where it is found.
98	greg	1.1	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	greg	1.2	.PP
109	greg	1.1	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	greg	1.2	.PP
124	greg	1.1	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	greg	1.9	Operators are evaluated left to right, except '^',
206			which is right associative.
207	greg	1.1	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	greg	1.9	.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	greg	1.3	.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	greg	1.1	.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	greg	1.8	inverse tangent of y/x (range \-pi to pi).
303	greg	1.1	.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	greg	1.8	rcalc \-e '$1=sqrt($2);$2=$1*$3' inputfile > outputfile
308	greg	1.11	.SH ENVIRONMENT
309			RAYPATH the directories to check for auxiliary files.
310	greg	1.1	.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	greg	1.10	cnt(1), ev(1), getinfo(1), icalc(1), rcollate(1), rlam(1), tabfunc(1), total(1)