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