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