-.\" $OpenBSD: rs.1,v 1.4 1999/10/17 20:24:35 aaron Exp $
+.\" $OpenBSD: rs.1,v 1.5 2000/03/06 12:23:41 aaron Exp $
.\"
.\" Copyright (c) 1993
.\" The Regents of the University of California. All rights reserved.
.\" SUCH DAMAGE.
.\"
.\" @(#)rs.1 8.2 (Berkeley) 12/30/93
+.\" $FreeBSD: src/usr.bin/rs/rs.1,v 1.4 1999/08/28 01:05:21 peter Exp $
.\"
-.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
+.Dd December 30, 1993
+.Dt RS 1
+.Os
+.Sh NAME
+.Nm rs
+.Nd reshape a data array
+.Sh SYNOPSIS
+.Nm rs
+.Oo
+.Sm off
+.Xo Fl Oo Cm Op Cm csCS
+.Op Ar x
+.Op Cm kKgGw
+.Op Ar N
+.Cm tTeEnyjhHmz Oc
+.Xc
+.Oc
+.Sm on
+.Op Ar rows Op Ar cols
+.Sh DESCRIPTION
+.Nm
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
+.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.
+obtained by skipping some of the input with the
+.Fl k
+option.
Other options control interpretation of the input columns.
-.PP
+.Pp
The shape of the output array is influenced by the
-.I rows
+.Ar rows
and
-.I cols
+.Ar cols
specifications, which should be positive integers.
If only one of them is a positive integer,
-.I rs
+.Nm
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
+.Pp
The options are as follows:
-.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
+.Bl -tag -width indent
+.It Fl c Ns Ar x
+Input columns are delimited by the single character
+.Ar x .
+A missing
+.Ar x
+is taken to be
+.Ql ^I .
+.It Fl s Ns Ar x
+Like
+.Fl c ,
+but maximal strings of
+.Ar x
+are delimiters.
+.It Fl C Ns Ar x
+Output columns are delimited by the single character
+.Ar x .
+A missing
+.Ar x
+is taken to be
+.Ql ^I .
+.It Fl S Ns Ar x
+Like
+.Fl C ,
+but padded strings of
+.Ar x
+are delimiters.
+.It Fl t
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
+.Ar rows
and
-.I cols
+.Ar cols
specifications.
-.IP \fB\-T\fR
+.It Fl T
Print the pure transpose of the input, ignoring any
-.I rows
+.Ar rows
or
-.I cols
+.Ar 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
+.It Fl k Ns Ar N
+Ignore the first
+.Ar N
+lines of input.
+.It Fl K Ns Ar N
+Like
+.Fl k ,
+but print the ignored lines.
+.It Fl g Ns Ar N
+The gutter width (inter-column space), normally 2, is taken to be
+.Ar N .
+.It Fl G Ns Ar N
+The gutter width has
+.Ar N
+percent of the maximum column width added to it.
+.It Fl e
Consider each line of input as an array entry.
-.IP \fB\-n\fR
+.It Fl E
+Consider each character of input as an array entry.
+.It Fl n
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
+.It Fl y
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
+.It Fl h
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
+.It Fl H
+Like
+.Fl h ,
+but also print the length of each line.
+.It Fl j
Right adjust entries within columns.
-.IP \fB\-w\fRN
+.It Fl w Ns Ar N
The width of the display, normally 80, is taken to be the positive
-integer \fIN\fP.
-.IP \fB\-m\fR
+integer
+.Ar N .
+.It Fl m
Do not trim excess delimiters from the ends of the output array.
-.IP \fB\-z\fR
+.It Fl z
Adapt column widths to fit the largest entries appearing in them.
-.PP
+.El
+.Pp
With no arguments,
-.I rs
+.Nm
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
+.Sh EXAMPLES
+.Nm
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 ,
+.Xr spell ,
+.Xr du ,
+.Xr file ,
+.Xr look ,
+.Xr nm ,
+.Xr who ,
and
-.IR wc (1))
-into a convenient ``window'' format, as in
-.IC
-who | rs
-.NC
+.Xr wc 1 )
+into a convenient
+.Dq window
+format, as in
+.Bd -literal -offset indent
+% who | rs
+.Ed
+.Pp
This function has been incorporated into the
-.IR ls (1)
+.Xr ls 1
program, though for most programs with similar output
-.I rs
+.Nm
suffices.
-.PP
+.Pp
To convert stream input into vector output and back again, use
-.IC
-rs 1 0 | rs 0 1
-.NC
+.Bd -literal -offset indent
+% rs 1 0 | rs 0 1
+.Ed
+.Pp
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
+.Bd -literal -offset indent
+% jot \-r 100 | rs 10 10 | tee array | rs \-T > tarray
+.Ed
+.Pp
In the editor
-.IR vi (1),
+.Xr 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
+.Bd -literal -offset indent
:1,$!rs 0 9
-.NC
+.Ed
+.Pp
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
+.Bd -literal -offset indent
+% rs \-eC 0 4 | sort | rs \-c 0 1
+.Ed
+.Sh SEE ALSO
+.Xr jot 1 ,
+.Xr pr 1 ,
+.Xr sort 1 ,
+.Xr vi 1
+.Sh BUGS
Handles only two dimensional arrays.
-
+.Pp
The algorithm currently reads the whole file into memory,
so files that do not fit in memory will not be reshaped.
-
+.Pp
Fields cannot be defined yet on character positions.
-
+.Pp
Re-ordering of columns is not yet possible.
-
+.Pp
There are too many options.
projects / openbsd / commitdiff