man/man1/rcalc.1

.\" RCSid "$Id$"
.TH RCALC 1 4/6/99 RADIANCE
.SH NAME
rcalc - record calculator
.SH SYNOPSIS
.B rcalc
[
.B \-b
][
.B \-l
][
.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 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.
.PP
The variable and function definitions in each
.I \-f source
file are read and compiled.
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.
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 "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 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"
calc(1), cnt(1), ev(1), getinfo(1), lam(1), tabfunc(1), total(1)
Revision:	1.4
Committed:	Tue Dec 9 15:59:06 2003 UTC (21 years, 10 months ago) by greg
Branch:	MAIN
Changes since 1.3:	+1 -1 lines
Log Message:	Fixed RCSid specification
#	User	Rev	Content
1	greg	1.4	.\" RCSid "$Id$"
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			.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	greg	1.2	.PP
42	greg	1.1	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	greg	1.2	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	greg	1.1	A
60			.I \-o format
61			option specifies an alternate output record format.
62	greg	1.2	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	greg	1.1	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	greg	1.2	.PP
84	greg	1.1	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	greg	1.2	.PP
99	greg	1.1	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	greg	1.3	.BR "in(n)"
213			Return the value for input column
214			.I n,
215			or the number of columns available in this record if
216			.I n
217			is 0.
218			This is an alternate way to get a column value instead of using
219			the $N notation, and is more flexible since it is programmable.
220			This function is disabled if an input format is used.
221			.TP
222	greg	1.1	.BR "if(cond, then, else)"
223			if cond is greater than zero,
224			then is evaluated, otherwise else is evaluated.
225			This function is necessary for recursive definitions.
226			.TP
227			.BR "select(N, a1, a2, ..)"
228			return aN (N is rounded to the nearest integer).
229			This function provides array capabilities.
230			If
231			.I N
232			is zero, the number of available arguments is returned.
233			.TP
234			.BR "rand(x)"
235			compute a random number between 0 and 1 based on x.
236			.TP
237			.BR "floor(x)"
238			return largest integer not greater than x.
239			.TP
240			.BR "ceil(x)"
241			return smallest integer not less than x.
242			.TP
243			.BR "sqrt(x)"
244			return square root of x.
245			.TP
246			.BR "exp(x)"
247			compute e to the power of x (e approx = 2.718281828).
248			.TP
249			.BR "log(x)"
250			compute the logarithm of x to the base e.
251			.TP
252			.BR "log10(x)"
253			compute the logarithm of x to the base 10.
254			.TP
255			.BR PI
256			the ratio of a circle's circumference to its diameter.
257			.TP
258			.BR recno
259			the number of records recognized thus far.
260			.TP
261			.BR outno
262			the number or records output thus far (including this one).
263			.TP
264			.BR "sin(x), cos(x), tan(x)"
265			trigonometric functions.
266			.TP
267			.BR "asin(x), acos(x), atan(x)"
268			inverse trigonometric functions.
269			.TP
270			.BR "atan2(y, x)"
271			inverse tangent of y/x (range -pi to pi).
272			.SH EXAMPLE
273			To print the square root of column two in column one,
274			and column one times column three in column two:
275			.IP "" .2i
276			rcalc -e '$1=sqrt($2);$2=$1*$3' inputfile > outputfile
277			.SH AUTHOR
278			Greg Ward
279			.SH BUGS
280			String variables can only be used in input and output formats and
281			.I \-s
282			options, not in definitions.
283			.PP
284			Tabs count as single spaces inside fields.
285			.SH "SEE ALSO"
286	greg	1.2	calc(1), cnt(1), ev(1), getinfo(1), lam(1), tabfunc(1), total(1)