Annotation of src/usr.bin/rs/rs.1, Revision 1.19
1.19 ! schwarze 1: .\" $OpenBSD: rs.1,v 1.18 2016/01/04 23:21:28 schwarze Exp $
1.10 millert 2: .\" $FreeBSD: src/usr.bin/rs/rs.1,v 1.4 1999/08/28 01:05:21 peter Exp $
1.3 deraadt 3: .\"
1.1 deraadt 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.
1.8 millert 15: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 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: .\"
1.19 ! schwarze 33: .Dd $Mdocdate: January 4 2016 $
1.5 aaron 34: .Dt RS 1
35: .Os
36: .Sh NAME
37: .Nm rs
38: .Nd reshape a data array
39: .Sh SYNOPSIS
40: .Nm rs
1.10 millert 41: .Op Fl CcSs Ns Op Ar x
1.14 sobrado 42: .Op Fl GgKkw Ar N
1.11 jmc 43: .Op Fl EeHhjmnTtyz
1.5 aaron 44: .Op Ar rows Op Ar cols
45: .Sh DESCRIPTION
46: .Nm
1.1 deraadt 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.
1.5 aaron 53: .Pp
1.1 deraadt 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
1.5 aaron 57: obtained by skipping some of the input with the
58: .Fl k
59: option.
1.1 deraadt 60: Other options control interpretation of the input columns.
1.5 aaron 61: .Pp
1.1 deraadt 62: The shape of the output array is influenced by the
1.5 aaron 63: .Ar rows
1.1 deraadt 64: and
1.5 aaron 65: .Ar cols
1.1 deraadt 66: specifications, which should be positive integers.
67: If only one of them is a positive integer,
1.5 aaron 68: .Nm
1.1 deraadt 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.
1.5 aaron 75: .Pp
1.4 aaron 76: The options are as follows:
1.6 aaron 77: .Bl -tag -width Ds
1.15 sobrado 78: .It Fl C Ns Op Ar x
1.10 millert 79: Output columns are delimited by the single character
1.5 aaron 80: .Ar x .
81: A missing
82: .Ar x
83: is taken to be
84: .Ql ^I .
1.15 sobrado 85: .It Fl c Ns Op Ar x
1.10 millert 86: Input columns are delimited by the single character
1.5 aaron 87: .Ar x .
88: A missing
89: .Ar x
90: is taken to be
91: .Ql ^I .
1.10 millert 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.
1.15 sobrado 127: .It Fl S Ns Op Ar x
1.5 aaron 128: Like
129: .Fl C ,
130: but padded strings of
131: .Ar x
132: are delimiters.
1.15 sobrado 133: .It Fl s Ns Op Ar x
1.10 millert 134: Like
135: .Fl c ,
136: but maximal strings of
137: .Ar x
138: are delimiters.
1.12 jmc 139: .It Fl T
140: Print the pure transpose of the input, ignoring any
141: .Ar rows
142: or
143: .Ar cols
144: specification.
1.5 aaron 145: .It Fl t
1.1 deraadt 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
1.5 aaron 148: .Ar rows
1.1 deraadt 149: and
1.5 aaron 150: .Ar cols
1.1 deraadt 151: specifications.
1.10 millert 152: .It Fl w Ns Ar N
153: The width of the display, normally 80, is taken to be the positive
154: integer
1.5 aaron 155: .Ar N .
156: .It Fl y
1.1 deraadt 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.
1.5 aaron 160: .It Fl z
1.2 deraadt 161: Adapt column widths to fit the largest entries appearing in them.
1.5 aaron 162: .El
163: .Pp
1.1 deraadt 164: With no arguments,
1.5 aaron 165: .Nm
1.1 deraadt 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.
1.17 schwarze 170: .Sh ENVIRONMENT
171: .Bl -tag -width LC_CTYPE
172: .It Ev LC_CTYPE
1.19 ! schwarze 173: The character encoding
1.17 schwarze 174: .Xr locale 1 .
1.19 ! schwarze 175: It decides which byte sequences form characters
! 176: and what their display width is.
1.17 schwarze 177: If unset or set to
178: .Qq C ,
179: .Qq POSIX ,
180: or an unsupported value, each byte is treated as a character of
181: display width 1.
182: .El
1.5 aaron 183: .Sh EXAMPLES
184: .Nm
1.1 deraadt 185: can be used as a filter to convert the stream output
186: of certain programs (e.g.,
1.16 schwarze 187: .Xr spell 1 ,
188: .Xr du 1 ,
189: .Xr file 1 ,
190: .Xr look 1 ,
191: .Xr nm 1 ,
192: .Xr who 1 ,
1.1 deraadt 193: and
1.5 aaron 194: .Xr wc 1 )
195: into a convenient
196: .Dq window
197: format, as in
198: .Bd -literal -offset indent
1.7 mpech 199: $ who | rs
1.5 aaron 200: .Ed
201: .Pp
1.1 deraadt 202: This function has been incorporated into the
1.5 aaron 203: .Xr ls 1
1.1 deraadt 204: program, though for most programs with similar output
1.5 aaron 205: .Nm
1.1 deraadt 206: suffices.
1.5 aaron 207: .Pp
1.1 deraadt 208: To convert stream input into vector output and back again, use
1.5 aaron 209: .Bd -literal -offset indent
1.7 mpech 210: $ rs 1 0 | rs 0 1
1.5 aaron 211: .Ed
212: .Pp
1.1 deraadt 213: A 10 by 10 array of random numbers from 1 to 100 and
214: its transpose can be generated with
1.5 aaron 215: .Bd -literal -offset indent
1.7 mpech 216: $ jot \-r 100 | rs 10 10 | tee array | rs \-T > tarray
1.5 aaron 217: .Ed
218: .Pp
1.1 deraadt 219: In the editor
1.5 aaron 220: .Xr vi 1 ,
1.1 deraadt 221: a file consisting of a multi-line vector with 9 elements per line
222: can undergo insertions and deletions,
223: and then be neatly reshaped into 9 columns with
1.5 aaron 224: .Bd -literal -offset indent
1.1 deraadt 225: :1,$!rs 0 9
1.5 aaron 226: .Ed
227: .Pp
1.1 deraadt 228: Finally, to sort a database by the first line of each 4-line field, try
1.5 aaron 229: .Bd -literal -offset indent
1.7 mpech 230: $ rs \-eC 0 4 | sort | rs \-c 0 1
1.5 aaron 231: .Ed
232: .Sh SEE ALSO
233: .Xr jot 1 ,
234: .Xr pr 1 ,
235: .Xr sort 1 ,
236: .Xr vi 1
1.18 schwarze 237: .Sh HISTORY
238: The
239: .Nm
240: utility first appeared in
241: .Bx 4.2 .
242: .Sh AUTHORS
243: .An John A. Kunze
1.5 aaron 244: .Sh BUGS
1.1 deraadt 245: Handles only two dimensional arrays.
1.5 aaron 246: .Pp
1.1 deraadt 247: The algorithm currently reads the whole file into memory,
248: so files that do not fit in memory will not be reshaped.
1.5 aaron 249: .Pp
1.1 deraadt 250: Fields cannot be defined yet on character positions.
1.5 aaron 251: .Pp
1.1 deraadt 252: Re-ordering of columns is not yet possible.
1.5 aaron 253: .Pp
1.1 deraadt 254: 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