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