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