BSD 4.4 Lite Usr.bin Sources

1 files changed, 197 insertions, 0 deletions

diff --git a/usr.bin/rs/rs.1 b/usr.bin/rs/rs.1
new file mode 100644
index 0000000..07de48c
--- /dev/null
+++ b/usr.bin/rs/rs.1
@@ -0,0 +1,197 @@
+.\" Copyright (c) 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by the University of
+.\"	California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"	@(#)rs.1	8.2 (Berkeley) 12/30/93
+.\"
+.TH RS 1 "December 30, 1993"
+.UC 4
+.SH NAME
+rs \- reshape a data array
+.SH SYNOPSIS
+\fBrs [ \-[csCS][\fRx\fB][kKgGw][\fRN\fB]tTeEnyjhHm ] [ \fRrows\fB [ \fRcols\fB ] ]\fR
+.SH DESCRIPTION
+.I Rs
+reads the standard input, interpreting each line as a row
+of blank-separated entries in an array,
+transforms the array according to the options,
+and writes it on the standard output.
+With no arguments it transforms stream input into a columnar
+format convenient for terminal viewing.
+.PP
+The shape of the input array is deduced from the number of lines
+and the number of columns on the first line.
+If that shape is inconvenient, a more useful one might be
+obtained by skipping some of the input with the \fB\-k\fP option.
+Other options control interpretation of the input columns.
+.PP
+The shape of the output array is influenced by the
+.I rows
+and
+.I cols
+specifications, which should be positive integers.
+If only one of them is a positive integer,
+.I rs
+computes a value for the other which will accommodate
+all of the data.
+When necessary, missing data are supplied in a manner
+specified by the options and surplus data are deleted.
+There are options to control presentation of the output columns,
+including transposition of the rows and columns.
+.PP
+The options are described below.
+.IP \fB\-c\fRx
+Input columns are delimited by the single character \fIx\fP.
+A missing \fIx\fP is taken to be `^I'.
+.IP \fB\-s\fRx
+Like \fB\-c\fR, but maximal strings of \fIx\fP are delimiters.
+.IP \fB\-C\fRx
+Output columns are delimited by the single character \fIx\fP.
+A missing \fIx\fP is taken to be `^I'.
+.IP \fB\-S\fRx
+Like \fB\-C\fR, but padded strings of \fIx\fP are delimiters.
+.IP \fB\-t\fR
+Fill in the rows of the output array using the columns of the
+input array, that is, transpose the input while honoring any
+.I rows
+and
+.I cols
+specifications.
+.IP \fB\-T\fR
+Print the pure transpose of the input, ignoring any
+.I rows
+or
+.I cols
+specification.
+.IP \fB\-k\fRN
+Ignore the first \fIN\fR lines of input.
+.IP \fB\-K\fRN
+Like \fB\-k\fR, but print the ignored lines.
+.IP \fB\-g\fRN
+The gutter width (inter-column space), normally 2, is taken to be \fIN\fR.
+.IP \fB\-G\fRN
+The gutter width has \fIN\fR percent of the maximum
+column width added to it.
+.IP \fB\-e\fR
+Consider each line of input as an array entry.
+.IP \fB\-n\fR
+On lines having fewer entries than the first line,
+use null entries to pad out the line.
+Normally, missing entries are taken from the next line of input.
+.IP \fB\-y\fR
+If there are too few entries to make up the output dimensions,
+pad the output by recycling the input from the beginning.
+Normally, the output is padded with blanks.
+.IP \fB\-h\fR
+Print the shape of the input array and do nothing else.
+The shape is just the number of lines and the number of
+entries on the first line.
+.IP \fB\-H\fR
+Like \fB\-h\fR, but also print the length of each line.
+.IP \fB\-j\fR
+Right adjust entries within columns.
+.IP \fB\-w\fRN
+The width of the display, normally 80, is taken to be the positive
+integer \fIN\fP.
+.IP \fB\-m\fR
+Do not trim excess delimiters from the ends of the output array.
+.PP
+With no arguments,
+.I rs
+transposes its input, and assumes one array entry per input line
+unless the first non-ignored line is longer than the display width.
+Option letters which take numerical arguments interpret a missing
+number as zero unless otherwise indicated.
+.SH EXAMPLES
+.de IC
+.IP
+.ss 36
+.ft B
+..
+.de NC
+.br
+.ss 12
+.PP
+..
+.I Rs
+can be used as a filter to convert the stream output
+of certain programs (e.g.,
+.IR spell ,
+.IR du ,
+.IR file ,
+.IR look ,
+.IR nm ,
+.IR who ,
+and
+.IR wc (1))
+into a convenient ``window'' format, as in
+.IC
+who | rs
+.NC
+This function has been incorporated into the
+.IR ls (1)
+program, though for most programs with similar output
+.I rs
+suffices.
+.PP
+To convert stream input into vector output and back again, use
+.IC
+rs 1 0 | rs 0 1
+.NC
+A 10 by 10 array of random numbers from 1 to 100 and
+its transpose can be generated with
+.IC
+jot \-r 100 | rs 10 10 | tee array | rs \-T > tarray
+.NC
+In the editor
+.IR vi (1),
+a file consisting of a multi-line vector with 9 elements per line
+can undergo insertions and deletions,
+and then be neatly reshaped into 9 columns with
+.IC
+:1,$!rs 0 9
+.NC
+Finally, to sort a database by the first line of each 4-line field, try
+.IC
+rs \-eC 0 4 | sort | rs \-c 0 1
+.NC
+.SH SEE ALSO
+jot(1), vi(1), sort(1), pr(1)
+.SH BUGS
+Handles only two dimensional arrays.
+
+The algorithm currently reads the whole file into memory,
+so files that do not fit in memory will not be reshaped.
+
+Fields cannot be defined yet on character positions.
+
+Re-ordering of columns is not yet possible.
+
+There are too many options.