source: trunk/third/rs/rs.1 @ 23442

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