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