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