Annotation of src/usr.bin/rs/rs.1, Revision 1.1.1.1
1.1 deraadt 1: .\" Copyright (c) 1993
2: .\" The Regents of the University of California. All rights reserved.
3: .\"
4: .\" Redistribution and use in source and binary forms, with or without
5: .\" modification, are permitted provided that the following conditions
6: .\" are met:
7: .\" 1. Redistributions of source code must retain the above copyright
8: .\" notice, this list of conditions and the following disclaimer.
9: .\" 2. Redistributions in binary form must reproduce the above copyright
10: .\" notice, this list of conditions and the following disclaimer in the
11: .\" documentation and/or other materials provided with the distribution.
12: .\" 3. All advertising materials mentioning features or use of this software
13: .\" must display the following acknowledgement:
14: .\" This product includes software developed by the University of
15: .\" California, Berkeley and its contributors.
16: .\" 4. Neither the name of the University nor the names of its contributors
17: .\" may be used to endorse or promote products derived from this software
18: .\" without specific prior written permission.
19: .\"
20: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30: .\" SUCH DAMAGE.
31: .\"
32: .\" @(#)rs.1 8.2 (Berkeley) 12/30/93
33: .\"
34: .TH RS 1 "December 30, 1993"
35: .UC 4
36: .SH NAME
37: rs \- reshape a data array
38: .SH SYNOPSIS
39: \fBrs [ \-[csCS][\fRx\fB][kKgGw][\fRN\fB]tTeEnyjhHm ] [ \fRrows\fB [ \fRcols\fB ] ]\fR
40: .SH DESCRIPTION
41: .I Rs
42: reads the standard input, interpreting each line as a row
43: of blank-separated entries in an array,
44: transforms the array according to the options,
45: and writes it on the standard output.
46: With no arguments it transforms stream input into a columnar
47: format convenient for terminal viewing.
48: .PP
49: The shape of the input array is deduced from the number of lines
50: and the number of columns on the first line.
51: If that shape is inconvenient, a more useful one might be
52: obtained by skipping some of the input with the \fB\-k\fP option.
53: Other options control interpretation of the input columns.
54: .PP
55: The shape of the output array is influenced by the
56: .I rows
57: and
58: .I cols
59: specifications, which should be positive integers.
60: If only one of them is a positive integer,
61: .I rs
62: computes a value for the other which will accommodate
63: all of the data.
64: When necessary, missing data are supplied in a manner
65: specified by the options and surplus data are deleted.
66: There are options to control presentation of the output columns,
67: including transposition of the rows and columns.
68: .PP
69: The options are described below.
70: .IP \fB\-c\fRx
71: Input columns are delimited by the single character \fIx\fP.
72: A missing \fIx\fP is taken to be `^I'.
73: .IP \fB\-s\fRx
74: Like \fB\-c\fR, but maximal strings of \fIx\fP are delimiters.
75: .IP \fB\-C\fRx
76: Output columns are delimited by the single character \fIx\fP.
77: A missing \fIx\fP is taken to be `^I'.
78: .IP \fB\-S\fRx
79: Like \fB\-C\fR, but padded strings of \fIx\fP are delimiters.
80: .IP \fB\-t\fR
81: Fill in the rows of the output array using the columns of the
82: input array, that is, transpose the input while honoring any
83: .I rows
84: and
85: .I cols
86: specifications.
87: .IP \fB\-T\fR
88: Print the pure transpose of the input, ignoring any
89: .I rows
90: or
91: .I cols
92: specification.
93: .IP \fB\-k\fRN
94: Ignore the first \fIN\fR lines of input.
95: .IP \fB\-K\fRN
96: Like \fB\-k\fR, but print the ignored lines.
97: .IP \fB\-g\fRN
98: The gutter width (inter-column space), normally 2, is taken to be \fIN\fR.
99: .IP \fB\-G\fRN
100: The gutter width has \fIN\fR percent of the maximum
101: column width added to it.
102: .IP \fB\-e\fR
103: Consider each line of input as an array entry.
104: .IP \fB\-n\fR
105: On lines having fewer entries than the first line,
106: use null entries to pad out the line.
107: Normally, missing entries are taken from the next line of input.
108: .IP \fB\-y\fR
109: If there are too few entries to make up the output dimensions,
110: pad the output by recycling the input from the beginning.
111: Normally, the output is padded with blanks.
112: .IP \fB\-h\fR
113: Print the shape of the input array and do nothing else.
114: The shape is just the number of lines and the number of
115: entries on the first line.
116: .IP \fB\-H\fR
117: Like \fB\-h\fR, but also print the length of each line.
118: .IP \fB\-j\fR
119: Right adjust entries within columns.
120: .IP \fB\-w\fRN
121: The width of the display, normally 80, is taken to be the positive
122: integer \fIN\fP.
123: .IP \fB\-m\fR
124: Do not trim excess delimiters from the ends of the output array.
125: .PP
126: With no arguments,
127: .I rs
128: transposes its input, and assumes one array entry per input line
129: unless the first non-ignored line is longer than the display width.
130: Option letters which take numerical arguments interpret a missing
131: number as zero unless otherwise indicated.
132: .SH EXAMPLES
133: .de IC
134: .IP
135: .ss 36
136: .ft B
137: ..
138: .de NC
139: .br
140: .ss 12
141: .PP
142: ..
143: .I Rs
144: can be used as a filter to convert the stream output
145: of certain programs (e.g.,
146: .IR spell ,
147: .IR du ,
148: .IR file ,
149: .IR look ,
150: .IR nm ,
151: .IR who ,
152: and
153: .IR wc (1))
154: into a convenient ``window'' format, as in
155: .IC
156: who | rs
157: .NC
158: This function has been incorporated into the
159: .IR ls (1)
160: program, though for most programs with similar output
161: .I rs
162: suffices.
163: .PP
164: To convert stream input into vector output and back again, use
165: .IC
166: rs 1 0 | rs 0 1
167: .NC
168: A 10 by 10 array of random numbers from 1 to 100 and
169: its transpose can be generated with
170: .IC
171: jot \-r 100 | rs 10 10 | tee array | rs \-T > tarray
172: .NC
173: In the editor
174: .IR vi (1),
175: a file consisting of a multi-line vector with 9 elements per line
176: can undergo insertions and deletions,
177: and then be neatly reshaped into 9 columns with
178: .IC
179: :1,$!rs 0 9
180: .NC
181: Finally, to sort a database by the first line of each 4-line field, try
182: .IC
183: rs \-eC 0 4 | sort | rs \-c 0 1
184: .NC
185: .SH SEE ALSO
186: jot(1), vi(1), sort(1), pr(1)
187: .SH BUGS
188: Handles only two dimensional arrays.
189:
190: The algorithm currently reads the whole file into memory,
191: so files that do not fit in memory will not be reshaped.
192:
193: Fields cannot be defined yet on character positions.
194:
195: Re-ordering of columns is not yet possible.
196:
197: There are too many options.