usr.bin/shuffle/shuffle.1

   1 .\"     $NetBSD: shuffle.1,v 1.8 2009/02/19 10:08:15 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1998
   4 .\"     Perry E. Metzger.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgment:
  16 .\"     This product includes software developed for the NetBSD Project
  17 .\"     by Perry E. Metzger.
  18 .\" 4. The name of the author may not be used to endorse or promote products
  19 .\"    derived from this software without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  22 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  23 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  24 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  26 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  30 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 .\"
  32 .\"
  33 .Dd February 18, 2009
  34 .Dt SHUFFLE 1
  35 .Os
  36 .Sh NAME
  37 .Nm shuffle
  38 .Nd print a random permutation of the command line arguments
  39 .Sh SYNOPSIS
  40 .Nm
  41 .Op Fl 0
  42 .Op Fl f Ar filename ...
  43 .Op Fl n Ar number
  44 .Op Fl p Ar number
  45 .Op Ar arg
  46 .Op Ar ...
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 program prints a random permutation (or
  51 .Dq shuffle )
  52 of its command line arguments.
  53 This can be useful in shell scripts for selecting a
  54 random order in which to do a set of tasks, view a set of files, etc.
  55 .Pp
  56 If the
  57 .Fl f
  58 option is given, the data is taken from that files' contents or if the
  59 filename is
  60 .Ar -
  61 .Dq stdin .
  62 .Pp
  63 If the
  64 .Fl n
  65 option is given, its argument is treated as a number, and the program
  66 prints a random permutation of the numbers greater than or equal to 0
  67 and less than the argument.
  68 .Pp
  69 If the
  70 .Fl p
  71 option is given, its argument is treated as a number, and the program
  72 prints that number of randomly selected lines or arguments in a random order.
  73 .Pp
  74 The
  75 .Fl 0
  76 option changes the field separator character from \en to \e0, so that
  77 the output is suitable to be sent to
  78 .Xr xargs 1
  79 (to handle filenames with whitespace in them).
  80 .Sh EXAMPLES
  81 .Bd -literal -offset indent
  82 $ shuffle a b c d
  83 c
  84 b
  85 d
  86 a
  87 $ shuffle -p 1 a b c d
  88 d
  89 $ shuffle -n 4 -p 2
  90 0
  91 3
  92 .Ed
  93 .Sh SEE ALSO
  94 .Xr jot 1 ,
  95 .Xr random 6
  96 .Sh HISTORY
  97 The
  98 .Nm
  99 program first appeared in
 100 .Nx 1.4 .
 101 .Sh AUTHORS
 102 Written by
 103 .An Perry E. Metzger
 104 .Aq perry@piermont.com .