Annotation of src/usr.bin/rs/rs.1, Revision 1.2
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.
1.2 ! deraadt 125: .IP \fB\-z\fR
! 126: Adapt column widths to fit the largest entries appearing in them.
1.1 deraadt 127: .PP
128: With no arguments,
129: .I rs
130: transposes its input, and assumes one array entry per input line
131: unless the first non-ignored line is longer than the display width.
132: Option letters which take numerical arguments interpret a missing
133: number as zero unless otherwise indicated.
134: .SH EXAMPLES
135: .de IC
136: .IP
137: .ss 36
138: .ft B
139: ..
140: .de NC
141: .br
142: .ss 12
143: .PP
144: ..
145: .I Rs
146: can be used as a filter to convert the stream output
147: of certain programs (e.g.,
148: .IR spell ,
149: .IR du ,
150: .IR file ,
151: .IR look ,
152: .IR nm ,
153: .IR who ,
154: and
155: .IR wc (1))
156: into a convenient ``window'' format, as in
157: .IC
158: who | rs
159: .NC
160: This function has been incorporated into the
161: .IR ls (1)
162: program, though for most programs with similar output
163: .I rs
164: suffices.
165: .PP
166: To convert stream input into vector output and back again, use
167: .IC
168: rs 1 0 | rs 0 1
169: .NC
170: A 10 by 10 array of random numbers from 1 to 100 and
171: its transpose can be generated with
172: .IC
173: jot \-r 100 | rs 10 10 | tee array | rs \-T > tarray
174: .NC
175: In the editor
176: .IR vi (1),
177: a file consisting of a multi-line vector with 9 elements per line
178: can undergo insertions and deletions,
179: and then be neatly reshaped into 9 columns with
180: .IC
181: :1,$!rs 0 9
182: .NC
183: Finally, to sort a database by the first line of each 4-line field, try
184: .IC
185: rs \-eC 0 4 | sort | rs \-c 0 1
186: .NC
187: .SH SEE ALSO
188: jot(1), vi(1), sort(1), pr(1)
189: .SH BUGS
190: Handles only two dimensional arrays.
191:
192: The algorithm currently reads the whole file into memory,
193: so files that do not fit in memory will not be reshaped.
194:
195: Fields cannot be defined yet on character positions.
196:
197: Re-ordering of columns is not yet possible.
198:
199: There are too many options.
![[BACK]](/icons/back.gif){kind=icon}
Return to rs.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / rs