ENUM(1)
=======
:man source:   enum {enumversion}
:man manual:   enum {enumversion}


NAME
----

enum - seq- and jot-like enumerator


SYNOPSIS
--------

GENERAL
~~~~~~~

*enum* [ 'OPTIONS' ]  'LEFT' *..* 'COUNT'*x* '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. "\n" 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. "\n" 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. "\n"
    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' *..* 'COUNT'*x* 'STEP' *..* 'RIGHT'

Four arguments are involved:

- 'LEFT', the value to start enumeration with
- 'COUNT', the (maximum) number of values to produce
- 'STEP', the gap from one value to another
- '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:

- *enum* 'LEFT' *..* 'COUNT'*x* 'STEP' *..* 'RIGHT'

With three arguments:

- *enum* 'LEFT' 'COUNT'*x* 'RIGHT'
- *enum* 'LEFT' *..* 'COUNT'*x* 'STEP' *..*
- *enum* *..* 'COUNT'*x* 'STEP' *..* 'RIGHT'
- *enum* 'LEFT' *..* 'COUNT'*x* *..* 'RIGHT'
- *enum* 'LEFT' *..* 'STEP' *..* 'RIGHT'
- *enum* 'LEFT' 'STEP' 'RIGHT' (for GNU seq compatibility)

With two arguments:

- *enum* *..* 'COUNT'*x* 'STEP' *..*
- *enum* *..* 'COUNT'*x* *..* 'RIGHT'
- *enum* 'COUNT'*x* *..* 'RIGHT'
- *enum* *..* 'STEP' *..* 'RIGHT'
- *enum* 'LEFT' *..* 'COUNT'*x* *..*
- *enum* 'LEFT' *..* 'STEP' *..*
- *enum* 'LEFT' *..* 'RIGHT'
- *enum* 'LEFT' 'RIGHT' (for GNU seq compatibility)

With one argument:

- *enum* *..* 'STEP' *..*
- *enum* *..* 'COUNT'*x* *..*
- *enum* *..* 'RIGHT'
- *enum* 'RIGHT' (for GNU seq compatibility)
- *enum* 'LEFT' *..*
- *enum* 'COUNT'*x*

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

Technically, more use cases are possible. For instance, 'COUNT'*x* '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:

- 'LEFT' defaults to 1 (unless 'STEP' and 'RIGHT' are specified, see
  *DERIVATION OF LEFT* below)
- 'COUNT' is infinity, unless it can be derived from the other three values.
- 'STEP' defaults to 1, unless it can be derived.
- '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:

- Produced values are random.
- Argument 'COUNT' defaults to 1 (one).
- Argument 'LEFT' (always!) defaults to 1 (one).
- 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:

- improved usability and
- 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

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

    0 1 2 3 4 5

- 100 integers from 0 to 99 on NetBSD, and

    0 1 2 [..] 97 98 99

- 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 "\n", in 'FORMAT':

--------------------------------------
# jot -w '%g\x41' 1
1\x41
--------------------------------------

*enum* is able to unescape "\x41" properly:

--------------------------------------
# enum -w '%g\x41' 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 "\n", in 'FORMAT':

--------------------------------------
# seq -f '%g\x41' 1
1\x41
--------------------------------------

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 '%g\x41' 3
1\x41
2\x41
3\x41
--------------------------------------

seq on FreeBSD and NetBSD:

--------------------------------------
# seq -f '%g\x41' 1
1A
2A
3A
--------------------------------------

seq on DragonFlyBSD:

--------------------------------------
# seq -f '%g\x41' 1
1A3
2A3
3A3
--------------------------------------

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

--------------------------------------
# enum -f '%g\x41' 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)