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