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, 3 months ago) by greg
Branch:	MAIN
CVS Tags:	rad3R5
Log Message:	Added documentation to repository
#	Content
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)