enum - seq- and jot-like enumerator

       Jan Hauke Rahm <jhr@debian.org>

       Sebastian Pipping <sping@gentoo.org>

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

   ADDITIONALFEATURES
       The extra features enum offers over GNU seq include:

       RANDOMNUMBERMODEenum 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}.

       SUPPORTFORINVERSEORDERING

           In contrast to GNU seq, enum supports enumerating decreasing values:

               # seq 3 1

               # enum 3 1
               3
               2
               1

       SUPPORTFORSEVERALPLACEHOLDERSINFORMATSTRINGS

               # seq -f %g%g 3
               seq: format `%g%g' has too many % directives

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

       SUPPORTFORESCAPESEQUENCES

           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

       OMITTINGFINALNEWLINE

           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 -wword. 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.

       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-05 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. -p2 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.

   ADDITIONALFEATURES
       The extra features that enum offers over jot include:

       MOREMEMORABLECOMMANDLINEUSAGE

           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

       CUSTOMRESOLUTIONOFRANDOM

           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

       SUPPORTFORSEVERALPLACEHOLDERSINFORMATSTRINGS

           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

       SUPPORTFORESCAPESEQUENCES

           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

       NULLBYTESASSEPARATOR

           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

   DIFFERENCESHANDLINGOFFORMATSWITHOUTPLACEHOLDERS

           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-NUMBERVALUESFORLEFTANDRIGHTenum 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.

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 USAGEINDETAIL.

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

   USEFORRANDOMNUMBERS
           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)

   SHOWINGANASCIITABLE
           enum -f '[%3i] "%c"' 0 127

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.

       enum - seq- and jot-like enumerator

RANDOMMODE-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-c6567 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—-101), 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).

       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.

   COUNTDEFAULTSTO1(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

   LEFTALWAYSDEFAULTSTO1(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

   RANDOMDOESNOTMIXWITHINFINITY
       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.

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

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

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

enum 1.1                                           02/02/2012                                            ENUM(1)

GENERALenum [ OPTIONS ] LEFT..COUNTxSTEP..RIGHTSHORTCUTSenum [ OPTIONS ] LEFTSTEPRIGHTenum [ OPTIONS ] LEFTRIGHTenum [ OPTIONS ] RIGHT

       ...

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

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

       enum [ OPTIONS ] LEFT..COUNTxSTEP..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 VALIDCOMBINATIONS below. Details on derivation of defaults are addressed in DERIVATIONOFDEFAULTS.

   VALIDCOMBINATIONS
       With four arguments:

       •    enumLEFT..COUNTxSTEP..RIGHT

       With three arguments:

       •    enumLEFTCOUNTxRIGHT

       •    enumLEFT..COUNTxSTEP..

       •    enum..COUNTxSTEP..RIGHT

       •    enumLEFT..COUNTx..RIGHT

       •    enumLEFT..STEP..RIGHT

       •    enumLEFTSTEPRIGHT (for GNU seq compatibility)

       With two arguments:

       •    enum..COUNTxSTEP..

       •    enum..COUNTx..RIGHT

       •    enumCOUNTx..RIGHT

       •    enum..STEP..RIGHT

       •    enumLEFT..COUNTx..

       •    enumLEFT..STEP..

       •    enumLEFT..RIGHT

       •    enumLEFTRIGHT (for GNU seq compatibility)

       With one argument:

       •    enum..STEP..

       •    enum..COUNTx..

       •    enum..RIGHT

       •    enumRIGHT (for GNU seq compatibility)

       •    enumLEFT..

       •    enumCOUNTx

       With less than three arguments, defaults apply. Details are described in DERIVATIONOFDEFAULTS below.

       Technically, more use cases are possible. For instance, COUNTxSTEP..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.

   DERIVATIONOFDEFAULTSAUTO-SELECTIONOFPRECISIONenum 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

       ARGUMENTDEFAULTS

           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 VALIDCOMBINATIONS), the unspecified ones are derived or
           set to their defaults:

           •    LEFT defaults to 1 (unless STEP and RIGHT are specified, see DERIVATIONOFLEFT 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.

       DERIVATIONOFLEFT

           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

   GENERATIONOFVALUES
       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.