rr.1

.\" Copyright (c) 2019 Marc Espie <espie@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: August 25 2016 $
.Dt RR 1
.Os
.Sh NAME
.Nm rr
.Nd run commands with shuffled parameters
.Sh SYNOPSIS
.Nm
.Op Fl 1DdEeiNOpRrv
.Op Fl L Ar logfile
.Op Fl l Ar list
.Op Fl M Ar copies
.Op Fl m Ar margin
.Op Fl n Ar maxargs
.Op Fl o Ar regex
.Op Fl P Ar n
.Op Fl s Ar regex
.Op Fl x Ar regex
.Bk -words
.Ar cmd
.Op flags Fl -
.Ar param1 ...
.Ek
.Sh DESCRIPTION
.Nm
runs
.Ar cmd ,
keeping options in the same order up to the
.Ar --
marker, then shuffling all subsequent parameters
in a random order.
.Pp
The options are as follows:
.Bl -tag -width keyword123
.It Fl 1
Keep just one random parameter for running.
.It Fl D
Scan parameters and recursively add each leaf directory, e.g.,
each directory that does contain only files and not subdirectories.
.It Fl d
Without this flag,
.Ar --
on the command line will be propagated to each execution of
the command.
.It Fl E
Use extended regular expression syntax for
filtering
.Po Fl o ,
.Fl s
and
.Fl x Pc .
By default,
.Nm
will use basic regular expression syntax
.Po
see
.Xr regex 3
.Pc .
Note that this is a position-dependent option:
you can specify basic regular expressions
before
.Fl E ,
and extended regular expressions after.
.It Fl e
Exit on error after running command.
.It Fl i
Use case-insensitive regular expressions for filtering
.Po Fl o ,
.Fl s
and
.Fl x Pc .
Note that this is a position-dependent option:
You can specify case-sensitive regular expressions before
.Fl i ,
and case-insensitive after.
.It Fl L Ar logfile
Log every executed command to
.Ar logfile .
This can be useful for post-mortem retrieval of parameter order.
.It Fl l Ar list
Add the contents of file
.Ar list
to the parameters, each line being a single parameter.
As usual,
.Sq -
stands for standard input.
.It Fl M Ar copies
Copies the argument list
.Ar copies
time before randomizing anything, so each parameter will appear
several times.
.It Fl m Ar margin
If arguments run too long,
.Nm
will split the command into batches instead of running into the
kernel limit, allowing for
.Ar margin
bytes.
.It Fl N
Do not shuffle parameters.
.It Fl n Ar maxargs
Like
.Xr xargs 1 ,
split the command into batches of at most
.Ar maxargs
arguments.
Note that
.Ar maxargs
counts the full command line, so
.Bd -ragged -offset indent
.Nm Fl n Ns Ar 3 Ar feh Fl Z Fl - Ar *
.Ed
.Pp
will run each batch with exactly one random filename.
.It Fl O
Run the command exactly once.
.It Fl o Ar regex
Only keep parameters that match
.Ar regex .
.It Fl P Ar n
Rotate the arguments a given number of times
.Ar n
instead of
shuffling them.
.It Fl p
Do not run anything.
Consider the full argument list as parameters and randomize
them, then print the list, or parts of it according to
flags
.Fl 1On .
.It Fl R
Rotate the arguments instead of shuffling them.
.It Fl r
Scan parameters and recursively expand each directory.
.It Fl s Ar regex
Before shuffling parameters, skip until a parameter matching
.Ar regex .
Last match wins.
.It Fl v
Echo the command being run before running it.
.It Fl x Ar regex
Filter out parameters that match
.Ar regex .
.El
.Sh EXAMPLES
Run command with options on a random list of files:
.Bd -ragged -offset indent
.Nm Ar xv Fl maxpect Fl - Ar *.jpg
.Ed
.Pp
Select a specific number of files from a list and display
them, echo what's actually running:
.Bd -literal -offset indent
.Nm Fl Ov Fl n Ns Ar 5 Ar feh Fl Z Fl -bg-center Fl - Ar *
.Ed
.Pp
Play all mp4 videos under a specific folder in fullscreen,
limit to what
.Xr mpv 1
can manage, exit in case of error, do not randomize files:
.Bd -ragged -offset indent
.Nm Fl n Ns Ar 1500 Fl erN Fl o Ar '.*.mp4' Ar mpv Fl fs Fl - Ar videos
.Ed
.Pp
Display a random line from
.Ar file :
.Bd -ragged -offset indent
.Nm Fl n Ns Ar 2 Fl O Fl l Ar file Ar echo
.Ed
.Pp
Same thing, different options:
.Bd -ragged -offset indent
.Nm Fl 1pl Ar file
.Ed
.Sh AUTHORS
The
.Nm
utility was written by
.An Marc Espie Aq Mt espie@openbsd.org .