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