man/man1/rsplit.1

.\" RCSid "$Id: rsplit.1,v 1.9 2020/04/04 16:23:00 greg Exp $"
.TH RSPLIT 1 7/8/97 RADIANCE
.SH NAME
rsplit - splits standard input into multiple output files or streams
.SH SYNOPSIS
.B rsplit
[
.B \-tS
][
.B \-ih
][
.B \-iH
][
.B \-oh
][
.B \-oH
][
.B "\-x xres \-y yres"
][
.B \-oaN
|
.B \-ofN
|
.B \-odN
|
.B \-ocN
|
.B \-oiN
|
.B \-owN
|
.B \-obN
][
.B \-f
][
.B \-a
][
.B "\-on M"
]
output1 [options] output2 ..
.SH DESCRIPTION
.I Rsplit
writes lines or fields from the standard input to one or more output
streams.
By default, fields are separated by a
newline character (i.e., input is distributed by lines),
but the terminator can be changed using the
.I \-t
option.
If a space is specified as the terminator, then fields are separated by
any number of white spaces, including tabs, returns, and newlines.
Different terminators may be given for different fields by specifying
additional
.I \-t
options between each output specification.
Note that there is no space between this option and its argument, and
certain arguments, such as a space or a tab, must be quoted or escaped
with a backslash in most shells.
If no argument is given, the default newline terminator is re-established.
.PP
An output is either a file or a command.
If an output file exists, it will not be overwritten unless the
.I \-f
option is given, or it is being appended using the
.I \-a
option.
Commands are given in quotes, and begin with an exclamantion point ('!').
A period ('.') may also be specified as output,
which indicates that no output is desired for this field.
The corresponding data will be skipped on the input.
.PP
The
.I \-oa
option may be used to specify ASCII data (the default), or the
.I \-of
option may be used to indicated binary IEEE 32-bit floats.
Similarly, the
.I \-od
and
.I \-oi
options may be used to indicate binary 64-bit doubles or integer words,
respectively.
The
.I \-ow
option specifies 2-byte short words, and the
.I \-ob
option specifies bytes.
If a number immediately follows any of these options, then it
indicates that multiple such values are expected for each record.
For example,
.I \-of3
indicates three floats per output record for the next named output.
In the case of the
.I \-oa
option, no number writes one line or field per stream, and numbers
greater than zero write multiple fields per record to the same stream.
If the terminating character is set to something other than newline ('\\n'),
a newline is added after each record (in addition to the terminator).
For binary output formts, no number implies one value per output.
No terminator characters are expected or written for binary outputs.
.PP
If a
.I \-on
option is given with a positive integer argument, this will be the
maximum number of records that will be written by
.I rsplit.
.PP
A hyphen ('-') by itself can be used to indicate the standard
output, and may appear multiple times.
The options before the first appearance determine the
header parameters, if any.
Results will be unpredictable if the standard output is specified
in this way
and any of the command outputs also writes to their standard output.
At most, one command may reliably write to its standard output.
.PP
The
.I \-ih
option tells
.I rsplit
to expect a Radiance header on its input.
The
.I \-iH
option says to expect a resolution string for an image or similar.
The
.I \-x
and
.I \-y
options may alternatively be used to specify the input dimensions.
The
.I \-oh
option tells
.I rsplit
to produce a Radiance header on the next output stream.
The
.I \-oH
option will write a resolution string.
These options toggle the associated mode on and off,
so it is possible to have one output include a header or
resolution string and not the next by specifying the option(s) again.
Neither
.I \-oh
nor
.I \-oH
may be used with the append mode ('-a'), which may also be toggled.
.SH EXAMPLES
To alternate 5 lines between two output files:
.IP "" .2i
rsplit -oa5 output1.txt output2.txt < input.txt
.PP
To send the first of each double precision triplet to one file, and the second
and third to a second file, stopping after 500 triplets:
.IP "" .2i
rsplit -on 500 -od firstvals.dbl -od2 followingpairs.dbl < triplets.dbl
.PP
To convey material, color and distance information from rtrace to
separate files:
.IP "" .2i
vwrays [viewspec] | rtrace [options] -x 1024 -y 768 -h+ -oMlv octree | rsplit -ih -iH -t^I mats.txt -of depth.zbf -oh -oH -of3 '!pvalue -r -df > image.hdr'
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
cnt(1), histo(1), neaten(1), rcalc(1), rcode_depth(1),
rcode_ident(1), rcode_norm(1), rcode2bmp(1),
rlam(1), rtpict(1), rtrace(1), split(1), tabfunc(1), total(1)
Revision:	1.10
Committed:	Sun Apr 5 02:25:22 2020 UTC (5 years, 1 month ago) by greg
Branch:	MAIN
Changes since 1.9:	+5 -3 lines
Log Message:	Fixed issue with duplicate, incorrect headers if '-' used more than once
#	User	Rev	Content
1	greg	1.10	.\" RCSid "$Id: rsplit.1,v 1.9 2020/04/04 16:23:00 greg Exp $"
2	greg	1.1	.TH RSPLIT 1 7/8/97 RADIANCE
3			.SH NAME
4			rsplit - splits standard input into multiple output files or streams
5			.SH SYNOPSIS
6			.B rsplit
7			[
8			.B \-tS
9			][
10			.B \-ih
11			][
12			.B \-iH
13			][
14			.B \-oh
15			][
16			.B \-oH
17			][
18	greg	1.3	.B "\-x xres \-y yres"
19			][
20	greg	1.1	.B \-oaN
21			\|
22			.B \-ofN
23			\|
24			.B \-odN
25			\|
26			.B \-ocN
27			\|
28			.B \-oiN
29			\|
30			.B \-owN
31			\|
32			.B \-obN
33			][
34			.B \-f
35			][
36			.B \-a
37			][
38			.B "\-on M"
39			]
40			output1 [options] output2 ..
41			.SH DESCRIPTION
42			.I Rsplit
43			writes lines or fields from the standard input to one or more output
44			streams.
45			By default, fields are separated by a
46	greg	1.3	newline character (i.e., input is distributed by lines),
47			but the terminator can be changed using the
48	greg	1.1	.I \-t
49			option.
50	greg	1.8	If a space is specified as the terminator, then fields are separated by
51			any number of white spaces, including tabs, returns, and newlines.
52	greg	1.3	Different terminators may be given for different fields by specifying
53	greg	1.1	additional
54			.I \-t
55	greg	1.3	options between each output specification.
56	greg	1.8	Note that there is no space between this option and its argument, and
57			certain arguments, such as a space or a tab, must be quoted or escaped
58			with a backslash in most shells.
59			If no argument is given, the default newline terminator is re-established.
60	greg	1.1	.PP
61			An output is either a file or a command.
62			If an output file exists, it will not be overwritten unless the
63			.I \-f
64			option is given, or it is being appended using the
65			.I \-a
66			option.
67			Commands are given in quotes, and begin with an exclamantion point ('!').
68	greg	1.9	A period ('.') may also be specified as output,
69			which indicates that no output is desired for this field.
70			The corresponding data will be skipped on the input.
71	greg	1.1	.PP
72			The
73			.I \-oa
74			option may be used to specify ASCII data (the default), or the
75			.I \-of
76			option may be used to indicated binary IEEE 32-bit floats.
77			Similarly, the
78			.I \-od
79			and
80			.I \-oi
81			options may be used to indicate binary 64-bit doubles or integer words,
82			respectively.
83			The
84			.I \-ow
85			option specifies 2-byte short words, and the
86			.I \-ob
87			option specifies bytes.
88			If a number immediately follows any of these options, then it
89			indicates that multiple such values are expected for each record.
90			For example,
91			.I \-of3
92			indicates three floats per output record for the next named output.
93			In the case of the
94			.I \-oa
95			option, no number writes one line or field per stream, and numbers
96	greg	1.3	greater than zero write multiple fields per record to the same stream.
97			If the terminating character is set to something other than newline ('\\n'),
98			a newline is added after each record (in addition to the terminator).
99	greg	1.1	For binary output formts, no number implies one value per output.
100	greg	1.7	No terminator characters are expected or written for binary outputs.
101	greg	1.1	.PP
102			If a
103			.I \-on
104			option is given with a positive integer argument, this will be the
105			maximum number of records that will be written by
106			.I rsplit.
107			.PP
108			A hyphen ('-') by itself can be used to indicate the standard
109			output, and may appear multiple times.
110	greg	1.10	The options before the first appearance determine the
111			header parameters, if any.
112	greg	1.1	Results will be unpredictable if the standard output is specified
113			in this way
114			and any of the command outputs also writes to their standard output.
115			At most, one command may reliably write to its standard output.
116			.PP
117			The
118			.I \-ih
119			option tells
120			.I rsplit
121			to expect a Radiance header on its input.
122			The
123			.I \-iH
124			option says to expect a resolution string for an image or similar.
125			The
126			.I \-x
127			and
128			.I \-y
129			options may alternatively be used to specify the input dimensions.
130			The
131			.I \-oh
132			option tells
133			.I rsplit
134			to produce a Radiance header on the next output stream.
135			The
136			.I \-oH
137			option will write a resolution string.
138			These options toggle the associated mode on and off,
139			so it is possible to have one output include a header or
140			resolution string and not the next by specifying the option(s) again.
141			Neither
142			.I \-oh
143			nor
144			.I \-oH
145	greg	1.6	may be used with the append mode ('-a'), which may also be toggled.
146	greg	1.5	.SH EXAMPLES
147	greg	1.1	To alternate 5 lines between two output files:
148			.IP "" .2i
149	greg	1.2	rsplit -oa5 output1.txt output2.txt < input.txt
150	greg	1.1	.PP
151			To send the first of each double precision triplet to one file, and the second
152			and third to a second file, stopping after 500 triplets:
153			.IP "" .2i
154	greg	1.2	rsplit -on 500 -od firstvals.dbl -od2 followingpairs.dbl < triplets.dbl
155	greg	1.1	.PP
156			To convey material, color and distance information from rtrace to
157			separate files:
158			.IP "" .2i
159			vwrays [viewspec] \| rtrace [options] -x 1024 -y 768 -h+ -oMlv octree \| rsplit -ih -iH -t^I mats.txt -of depth.zbf -oh -oH -of3 '!pvalue -r -df > image.hdr'
160			.SH AUTHOR
161			Greg Ward
162			.SH "SEE ALSO"
163	greg	1.6	cnt(1), histo(1), neaten(1), rcalc(1), rcode_depth(1),
164	greg	1.10	rcode_ident(1), rcode_norm(1), rcode2bmp(1),
165			rlam(1), rtpict(1), rtrace(1), split(1), tabfunc(1), total(1)