1.\" Copyright (c) 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)rs.1 8.2 (Berkeley) 12/30/93 29.\" $FreeBSD: src/usr.bin/rs/rs.1,v 1.4.2.5 2002/06/21 15:28:55 charnier Exp $ 30.\" $DragonFly: src/usr.bin/rs/rs.1,v 1.3 2006/04/17 18:01:37 swildner Exp $ 31.\" 32.Dd December 30, 1993 33.Dt RS 1 34.Os 35.Sh NAME 36.Nm rs 37.Nd reshape a data array 38.Sh SYNOPSIS 39.Nm 40.Oo 41.Fl Oo Cm csCS Oc Ns Op Ar x 42.Oo Cm kKgGw Oc Ns Op Ar N 43.Cm tTeEnyjhHmz 44.Oc 45.Op Ar rows Op Ar cols 46.Sh DESCRIPTION 47The 48.Nm 49utility reads the standard input, interpreting each line as a row 50of blank-separated entries in an array, 51transforms the array according to the options, 52and writes it on the standard output. 53With no arguments it transforms stream input into a columnar 54format convenient for terminal viewing. 55.Pp 56The shape of the input array is deduced from the number of lines 57and the number of columns on the first line. 58If that shape is inconvenient, a more useful one might be 59obtained by skipping some of the input with the 60.Fl k 61option. 62Other options control interpretation of the input columns. 63.Pp 64The shape of the output array is influenced by the 65.Ar rows 66and 67.Ar cols 68specifications, which should be positive integers. 69If only one of them is a positive integer, 70.Nm 71computes a value for the other which will accommodate 72all of the data. 73When necessary, missing data are supplied in a manner 74specified by the options and surplus data are deleted. 75There are options to control presentation of the output columns, 76including transposition of the rows and columns. 77.Pp 78The following options are available: 79.Bl -tag -width indent 80.It Fl c Ns Ar x 81Input columns are delimited by the single character 82.Ar x . 83A missing 84.Ar x 85is taken to be `^I'. 86.It Fl s Ns Ar x 87Like 88.Fl c , 89but maximal strings of 90.Ar x 91are delimiters. 92.It Fl C Ns Ar x 93Output columns are delimited by the single character 94.Ar x . 95A missing 96.Ar x 97is taken to be `^I'. 98.It Fl S Ns Ar x 99Like 100.Fl C , 101but padded strings of 102.Ar x 103are delimiters. 104.It Fl t 105Fill in the rows of the output array using the columns of the 106input array, that is, transpose the input while honoring any 107.Ar rows 108and 109.Ar cols 110specifications. 111.It Fl T 112Print the pure transpose of the input, ignoring any 113.Ar rows 114or 115.Ar cols 116specification. 117.It Fl k Ns Ar N 118Ignore the first 119.Ar N 120lines of input. 121.It Fl K Ns Ar N 122Like 123.Fl k , 124but print the ignored lines. 125.It Fl g Ns Ar N 126The gutter width (inter-column space), normally 2, is taken to be 127.Ar N . 128.It Fl G Ns Ar N 129The gutter width has 130.Ar N 131percent of the maximum column width added to it. 132.It Fl e 133Consider each line of input as an array entry. 134.It Fl n 135On lines having fewer entries than the first line, 136use null entries to pad out the line. 137Normally, missing entries are taken from the next line of input. 138.It Fl y 139If there are too few entries to make up the output dimensions, 140pad the output by recycling the input from the beginning. 141Normally, the output is padded with blanks. 142.It Fl h 143Print the shape of the input array and do nothing else. 144The shape is just the number of lines and the number of 145entries on the first line. 146.It Fl H 147Like 148.Fl h , 149but also print the length of each line. 150.It Fl j 151Right adjust entries within columns. 152.It Fl w Ns Ar N 153The width of the display, normally 80, is taken to be the positive 154integer 155.Ar N . 156.It Fl m 157Do not trim excess delimiters from the ends of the output array. 158.It Fl z 159Adapt column widths to fit the largest entries appearing in them. 160.El 161.Pp 162With no arguments, 163.Nm 164transposes its input, and assumes one array entry per input line 165unless the first non-ignored line is longer than the display width. 166Option letters which take numerical arguments interpret a missing 167number as zero unless otherwise indicated. 168.Sh EXAMPLES 169The 170.Nm 171utility can be used as a filter to convert the stream output 172of certain programs (e.g., 173.Xr spell 1 , 174.Xr du 1 , 175.Xr file 1 , 176.Xr look 1 , 177.Xr nm 1 , 178.Xr who 1 , 179and 180.Xr wc 1 ) 181into a convenient ``window'' format, as in 182.Bd -literal -offset indent 183% who | rs 184.Ed 185.Pp 186This function has been incorporated into the 187.Xr ls 1 188program, though for most programs with similar output 189.Nm 190suffices. 191.Pp 192To convert stream input into vector output and back again, use 193.Bd -literal -offset indent 194% rs 1 0 | rs 0 1 195.Ed 196.Pp 197A 10 by 10 array of random numbers from 1 to 100 and 198its transpose can be generated with 199.Bd -literal -offset indent 200% jot \-r 100 | rs 10 10 | tee array | rs \-T > tarray 201.Ed 202.Pp 203In the editor 204.Xr vi 1 , 205a file consisting of a multi-line vector with 9 elements per line 206can undergo insertions and deletions, 207and then be neatly reshaped into 9 columns with 208.Bd -literal -offset indent 209:1,$!rs 0 9 210.Ed 211.Pp 212Finally, to sort a database by the first line of each 4-line field, try 213.Bd -literal -offset indent 214% rs \-eC 0 4 | sort | rs \-c 0 1 215.Ed 216.Sh SEE ALSO 217.Xr jot 1 , 218.Xr pr 1 , 219.Xr sort 1 , 220.Xr vi 1 221.Sh BUGS 222.Bl -item 223.It 224Handles only two dimensional arrays. 225.It 226The algorithm currently reads the whole file into memory, 227so files that do not fit in memory will not be reshaped. 228.It 229Fields cannot be defined yet on character positions. 230.It 231Re-ordering of columns is not yet possible. 232.It 233There are too many options. 234.El 235