.\" Copyright (C) 2002 Arthur de Jong
.\"
.\" rl is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; see the file COPYING.  If not, write to
.\" the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
.\"
.TH "RL" "1" "October 2002" "" "User Commands"

.SH NAME
rl \- Randomize Lines.

.SH SYNOPSIS
.B rl
.RI [ OPTION ]...
.RI [ FILE ]...

.SH DESCRIPTION
\fBrl\fP reads lines from a input file or stdin, randomizes the lines and outputs a specified number of lines.
It does this with only a single pass over the input while trying to use as little memory as possible.

.TP
.B \-c, \-\-count=N
Select the number of lines to be returned in the output.
If this argument is omited all the lines in the file will be returned in random order.
If the input contains less lines than specified and the \-\-reselect option below is not specified a warning is printed and all lines are returned in random order. 

.TP
.B \-r, \-\-reselect
When using this option a single line may be selected multiple times.
The default behaviour is that any input line will only be selected once.
This option makes it possible to specify a \-\-count option with more lines than the file actually holds.

.TP
.B \-o, \-\-output=FILE
Send randomized lines to FILE instead of stdout.

.TP
.B \-d, \-\-delimiter=DELIM
Use specified character as a "line" delimiter instead of the newline character.

.TP
.B \-0, \-\-null
Input lines are terminated by a null character.
This option is useful to process the output of the GNU find \-print0 option.

.TP
.B \-q, \-\-quiet, \-\-silent
Be quiet about any errors or warnings.

.TP
.B \-h, \-\-help
Show short summary of options.

.TP
.B \-v, \-\-version
Show version of program.

.SH "EXAMPLES"
Some simple demonstrations of how rl can help you do everyday tasks.
Warning: some of these examples may affect the operation of your system.

Play a random sound after 4 minutes (perfect for toast):
.ft B
    sleep 240 ; play `find /sounds \-name '*.au' \-print | rl \-\-count=1`
.ft R

Renice all the processes of a random logged\-in user:
.ft B
    renice +5 \-u `who | cut '\-d ' \-f 1 | sort \-u | rl \-\-count=1`
.ft R

Kill a random process on your computer.
.ft B
    kill \-9 `ps \-A | awk '{print $1}' | rl \-\-count=1`
.ft R
.br
Do this as root and see how long your system keeps working.
Increase the \-\-count for extra effect.
(you may need to change the ps and awk parameters depending on your system)

Find all movies and play them in random order.
.ft B
    find . \-name '*.avi' \-print0 | rl \-0 | xargs \-n 1 \-0 mplayer
.ft R
.br
Because \-0 is used filenames with spaces (even newlines and other unusual characters) in them work.

.SH COPYRIGHT
Copyright \(co 2002 Arthur de Jong <arthur@tiefighter.et.tudelft.nl>.
.br
This is free software; see the license for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.