.\" rand.1 man page for rand
.\" http://math.smsu.edu/~erik/software.php?id=7
.\" $Id: rand.1,v 1.2 2004/06/05 20:01:01 erik Exp $
.\"===========================================================================
.Dd December 11, 1998
.Dt RAND 1
.\"===========================================================================
.Sh NAME
.Nm rand
.Nd randomize the order of a stream
.\"===========================================================================
.Sh SYNOPSIS
.Nm
.Op Fl lwvh
.Op Fl f Cm
.Op Fl -help
.Op Fl -version
.\"===========================================================================
.Sh DESCRIPTION
.Nm
has 2 major modes of operation. The first is as a pipe. The second is to act
on a specified file. There are 2 minor modes of operation, the data can be
randomized by line or word.
.Pp
As a pipe,
.Nm
collects the stream until it terminates, then displays the randomized results
of this completed stream. If the stream is the result of several operations,
then the stream as a whole is randomized.
.Pp
When operating on a file,
.Nm
will read the input from a single given file, and display the results to stdout.
.Pp
The two command line parameters control if the randomization is per line or word. The default behavior is to randomize by line.
.Nm
.B -w
will randomize by word, and return one word on every line. A word in this sense
is any string delimited by a whitespace. Tabs, spaces, and newlines are ignored.
.Pp
.\"===========================================================================
.Sh OPTIONS
.Bl -tag -width
.It Op Fl l
Line shuffle
.It Op Fl w
Word shuffle
.It Op Fl w
Character shuffle
.It Op Fl v, -version
Show version and exit.
.It Op Fl h, -help
Show help and exit.
.It Op Fl f Cm
Read from instead of stdin.
.It Op Fl Cm
Write to instead of stdout.
.El
.\"===========================================================================
.Sh EXAMPLES
play `find -name *.wav |
.Nm
`
.br
.Nm
-w -f COPYING -o whatever
.br
.Nm
-l -f history.test -o test.1
.br
/bin/ls |
.Nm
-w
.\"===========================================================================
.Sh DIAGNOSTICS
.Nm
returns EXIT_SUCCESS on success or EXIT_FAILURE on failure. The only cases
where EXIT_FAILURE may be returned are
.Bl -bullet
.It
\-f file can not be read.
.It
\-o file cannot be written to.
.It
An unknown option is presented (in which case, usage is also printed)
.El
.\"===========================================================================
.Sh SEE ALSO
.Xr sort 1 ,
.Xr rand 3
.\"===========================================================================
.Sh HISTORY
.Nm
was created in October of 1998 when
.An Erik Greenwald
got tired of hacking things to shuffle stuff.
.\"===========================================================================
.Sh BUGS
.Nm
has no known bugs. Please report any to
.An
.\"===========================================================================
.Sh AUTHOR
.An Erik Greenwald