Annotation of src/usr.bin/rs/rs.1, Revision 1.6
1.6 ! aaron 1: .\" $OpenBSD: rs.1,v 1.5 2000/03/06 12:23:41 aaron 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.
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
1.5 aaron 35: .\" $FreeBSD: src/usr.bin/rs/rs.1,v 1.4 1999/08/28 01:05:21 peter Exp $
1.1 deraadt 36: .\"
1.5 aaron 37: .Dd December 30, 1993
38: .Dt RS 1
39: .Os
40: .Sh NAME
41: .Nm rs
42: .Nd reshape a data array
43: .Sh SYNOPSIS
44: .Nm rs
45: .Oo
46: .Sm off
47: .Xo Fl Oo Cm Op Cm csCS
48: .Op Ar x
49: .Op Cm kKgGw
50: .Op Ar N
51: .Cm tTeEnyjhHmz Oc
52: .Xc
53: .Oc
54: .Sm on
55: .Op Ar rows Op Ar cols
56: .Sh DESCRIPTION
57: .Nm
1.1 deraadt 58: reads the standard input, interpreting each line as a row
59: of blank-separated entries in an array,
60: transforms the array according to the options,
61: and writes it on the standard output.
62: With no arguments it transforms stream input into a columnar
63: format convenient for terminal viewing.
1.5 aaron 64: .Pp
1.1 deraadt 65: The shape of the input array is deduced from the number of lines
66: and the number of columns on the first line.
67: If that shape is inconvenient, a more useful one might be
1.5 aaron 68: obtained by skipping some of the input with the
69: .Fl k
70: option.
1.1 deraadt 71: Other options control interpretation of the input columns.
1.5 aaron 72: .Pp
1.1 deraadt 73: The shape of the output array is influenced by the
1.5 aaron 74: .Ar rows
1.1 deraadt 75: and
1.5 aaron 76: .Ar cols
1.1 deraadt 77: specifications, which should be positive integers.
78: If only one of them is a positive integer,
1.5 aaron 79: .Nm
1.1 deraadt 80: computes a value for the other which will accommodate
81: all of the data.
82: When necessary, missing data are supplied in a manner
83: specified by the options and surplus data are deleted.
84: There are options to control presentation of the output columns,
85: including transposition of the rows and columns.
1.5 aaron 86: .Pp
1.4 aaron 87: The options are as follows:
1.6 ! aaron 88: .Bl -tag -width Ds
1.5 aaron 89: .It Fl c Ns Ar x
90: Input columns are delimited by the single character
91: .Ar x .
92: A missing
93: .Ar x
94: is taken to be
95: .Ql ^I .
96: .It Fl s Ns Ar x
97: Like
98: .Fl c ,
99: but maximal strings of
100: .Ar x
101: are delimiters.
102: .It Fl C Ns Ar x
103: Output columns are delimited by the single character
104: .Ar x .
105: A missing
106: .Ar x
107: is taken to be
108: .Ql ^I .
109: .It Fl S Ns Ar x
110: Like
111: .Fl C ,
112: but padded strings of
113: .Ar x
114: are delimiters.
115: .It Fl t
1.1 deraadt 116: Fill in the rows of the output array using the columns of the
117: input array, that is, transpose the input while honoring any
1.5 aaron 118: .Ar rows
1.1 deraadt 119: and
1.5 aaron 120: .Ar cols
1.1 deraadt 121: specifications.
1.5 aaron 122: .It Fl T
1.1 deraadt 123: Print the pure transpose of the input, ignoring any
1.5 aaron 124: .Ar rows
1.1 deraadt 125: or
1.5 aaron 126: .Ar cols
1.1 deraadt 127: specification.
1.5 aaron 128: .It Fl k Ns Ar N
129: Ignore the first
130: .Ar N
131: lines of input.
132: .It Fl K Ns Ar N
133: Like
134: .Fl k ,
135: but print the ignored lines.
136: .It Fl g Ns Ar N
137: The gutter width (inter-column space), normally 2, is taken to be
138: .Ar N .
139: .It Fl G Ns Ar N
140: The gutter width has
141: .Ar N
142: percent of the maximum column width added to it.
143: .It Fl e
1.1 deraadt 144: Consider each line of input as an array entry.
1.5 aaron 145: .It Fl E
146: Consider each character of input as an array entry.
147: .It Fl n
1.1 deraadt 148: On lines having fewer entries than the first line,
149: use null entries to pad out the line.
150: Normally, missing entries are taken from the next line of input.
1.5 aaron 151: .It Fl y
1.1 deraadt 152: If there are too few entries to make up the output dimensions,
153: pad the output by recycling the input from the beginning.
154: Normally, the output is padded with blanks.
1.5 aaron 155: .It Fl h
1.1 deraadt 156: Print the shape of the input array and do nothing else.
157: The shape is just the number of lines and the number of
158: entries on the first line.
1.5 aaron 159: .It Fl H
160: Like
161: .Fl h ,
162: but also print the length of each line.
163: .It Fl j
1.1 deraadt 164: Right adjust entries within columns.
1.5 aaron 165: .It Fl w Ns Ar N
1.1 deraadt 166: The width of the display, normally 80, is taken to be the positive
1.5 aaron 167: integer
168: .Ar N .
169: .It Fl m
1.1 deraadt 170: Do not trim excess delimiters from the ends of the output array.
1.5 aaron 171: .It Fl z
1.2 deraadt 172: Adapt column widths to fit the largest entries appearing in them.
1.5 aaron 173: .El
174: .Pp
1.1 deraadt 175: With no arguments,
1.5 aaron 176: .Nm
1.1 deraadt 177: transposes its input, and assumes one array entry per input line
178: unless the first non-ignored line is longer than the display width.
179: Option letters which take numerical arguments interpret a missing
180: number as zero unless otherwise indicated.
1.5 aaron 181: .Sh EXAMPLES
182: .Nm
1.1 deraadt 183: can be used as a filter to convert the stream output
184: of certain programs (e.g.,
1.5 aaron 185: .Xr spell ,
186: .Xr du ,
187: .Xr file ,
188: .Xr look ,
189: .Xr nm ,
190: .Xr who ,
1.1 deraadt 191: and
1.5 aaron 192: .Xr wc 1 )
193: into a convenient
194: .Dq window
195: format, as in
196: .Bd -literal -offset indent
197: % who | rs
198: .Ed
199: .Pp
1.1 deraadt 200: This function has been incorporated into the
1.5 aaron 201: .Xr ls 1
1.1 deraadt 202: program, though for most programs with similar output
1.5 aaron 203: .Nm
1.1 deraadt 204: suffices.
1.5 aaron 205: .Pp
1.1 deraadt 206: To convert stream input into vector output and back again, use
1.5 aaron 207: .Bd -literal -offset indent
208: % rs 1 0 | rs 0 1
209: .Ed
210: .Pp
1.1 deraadt 211: A 10 by 10 array of random numbers from 1 to 100 and
212: its transpose can be generated with
1.5 aaron 213: .Bd -literal -offset indent
214: % jot \-r 100 | rs 10 10 | tee array | rs \-T > tarray
215: .Ed
216: .Pp
1.1 deraadt 217: In the editor
1.5 aaron 218: .Xr vi 1 ,
1.1 deraadt 219: a file consisting of a multi-line vector with 9 elements per line
220: can undergo insertions and deletions,
221: and then be neatly reshaped into 9 columns with
1.5 aaron 222: .Bd -literal -offset indent
1.1 deraadt 223: :1,$!rs 0 9
1.5 aaron 224: .Ed
225: .Pp
1.1 deraadt 226: Finally, to sort a database by the first line of each 4-line field, try
1.5 aaron 227: .Bd -literal -offset indent
228: % rs \-eC 0 4 | sort | rs \-c 0 1
229: .Ed
230: .Sh SEE ALSO
231: .Xr jot 1 ,
232: .Xr pr 1 ,
233: .Xr sort 1 ,
234: .Xr vi 1
235: .Sh BUGS
1.1 deraadt 236: Handles only two dimensional arrays.
1.5 aaron 237: .Pp
1.1 deraadt 238: The algorithm currently reads the whole file into memory,
239: so files that do not fit in memory will not be reshaped.
1.5 aaron 240: .Pp
1.1 deraadt 241: Fields cannot be defined yet on character positions.
1.5 aaron 242: .Pp
1.1 deraadt 243: Re-ordering of columns is not yet possible.
1.5 aaron 244: .Pp
1.1 deraadt 245: 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