other sections
ENUM(1) | enum 1.1 | ENUM(1) |
NAME¶
enum - seq- and jot-like enumeratorSYNOPSIS¶
GENERAL¶
enum [ OPTIONS ] LEFT .. COUNTx STEP .. RIGHTSHORTCUTS¶
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)
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, --randomProduces 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=TEXTOverrides 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, --helpOutputs 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:• 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 ..
COUNTx STEP .. RIGHT
With three arguments:
• enum LEFT COUNTx
RIGHT
• enum LEFT ..
COUNTx STEP ..
• enum .. COUNTx
STEP .. RIGHT
• enum LEFT ..
COUNTx .. RIGHT
• enum LEFT .. STEP
.. RIGHT
• enum LEFT STEP RIGHT
(for GNU seq compatibility)
With two arguments:
• enum .. COUNTx
STEP ..
• enum .. COUNTx
.. RIGHT
• enum COUNTx ..
RIGHT
• enum .. STEP ..
RIGHT
• enum LEFT ..
COUNTx ..
• enum LEFT .. STEP
..
• enum LEFT ..
RIGHT
• enum LEFT RIGHT (for GNU
seq compatibility)
With one argument:
• enum .. STEP
..
• enum .. COUNTx
..
• enum .. RIGHT
• enum RIGHT (for GNU seq
compatibility)
• enum LEFT ..
• 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:
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:
A specified precision always takes precedence, though:
# enum 1 2 1 2 # enum 1 2.0 1.0 1.1 [..] 1.9 2.0
# enum 1 .. 3x .. 2 1.0 1.5 2.0
# enum -p 2 1 .. 3x .. 2 1.00 1.50 2.00
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.
In general, LEFT defaults to 1:
If STEP and RIGHT is given, it is derived as
LEFT = RIGHT - STEP * floor(RIGHT / STEP)
If, in addition to STEP and RIGHT, COUNT is given, it is
derived as:
LEFT = RIGHT - (COUNT - 1) * STEP
# enum .. 3 1 2 3
# enum .. 4 .. 10 2 6 10
# 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
value[0] = LEFT + (RIGHT - LEFT) / (COUNT - 1) * 0 value[1] = LEFT + (RIGHT - LEFT) / (COUNT - 1) * 1 .. value[i] = LEFT + (RIGHT - LEFT) / (COUNT - 1) * i
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
# 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
# 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 [..]
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.
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:
0 0 0 0 0 0 0 0 0 0 1 1 [..] 4 4 5 5 5 5 5 5 5 5 5 5
# jot -p 2 3 1.00 2.00 3.00 # enum -p 2 3 1.00 2.00 3.00
ADDITIONAL FEATURES¶
The extra features that enum offers over jot include:
In order to produce 3 random numbers between 1 and 10 (inclusively), you would
run
with jot. We find these alternative calls to enum more intuitive:
jot -r 3 1 10
enum -r 1 .. 3x .. 10 enum -r 1 3x 10
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
jot on DragonFlyBSD, FreeBSD, MirOS BSD, OpenBSD, and OS X:
jot on NetBSD:
enum on any platform:
# jot -w %g%g 3 jot: too many conversions
# jot -w %g%g 3 jot: unknown or invalid format `%g%g'
# enum -f %g%g 3 11 22 33
None of the jot implementations we tested (DragonFlyBSD, FreeBSD, MirOS BSD,
NetBSD, OpenBSD, and OS X) supports escape sequences, say "\n", in
FORMAT:
enum is able to unescape "\x41" properly:
On a side note, "\x25" produces a literal "%"; it does not
make a placeholder:
# jot -w '%g\x41' 1 1\x41
# enum -w '%g\x41' 1 1A
# enum -w '%g \x25g' 1 1 %g
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:
To prevent this, you could pass --null to both enum and xargs:
# enum -f 'sheep number %d' 2 | xargs -n 1 echo sheep number 1 sheep number 2
# 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:
Behavior of enum:
In order to achieve jot’s output with enum, you should manually
append a placeholder:
# jot 3 -w test_ test_1 test_2 test_3
# enum -w test_ 3 test_ test_ test_
# enum -w test_%d 3 test_1 test_2 test_3
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:
Inconsistently,
jot does not interpret "0" as the ASCII character with code 48. We
have no intention of duplicating this mix, at the moment.
# jot 3 A 65 66 67
# jot 3 0 0 1 2
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:
enum supports output of constrained random numbers, e.g.
produces three (possibly duplicate) random numbers from the set {4.0, 6.0, 8.0,
10.0}.
enum -r 4 .. 3x 2.0 .. 11
In contrast to GNU seq, enum supports enumerating decreasing values:
# seq 3 1 # enum 3 1 3 2 1
# seq -f %g%g 3 seq: format `%g%g' has too many % directives # enum -f %g%g 3 11 22 33
GNU seq does not support escape sequences, say "\n", in FORMAT:
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 on FreeBSD and NetBSD:
seq on DragonFlyBSD:
enum unescape "\x41" to "A" as well:
On a side note, "\x25" produces a literal "%"; it does not
make a placeholder:
# seq -f '%g\x41' 1 1\x41
# seq -f '%g\x41' 3 1\x41 2\x41 3\x41
# seq -f '%g\x41' 1 1A 2A 3A
# seq -f '%g\x41' 1 1A3 2A3 3A3
# enum -f '%g\x41' 3 1A 2A 3A
# enum -f '%g \x25g' 1 1 %g
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 BieniaAUTHORS¶
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.gitSEE ALSO¶
jot(1), seq(1), printf(3)02/02/2012 | enum 1.1 |