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