Annotation of src/usr.bin/rs/rs.1, Revision 1.5
1.5 ! aaron 1: .\" $OpenBSD: rs.1,v 1.4 1999/10/17 20:24:35 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.5 ! aaron 88: .Bl -tag -width indent
! 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