ENUM(1) 							     enum 1.1								   ENUM(1)

NAME

       enum - seq- and jot-like enumerator

SYNOPSIS

   GENERAL
       enum [ OPTIONS ] LEFT .. COUNTx STEP .. RIGHT

   SHORTCUTS
       enum [ OPTIONS ] LEFT STEP RIGHT

       enum [ OPTIONS ] LEFT RIGHT

       enum [ OPTIONS ] RIGHT

       ...

DESCRIPTION

       enum enumerates values (numbers) from LEFT to RIGHT adding/subtracting STEP each time. If STEP is not provided a value is implied. No more
       than COUNT values are printed. Before printing, values are passed through a formatter. Please see OPTIONS for details on controlling the
       formatter or EXAMPLES for use cases.

       Further enum usage details are covered in USAGE IN DETAIL.

EXAMPLES

   USE IN FOR-LOOPS
	   for i in $(enum -e 1 20); do
	       touch file_${i}
	   done

   USE FOR RANDOM NUMBERS
	   number=$(enum --random 3 .. 10)

       instead of native Bash like

	   f() { min=$1; max=$2; echo $((RANDOM * (max - min + 1) / 32767 + min)); }
	   number=$(f 3 10)

   SHOWING AN ASCII TABLE
	   enum -f '[%3i] "%c"' 0 127

OPTIONS

   RANDOM MODE
       -r, --random
	   Produces random numbers (potentially with duplicates) instead of monotonic sequences.

       -i, --seed=NUMBER
	   Pass NUMBER as initializer to the random number generator. By default, the RNG is initialized from the current time and the process ID
	   of the running instance of enum.

   FORMATTING
       -b, --dumb=TEXT
	   Overrides the output format to TEXT without interpolating placeholders. For instance, enum -b "foo % 10" 3x produces the string "foo %
	   10" three times.

       -c, --characters
	   Overrides the output format to %c producing characters. For example, enum -c 65 67 produces the letters "A", "B" and "C".

       -e, --equal-width
	   Equalize width by padding with leading zeroes. NOTE: In the case of mixed negative and non-negative numbers (e.g. with enum -e -- -10
	   1), non-negative values will compensate for the lack of a leading minus with an extra zero to be of equal width.

       -f, --format=FORMAT
	   Overrides the default output format with FORMAT. For details on allowed formats please see printf(3).

	   FORMAT is subject to processing of C escape sequences (e.g. "
" makes a newline). If FORMAT does not contain any placeholders, enum
	   will print FORMAT repeatedly. In contrast, jot would have appended the number's value instead. To make numbers appear at the end with
	   enum, adjust FORMAT appropriately.

       -l, --line
	   Shortcut for "-s ' '" which means having a space instead of a newline as separator.

       -n, --omit-newline
	   Omits the terminating string (defaults to newline) from output, i.e. it's a shortcut to "-t ''".

       -p, --precision=COUNT
	   Overrides automatic selection of precision to print COUNT decimal places, e.g. "0.100" for COUNT = 3. By default, the number of digits
	   to print is computed from the arguments given and the (given or computed) step size.

       -s, --separator=TEXT
	   Overrides the separator that is printed between values. By default, values are separated by a newline.  TEXT is subject to processing
	   of C escape sequences (e.g. "
" makes a newline).

       -t, --terminator=TEXT
	   Overrides the terminator that is printed in the very end. Default is a newline.  TEXT is subject to processing of C escape sequences
	   (e.g. "
" makes a newline).

       -w, --word=FORMAT
	   Alias for --format, for compatibility with jot. For GNU seq's -w meaning --equal-width, see -e.

       -z, --zero, --null
	   Print null bytes as separator, not a newline.

   OTHER
       -h, --help
	   Outputs usage information and exits with code 0 (success).

       -V, --version
	   Displays version information and exits with code 0 (success).

USAGE IN DETAIL

   ARGUMENTS
       The logic of enum's command line parameters is:

       enum [ OPTIONS ] LEFT .. COUNTx STEP .. RIGHT

       Four arguments are involved:

       o    LEFT, the value to start enumeration with

       o    COUNT, the (maximum) number of values to produce

       o    STEP, the gap from one value to another

       o    RIGHT, the value to stop enumeration at (in some cases before)

       Not all four arguments are needed, though specifying all four is possible. For a list of all valid combinations see VALID COMBINATIONS
       below. Details on derivation of defaults are addressed in DERIVATION OF DEFAULTS.

   VALID COMBINATIONS
       With four arguments:

       o    enum LEFT ..  COUNTx STEP ..  RIGHT

       With three arguments:

       o    enum LEFT COUNTx RIGHT

       o    enum LEFT ..  COUNTx STEP ..

       o    enum ..  COUNTx STEP ..  RIGHT

       o    enum LEFT ..  COUNTx ..  RIGHT

       o    enum LEFT ..  STEP ..  RIGHT

       o    enum LEFT STEP RIGHT (for GNU seq compatibility)

       With two arguments:

       o    enum ..  COUNTx STEP ..

       o    enum ..  COUNTx ..	RIGHT

       o    enum COUNTx ..  RIGHT

       o    enum ..  STEP ..  RIGHT

       o    enum LEFT ..  COUNTx ..

       o    enum LEFT ..  STEP ..

       o    enum LEFT ..  RIGHT

       o    enum LEFT RIGHT (for GNU seq compatibility)

       With one argument:

       o    enum ..  STEP ..

       o    enum ..  COUNTx ..

       o    enum ..  RIGHT

       o    enum RIGHT (for GNU seq compatibility)

       o    enum LEFT ..

       o    enum COUNTx

       With less than three arguments, defaults apply. Details are described in DERIVATION OF DEFAULTS below.

       Technically, more use cases are possible. For instance, COUNTx STEP .. RIGHT is unambiguous since the order of arguments is fixed. Yet,
       "enum 3x 4 .. 10" reads a lot like "3 values between 4 and 10" while it actually would mean "3 values up to 10 in steps of 4". In order to
       keep enum's user interface as intuitive as possible, cases which could lead to misunderstandings are not implemented.

   DERIVATION OF DEFAULTS
       AUTO-SELECTION OF PRECISION
	   enum distinguishes between "2", "2.0", "2.00" and so on:

	       # enum 1 2
	       1
	       2

	       # enum 1 2.0
	       1.0
	       1.1
	       [..]
	       1.9
	       2.0

	   Also, if the derived step has more decimal places than the specified values for LEFT and RIGHT, the output precision will be raised to
	   that of the step value:

	       # enum 1 .. 3x .. 2
	       1.0
	       1.5
	       2.0

	   A specified precision always takes precedence, though:

	       # enum -p 2 1 .. 3x .. 2
	       1.00
	       1.50
	       2.00

       ARGUMENT DEFAULTS
	   In general, three arguments are needed; any three imply the fourth. This equation brings them together:

	   LEFT + (COUNT - 1) * STEP = RIGHT

	   If you specify less than three of them (see VALID COMBINATIONS), the unspecified ones are derived or set to their defaults:

	   o	LEFT defaults to 1 (unless STEP and RIGHT are specified, see DERIVATION OF LEFT below)

	   o	COUNT is infinity, unless it can be derived from the other three values.

	   o	STEP defaults to 1, unless it can be derived.

	   o	RIGHT is +/-infinity, unless it can be derived from the other three values.

	   Obviously, if COUNT is set to zero (0x), enum will output nothing, regardless of the other arguments.

       DERIVATION OF LEFT
	   In general, LEFT defaults to 1:

	       # enum .. 3
	       1
	       2
	       3

	   If STEP and RIGHT is given, it is derived as

	   LEFT = RIGHT - STEP * floor(RIGHT / STEP)

	       # enum .. 4 .. 10
	       2
	       6
	       10

	   If, in addition to STEP and RIGHT, COUNT is given, it is derived as:

	   LEFT = RIGHT - (COUNT - 1) * STEP

	       # enum .. 2x 4 .. 10
	       6
	       10

   GENERATION OF VALUES
       When a custom step is requested, values are produced as follows:

	   value[0] = LEFT + 0 * STEP
	   value[1] = LEFT + 1 * STEP
	   ..
	   value[i] = LEFT + i * STEP

       Otherwise, to avoid imprecision adding up, values are produced as follows:

	   value[0] = LEFT + (RIGHT - LEFT) / (COUNT - 1) * 0
	   value[1] = LEFT + (RIGHT - LEFT) / (COUNT - 1) * 1
	   ..
	   value[i] = LEFT + (RIGHT - LEFT) / (COUNT - 1) * i

       Production stops when either COUNT values have been produced or RIGHT has been reached, whichever hits first. When all four values are
       given in perfect match they hit at the same time.

RANDOM MODE

       Basically, random mode differs in these regards:

       o   Produced values are random.

       o   Argument COUNT defaults to 1 (one).

       o   Argument LEFT (always!) defaults to 1 (one).

       o   Argument RIGHT is required: Random does not mix with infinity.

       This section covers these differences in detail.

   COUNT DEFAULTS TO 1 (ONE)
       In random mode only one value is produced, by default:

	   # enum 1 4
	   1
	   2
	   3
	   4

	   # enum -r 1 4
	   3

       By specifying COUNT you can produce more values at a time:

	   # enum -r 1 .. 3x .. 4
	   2
	   1
	   3

   LEFT ALWAYS DEFAULTS TO 1 (ONE)
       When you need increasing numbers up to a certain maximum (say 10), each separated by a certain step (say 4) you can let enum calculate the
       needed starting value for you:

	   # enum .. 4 .. 10
	   2
	   6
	   10

       In random mode LEFT is never calculated and defaults to 1 (one):

	   # enum -r .. 5x 4 .. 10
	   1
	   1
	   9
	   1
	   5

   RANDOM DOES NOT MIX WITH INFINITY
       In general, enum supports running towards infinity:

	   # enum 1 .. 2.0 ..
	   1.0
	   3.0
	   5.0
	   [..]

       However, in random mode enum would now produce random numbers from 1 to infinity (or a big number like FLT_MAX from <float.h>), which we
       have decided against.

HISTORY

       enum is a fusion of GNU seq and jot, feature-wise. At the core both tools print sequences of numbers. GNU seq has a clean interface but
       very limited functionality. jot on the other hand offers more advanced features, like producing random numbers, at the cost of a rather
       unfriendly interface.

       With enum we try to offer a tool with the power of jot and a usable, easily memorable interface. enum is licensed under a BSD license and
       written in C89 for maximum portability.

       The following sections take a look at the differences in detail.

COMPARISON TO JOT

       Using enum instead of jot offers two main advantages:

       o   improved usability and

       o   uniform behavior across distributions and operating systems.

       As of 2010-10-03, jot implementations still differ subtly between DragonFlyBSD, FreeBSD, MirOS BSD, NetBSD, OpenBSD, and OS X. For instance
       the command jot - 0 5 produces

       o   6 integers from 0 to 5 on FreeBSD and OS X,

	       0 1 2 3 4 5

       o   100 integers from 0 to 99 on NetBSD, and

	       0 1 2 [..] 97 98 99

       o   100 integers from 0 to 5 (with consecutive duplicates) on DragonFlyBSD, MirOS BSD, and OpenBSD.

	       0 0 0 0 0 0 0 0 0 0 1 1 [..] 4 4 5 5 5 5 5 5 5 5 5 5

       Basically, the full feature set of jot plus a few enhancements is contained in enum. Names of parameters have been retained for increased
       compatibility, e.g. -p 2 works with enum as it does with jot:

	   # jot -p 2 3
	   1.00
	   2.00
	   3.00

	   # enum -p 2 3
	   1.00
	   2.00
	   3.00

       Please see OPTIONS above for further details.

   ADDITIONAL FEATURES
       The extra features that enum offers over jot include:

       MORE MEMORABLE COMMAND LINE USAGE
	   In order to produce 3 random numbers between 1 and 10 (inclusively), you would run

	       jot -r 3 1 10

	   with jot. We find these alternative calls to enum more intuitive:

	       enum -r 1 .. 3x .. 10
	       enum -r 1 3x 10

       CUSTOM RESOLUTION OF RANDOM
	   With enum you can specify that the possible values to be randomly selected from have a particular spacing. These two cases illustrate
	   the difference between a gap of 2 and 3:

	       # enum -r 4 .. 100x 2 .. 10 | sort -u -n
	       4
	       6
	       8
	       10

	       # enum -r 4 .. 100x 3 .. 10 | sort -u -n
	       4
	       7
	       10

       SUPPORT FOR SEVERAL PLACEHOLDERS IN FORMAT STRINGS
	   jot on DragonFlyBSD, FreeBSD, MirOS BSD, OpenBSD, and OS X:

	       # jot -w %g%g 3
	       jot: too many conversions

	   jot on NetBSD:

	       # jot -w %g%g 3
	       jot: unknown or invalid format `%g%g'

	   enum on any platform:

	       # enum -f %g%g 3
	       11
	       22
	       33

       SUPPORT FOR ESCAPE SEQUENCES
	   None of the jot implementations we tested (DragonFlyBSD, FreeBSD, MirOS BSD, NetBSD, OpenBSD, and OS X) supports escape sequences, say
	   "
", in FORMAT:

	       # jot -w '%gx41' 1
	       1x41

	   enum is able to unescape "x41" properly:

	       # enum -w '%gx41' 1
	       1A

	   On a side note, "x25" produces a literal "%"; it does not make a placeholder:

	       # enum -w '%g x25g' 1
	       1 %g

       NULL BYTES AS SEPARATOR
	   When using format strings containing spaces, you may run into trouble in contexts like for loops or xargs: spaces are treated as
	   separators which breaks up your strings in pieces:

	       # enum -f 'sheep number %d' 2 | xargs -n 1 echo
	       sheep
	       number
	       1
	       sheep
	       number
	       2

	   To prevent this, you could pass --null to both enum and xargs:

	       # enum --null -f 'sheep number %d' 2 | xargs --null -n 1 echo
	       sheep number 1
	       sheep number 2

   DIFFERENCES
       HANDLING OF FORMATS WITHOUT PLACEHOLDERS
	   In contrast to jot, enum does not append the current value if the formatting string does not contain a placeholder. Behavior of jot:

	       # jot 3 -w test_
	       test_1
	       test_2
	       test_3

	   Behavior of enum:

	       # enum -w test_ 3
	       test_
	       test_
	       test_

	   In order to achieve jot's output with enum, you should manually append a placeholder:

	       # enum -w test_%d 3
	       test_1
	       test_2
	       test_3

       NON-NUMBER VALUES FOR LEFT AND RIGHT
	   enum does not support using ASCII characters instead of their numerical values (e.g. "A" for 65) for LEFT and RIGHT. With jot you can
	   do:

	       # jot 3 A
	       65
	       66
	       67

	   Inconsistently,

	       # jot 3 0
	       0
	       1
	       2

	   jot does not interpret "0" as the ASCII character with code 48. We have no intention of duplicating this mix, at the moment.

COMPARISON TO GNU SEQ

       Basically, enum's usage is backwards-compatible to that of GNU seq.

   ADDITIONAL FEATURES
       The extra features enum offers over GNU seq include:

       RANDOM NUMBER MODE
	   enum supports output of constrained random numbers, e.g.

	       enum -r 4 .. 3x 2.0 .. 11

	   produces three (possibly duplicate) random numbers from the set {4.0, 6.0, 8.0, 10.0}.

       SUPPORT FOR INVERSE ORDERING
	   In contrast to GNU seq, enum supports enumerating decreasing values:

	       # seq 3 1

	       # enum 3 1
	       3
	       2
	       1

       SUPPORT FOR SEVERAL PLACEHOLDERS IN FORMAT STRINGS
	       # seq -f %g%g 3
	       seq: format `%g%g' has too many % directives

	       # enum -f %g%g 3
	       11
	       22
	       33

       SUPPORT FOR ESCAPE SEQUENCES
	   GNU seq does not support escape sequences, say "
", in FORMAT:

	       # seq -f '%gx41' 1
	       1x41

	   In contrast, some of the other seq implementations around do. These three behaviours can be observed (as of 2010-10-25):

	   seq of Plan 9, 9base, and GNU seq:

	       # seq -f '%gx41' 3
	       1x41
	       2x41
	       3x41

	   seq on FreeBSD and NetBSD:

	       # seq -f '%gx41' 1
	       1A
	       2A
	       3A

	   seq on DragonFlyBSD:

	       # seq -f '%gx41' 1
	       1A3
	       2A3
	       3A3

	   enum unescape "x41" to "A" as well:

	       # enum -f '%gx41' 3
	       1A
	       2A
	       3A

	   On a side note, "x25" produces a literal "%"; it does not make a placeholder:

	       # enum -f '%g x25g' 1
	       1 %g

       OMITTING FINAL NEWLINE
	   By specifying -n as a parameter, you can make enum omit the trailing newline.

   DIFFERENCES
       GNU seq's --equal-width shortcut -w conflicts with jot's -w word. We chose to make -e the shortcut for --equal-width in enum, instead.

       Also, while GNU seq is licensed under GPL v3 or later, enum is licensed under the New BSD license.

THANKS

       Elias Pipping, Andreas Gunschl, Justin B. Rye, David Prevot, Kamil Dudka, Michael Bienia

AUTHORS

       Jan Hauke Rahm <jhr@debian.org>

       Sebastian Pipping <sping@gentoo.org>

RESOURCES

       Main web site: https://fedorahosted.org/enum/

       Gitweb: http://git.fedorahosted.org/git/?p=enum.git

SEE ALSO

       jot(1), seq(1), printf(3)

enum 1.1							    02/02/2012								   ENUM(1)