usr.bin/rs/rs.1

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