1ENUM(1) enum 1.0.2 ENUM(1)
2
6 enum - seq- and jot-like enumerator
7
9 GENERAL
10 enum [ OPTIONS ] LEFT .. COUNTx STEP .. RIGHT
11 SHORTCUTS
13 enum [ OPTIONS ] LEFT STEP RIGHT
14 enum [ OPTIONS ] LEFT RIGHT
16 enum [ OPTIONS ] RIGHT
18 ...
20
22 enum enumerates values (numbers) from LEFT to RIGHT adding/subtracting
23 STEP each time. If STEP is not provided a value is implied. No more
24 than COUNT values are printed. Before printing, values are passed
25 through a formatter. Please see OPTIONS for details on controlling the
26 formatter or EXAMPLES for use cases.
27 Further enum usage details are covered in USAGE IN DETAIL.
29
31 USE IN FOR-LOOPS
32 for i in $(enum -e 1 20); do
33 touch file_${i}
34 done
35 USE FOR RANDOM NUMBERS
37 number=$(enum --random 3 .. 10)
38 instead of native Bash like
40 f() { min=$1; max=$2; echo $((RANDOM * (max - min + 1) / 32767 + min)); }
42 number=$(f 3 10)
43 SHOWING AN ASCII TABLE
45 enum -f '[%3i] "%c"' 0 127
46
48 RANDOM MODE
49 -r, --random
50 Produces random numbers (potentially with duplicates) instead of
51 monotonic sequences.
52 -i, --seed=NUMBER
54 Pass NUMBER as initializer to the random number generator. By
55 default, the RNG is initialized from the current time and the
56 process ID of the running instance of enum.
57 FORMATTING
59 -b, --dumb=TEXT
60 Overrides the output format to TEXT without interpolating
61 placeholders. For instance, enum -b "foo % 10" 3x produces the
62 string "foo % 10" three times.
63 -c, --characters
65 Overrides the output format to %c producing characters. For
66 example, enum -c 65 67 produces the letters "A", "B" and "C".
67 -e, --equal-width
69 Equalize width by padding with leading zeroes. NOTE: In the case of
70 mixed negative and non-negative numbers (e.g. with enum -e — -10
71 1), non-negative values will compensate for the lack of a leading
72 minus with an extra zero to be of equal width.
73 -f, --format=FORMAT
75 Overrides the default output format with FORMAT. For details on
76 allowed formats please see printf(3).
77 FORMAT is subject to processing of C escape sequences (e.g. "\n"
79 makes a newline). If FORMAT does not contain any placeholders, enum
80 will print FORMAT repeatedly. In contrast, jot would have appended
81 the number’s value instead. To make numbers appear at the end with
82 enum, adjust FORMAT appropriately.
83 -l, --line
85 Shortcut for "-s ' '" which means having a space instead of a
86 newline as separator.
87 -n, --omit-newline
89 Omits the terminating string (defaults to newline) from output,
90 i.e. it’s a shortcut to "-t ''".
91 -p, --precision=COUNT
93 Overrides automatic selection of precision to print COUNT decimal
94 places, e.g. "0.100" for COUNT = 3. By default, the number of
95 digits to print is computed from the arguments given and the (given
96 or computed) step size.
97 -s, --separator=TEXT
99 Overrides the separator that is printed between values. By default,
100 values are separated by a newline. TEXT is subject to processing
101 of C escape sequences (e.g. "\n" makes a newline).
102 -t, --terminator=TEXT
104 Overrides the terminator that is printed in the very end. Default
105 is a newline. TEXT is subject to processing of C escape sequences
106 (e.g. "\n" makes a newline).
107 -w, --word=FORMAT
109 Alias for --format, for compatibility with jot. For GNU seq’s -w
110 meaning --equal-width, see -e.
111 -z, --zero, --null
113 Print null bytes as separator, not a newline.
114 OTHER
116 -h, --help
117 Outputs usage information and exits with code 0 (success).
118 -V, --version
120 Displays version information and exits with code 0 (success).
121
123 ARGUMENTS
124 The logic of enum's command line parameters is:
125 enum [ OPTIONS ] LEFT .. COUNTx STEP .. RIGHT
127 Four arguments are involved:
129 · LEFT, the value to start enumeration with
131 · COUNT, the (maximum) number of values to produce
133 · STEP, the gap from one value to another
135 · RIGHT, the value to stop enumeration at (in some cases before)
137 Not all four arguments are needed, though specifying all four is
139 possible. For a list of all valid combinations see VALID COMBINATIONS
140 below. Details on derivation of defaults are addressed in DERIVATION OF
141 DEFAULTS.
142 VALID COMBINATIONS
144 With four arguments:
145 · enum LEFT .. COUNTx STEP .. RIGHT
147 With three arguments:
149 · enum LEFT COUNTx RIGHT
151 · enum LEFT .. COUNTx STEP ..
153 · enum .. COUNTx STEP .. RIGHT
155 · enum LEFT .. COUNTx .. RIGHT
157 · enum LEFT .. STEP .. RIGHT
159 · enum LEFT STEP RIGHT (for GNU seq compatibility)
161 With two arguments:
163 · enum .. COUNTx STEP ..
165 · enum .. COUNTx .. RIGHT
167 · enum .. STEP .. RIGHT
169 · enum LEFT .. COUNTx ..
171 · enum LEFT .. STEP ..
173 · enum LEFT .. RIGHT
175 · enum LEFT RIGHT (for GNU seq compatibility)
177 With one argument:
179 · enum .. STEP ..
181 · enum .. COUNTx ..
183 · enum .. RIGHT
185 · enum RIGHT (for GNU seq compatibility)
187 · enum LEFT ..
189 · enum COUNTx
191 With less than three arguments, defaults apply. Details are described
193 in DERIVATION OF DEFAULTS below.
194 DERIVATION OF DEFAULTS
196 AUTO-SELECTION OF PRECISION
197 enum distinguishes between "2", "2.0", "2.00" and so on:
198 # enum 1 2
200 1
201 2
202 # enum 1 2.0
204 1.0
205 1.1
206 [..]
207 1.9
208 2.0
209 Also, if the derived step has more decimal places than the
211 specified values for LEFT and RIGHT, the output precision will be
212 raised to that of the step value:
213 # enum 1 .. 3x .. 2
215 1.0
216 1.5
217 2.0
218 A specified precision always takes precedence, though:
220 # enum -p 2 1 .. 3x .. 2
222 1.00
223 1.50
224 2.00
225 ARGUMENT DEFAULTS
227 In general, three arguments are needed; any three imply the fourth.
228 This equation brings them together:
229 LEFT + (COUNT - 1) * STEP = RIGHT
231 If you specify less than three of them (see VALID COMBINATIONS),
233 the unspecified ones are derived or set to their defaults:
234 · LEFT defaults to 1 (unless STEP and RIGHT are specified, see
236 DERIVATION OF LEFT below)
237 · COUNT is infinity, unless it can be derived from the other
239 three values.
240 · STEP defaults to 1, unless it can be derived.
242 · RIGHT is +/-infinity, unless it can be derived from the other
244 three values.
245 DERIVATION OF LEFT
247 In general, LEFT defaults to 1:
248 # enum .. 3
250 1
251 2
252 3
253 If STEP and RIGHT is given, it is derived as
255 LEFT = RIGHT - STEP * floor(RIGHT / STEP)
257 # enum .. 4 .. 10
259 2
260 6
261 10
262 If, in addition to STEP and RIGHT, COUNT is given, it is derived
264 as:
265 LEFT = RIGHT - (COUNT - 1) * STEP
267 # enum .. 2x 4 .. 10
269 6
270 10
271 GENERATION OF VALUES
273 When a custom step is requested, values are produced as follows:
274 value[0] = LEFT + 0 * STEP
276 value[1] = LEFT + 1 * STEP
277 ..
278 value[i] = LEFT + i * STEP
279 Otherwise, to avoid imprecision adding up, values are produced as
281 follows:
282 value[0] = LEFT + (RIGHT - LEFT) / (COUNT - 1) * 0
284 value[1] = LEFT + (RIGHT - LEFT) / (COUNT - 1) * 1
285 ..
286 value[i] = LEFT + (RIGHT - LEFT) / (COUNT - 1) * i
287 Production stops when either COUNT values have been produced or RIGHT
289 has been reached, whichever hits first. When all four values are given
290 in perfect match they hit at the same time.
291
293 Basically, random mode differs in these regards:
294 · Produced values are random.
296 · Argument COUNT defaults to 1 (one).
298 · Argument LEFT (always!) defaults to 1 (one).
300 · Argument RIGHT is required: Random does not mix with infinity.
302 This section covers these differences in detail.
304 COUNT DEFAULTS TO 1 (ONE)
306 In random mode only one value is produced, by default:
307 # enum 1 4
309 1
310 2
311 3
312 4
313 # enum -r 1 4
315 3
316 By specifying COUNT you can produce more values at a time:
318 # enum -r 1 .. 3x .. 4
320 2
321 1
322 3
323 LEFT ALWAYS DEFAULTS TO 1 (ONE)
325 When you need increasing numbers up to a certain maximum (say 10), each
326 separated by a certain step (say 4) you can let enum calculate the
327 needed starting value for you:
328 # enum .. 4 .. 10
330 2
331 6
332 10
333 In random mode LEFT is never calculated and defaults to 1 (one):
335 # enum -r .. 5x 4 .. 10
337 1
338 1
339 9
340 1
341 5
342 RANDOM DOES NOT MIX WITH INFINITY
344 In general, enum supports running towards infinity:
345 # enum 1 .. 2.0 ..
347 1.0
348 3.0
349 5.0
350 [..]
351 However, in random mode enum would now produce random numbers from 1 to
353 infinity (or a big number like FLT_MAX from <float.h>), which we have
354 decided against.
355
357 enum is a fusion of GNU seq and jot, feature-wise. At the core both
358 tools print sequences of numbers. GNU seq has a clean interface but
359 very limited functionality. jot on the other hand offers more advanced
360 features, like producing random numbers, at the cost of a rather
361 unfriendly interface.
362 With enum we try to offer a tool with the power of jot and a usable,
364 easily memorable interface. enum is licensed under a BSD license and
365 written in C89 for maximum portability.
366 The following sections take a look at the differences in detail.
368
370 Using enum instead of jot offers two main advantages:
371 · improved usability and
373 · uniform behavior across distributions and operating systems.
375 As of 2010-10-03, jot implementations still differ subtly between
377 DragonFlyBSD, FreeBSD, MirOS BSD, NetBSD, OpenBSD, and OS X. For
378 instance the command jot - 0 5 produces
379 · 6 integers from 0 to 5 on FreeBSD and OS X,
381 0 1 2 3 4 5
383 · 100 integers from 0 to 99 on NetBSD, and
385 0 1 2 [..] 97 98 99
387 · 100 integers from 0 to 5 (with consecutive duplicates) on
389 DragonFlyBSD, MirOS BSD, and OpenBSD.
390 0 0 0 0 0 0 0 0 0 0 1 1 [..] 4 4 5 5 5 5 5 5 5 5 5 5
392 Basically, the full feature set of jot plus a few enhancements is
394 contained in enum. Names of parameters have been retained for increased
395 compatibility, e.g. -p 2 works with enum as it does with jot:
396 # jot -p 2 3
398 1.00
399 2.00
400 3.00
401 # enum -p 2 3
403 1.00
404 2.00
405 3.00
406 Please see OPTIONS above for further details.
408 ADDITIONAL FEATURES
410 The extra features that enum offers over jot include:
411 MORE MEMORABLE COMMAND LINE USAGE
413 In order to produce 3 random numbers between 1 and 10
414 (inclusively), you would run
415 jot -r 3 1 10
417 with jot. We find these alternative calls to enum more intuitive:
419 enum -r 1 .. 3x .. 10
421 enum -r 1 3x 10
422 CUSTOM RESOLUTION OF RANDOM
424 With enum you can specify that the possible values to be randomly
425 selected from have a particular spacing. These two cases illustrate
426 the difference between a gap of 2 and 3:
427 # enum -r 4 .. 100x 2 .. 10 | sort -u -n
429 4
430 6
431 8
432 10
433 # enum -r 4 .. 100x 3 .. 10 | sort -u -n
435 4
436 7
437 10
438 SUPPORT FOR SEVERAL PLACEHOLDERS IN FORMAT STRINGS
440 jot on DragonFlyBSD, FreeBSD, MirOS BSD, OpenBSD, and OS X:
441 # jot -w %g%g 3
443 jot: too many conversions
444 jot on NetBSD:
446 # jot -w %g%g 3
448 jot: unknown or invalid format `%g%g'
449 enum on any platform:
451 # enum -f %g%g 3
453 11
454 22
455 33
456 SUPPORT FOR ESCAPE SEQUENCES
458 None of the jot implementations we tested (DragonFlyBSD, FreeBSD,
459 MirOS BSD, NetBSD, OpenBSD, and OS X) supports escape sequences,
460 say "\n", in FORMAT:
461 # jot -w '%g\x41' 1
463 1\x41
464 enum is able to unescape "\x41" properly:
466 # enum -w '%g\x41' 1
468 1A
469 On a side note, "\x25" produces a literal "%"; it does not make a
471 placeholder:
472 # enum -w '%g \x25g' 1
474 1 %g
475 NULL BYTES AS SEPARATOR
477 When using format strings containing spaces, you may run into
478 trouble in contexts like for loops or xargs: spaces are treated as
479 separators which breaks up your strings in pieces:
480 # enum -f 'sheep number %d' 2 | xargs -n 1 echo
482 sheep
483 number
484 1
485 sheep
486 number
487 2
488 To prevent this, you could pass --null to both enum and xargs:
490 # enum --null -f 'sheep number %d' 2 | xargs --null -n 1 echo
492 sheep number 1
493 sheep number 2
494 DIFFERENCES
496 HANDLING OF FORMATS WITHOUT PLACEHOLDERS
497 In contrast to jot, enum does not append the current value if the
498 formatting string does not contain a placeholder. Behavior of jot:
499 # jot 3 -w test_
501 test_1
502 test_2
503 test_3
504 Behavior of enum:
506 # enum -w test_ 3
508 test_
509 test_
510 test_
511 In order to achieve jot’s output with enum, you should manually
513 append a placeholder:
514 # enum -w test_%d 3
516 test_1
517 test_2
518 test_3
519 NON-NUMBER VALUES FOR LEFT AND RIGHT
521 enum does not support using ASCII characters instead of their
522 numerical values (e.g. "A" for 65) for LEFT and RIGHT. With jot you
523 can do:
524 # jot 3 A
526 65
527 66
528 67
529 Inconsistently,
531 # jot 3 0
533 0
534 1
535 2
536 jot does not interpret "0" as the ASCII character with code 48. We
538 have no intention of duplicating this mix, at the moment.
539
541 Basically, enum's usage is backwards-compatible to that of GNU seq.
542 ADDITIONAL FEATURES
544 The extra features enum offers over GNU seq include:
545 RANDOM NUMBER MODE
547 enum supports output of constrained random numbers, e.g.
548 enum -r 4 .. 3x 2.0 .. 11
550 produces three (possibly duplicate) random numbers from the set
552 {4.0, 6.0, 8.0, 10.0}.
553 SUPPORT FOR INVERSE ORDERING
555 In contrast to GNU seq, enum supports enumerating decreasing
556 values:
557 # seq 3 1
559 # enum 3 1
561 3
562 2
563 1
564 SUPPORT FOR SEVERAL PLACEHOLDERS IN FORMAT STRINGS
566 # seq -f %g%g 3
567 seq: format `%g%g' has too many % directives
568 # enum -f %g%g 3
570 11
571 22
572 33
573 SUPPORT FOR ESCAPE SEQUENCES
575 GNU seq does not support escape sequences, say "\n", in FORMAT:
576 # seq -f '%g\x41' 1
578 1\x41
579 In contrast, some of the other seq implementations around do. These
581 three behaviours can be observed (as of 2010-10-25):
582 seq of Plan 9, 9base, and GNU seq:
584 # seq -f '%g\x41' 3
586 1\x41
587 2\x41
588 3\x41
589 seq on FreeBSD and NetBSD:
591 # seq -f '%g\x41' 1
593 1A
594 2A
595 3A
596 seq on DragonFlyBSD:
598 # seq -f '%g\x41' 1
600 1A3
601 2A3
602 3A3
603 enum unescape "\x41" to "A" as well:
605 # enum -f '%g\x41' 3
607 1A
608 2A
609 3A
610 On a side note, "\x25" produces a literal "%"; it does not make a
612 placeholder:
613 # enum -f '%g \x25g' 1
615 1 %g
616 OMITTING FINAL NEWLINE
618 By specifying -n as a parameter, you can make enum omit the
619 trailing newline.
620 DIFFERENCES
622 GNU seq’s --equal-width shortcut -w conflicts with jot’s -w word. We
623 chose to make -e the shortcut for --equal-width in enum, instead.
624 Also, while GNU seq is licensed under GPL v3 or later, enum is licensed
626 under the New BSD license.
627
629 Elias Pipping, Andreas Gunschl, Justin B. Rye, David Prevot, Kamil
630 Dudka
631
633 Jan Hauke Rahm <jhr@debian.org>
634 Sebastian Pipping <sping@gentoo.org>
636
638 Main web site: https://fedorahosted.org/enum/
639 Gitweb: http://git.fedorahosted.org/git/?p=enum.git
641
643 jot(1), seq(1), printf(3)
644enum 1.0.2 11/02/2010 ENUM(1)