PageRenderTime 20ms CodeModel.GetById 11ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 0ms

/usr.bin/rs/rs.1

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 245 lines | 245 code | 0 blank | 0 comment | 0 complexity | 93e795a35ef4de5f96aed6d030f49040 MD5 | raw file
  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