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