1ENUM(1) enum 1.1 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 COUNTx .. RIGHT
169 · enum .. STEP .. RIGHT
171 · enum LEFT .. COUNTx ..
173 · enum LEFT .. STEP ..
175 · enum LEFT .. RIGHT
177 · enum LEFT RIGHT (for GNU seq compatibility)
179 With one argument:
181 · enum .. STEP ..
183 · enum .. COUNTx ..
185 · enum .. RIGHT
187 · enum RIGHT (for GNU seq compatibility)
189 · enum LEFT ..
191 · enum COUNTx
193 With less than three arguments, defaults apply. Details are described
195 in DERIVATION OF DEFAULTS below.
196 Technically, more use cases are possible. For instance, COUNTx STEP ..
198 RIGHT is unambiguous since the order of arguments is fixed. Yet, "enum
199 3x 4 .. 10" reads a lot like "3 values between 4 and 10" while it
200 actually would mean "3 values up to 10 in steps of 4". In order to keep
201 enum’s user interface as intuitive as possible, cases which could lead
202 to misunderstandings are not implemented.
203 DERIVATION OF DEFAULTS
205 AUTO-SELECTION OF PRECISION
206 enum distinguishes between "2", "2.0", "2.00" and so on:
207 # enum 1 2
209 1
210 2
211 # enum 1 2.0
213 1.0
214 1.1
215 [..]
216 1.9
217 2.0
218 Also, if the derived step has more decimal places than the
220 specified values for LEFT and RIGHT, the output precision will be
221 raised to that of the step value:
222 # enum 1 .. 3x .. 2
224 1.0
225 1.5
226 2.0
227 A specified precision always takes precedence, though:
229 # enum -p 2 1 .. 3x .. 2
231 1.00
232 1.50
233 2.00
234 ARGUMENT DEFAULTS
236 In general, three arguments are needed; any three imply the fourth.
237 This equation brings them together:
238 LEFT + (COUNT - 1) * STEP = RIGHT
240 If you specify less than three of them (see VALID COMBINATIONS),
242 the unspecified ones are derived or set to their defaults:
243 · LEFT defaults to 1 (unless STEP and RIGHT are specified, see
245 DERIVATION OF LEFT below)
246 · COUNT is infinity, unless it can be derived from the other
248 three values.
249 · STEP defaults to 1, unless it can be derived.
251 · RIGHT is +/-infinity, unless it can be derived from the other
253 three values.
254 Obviously, if COUNT is set to zero (0x), enum will output nothing,
256 regardless of the other arguments.
257 DERIVATION OF LEFT
259 In general, LEFT defaults to 1:
260 # enum .. 3
262 1
263 2
264 3
265 If STEP and RIGHT is given, it is derived as
267 LEFT = RIGHT - STEP * floor(RIGHT / STEP)
269 # enum .. 4 .. 10
271 2
272 6
273 10
274 If, in addition to STEP and RIGHT, COUNT is given, it is derived
276 as:
277 LEFT = RIGHT - (COUNT - 1) * STEP
279 # enum .. 2x 4 .. 10
281 6
282 10
283 GENERATION OF VALUES
285 When a custom step is requested, values are produced as follows:
286 value[0] = LEFT + 0 * STEP
288 value[1] = LEFT + 1 * STEP
289 ..
290 value[i] = LEFT + i * STEP
291 Otherwise, to avoid imprecision adding up, values are produced as
293 follows:
294 value[0] = LEFT + (RIGHT - LEFT) / (COUNT - 1) * 0
296 value[1] = LEFT + (RIGHT - LEFT) / (COUNT - 1) * 1
297 ..
298 value[i] = LEFT + (RIGHT - LEFT) / (COUNT - 1) * i
299 Production stops when either COUNT values have been produced or RIGHT
301 has been reached, whichever hits first. When all four values are given
302 in perfect match they hit at the same time.
303
305 Basically, random mode differs in these regards:
306 · Produced values are random.
308 · Argument COUNT defaults to 1 (one).
310 · Argument LEFT (always!) defaults to 1 (one).
312 · Argument RIGHT is required: Random does not mix with infinity.
314 This section covers these differences in detail.
316 COUNT DEFAULTS TO 1 (ONE)
318 In random mode only one value is produced, by default:
319 # enum 1 4
321 1
322 2
323 3
324 4
325 # enum -r 1 4
327 3
328 By specifying COUNT you can produce more values at a time:
330 # enum -r 1 .. 3x .. 4
332 2
333 1
334 3
335 LEFT ALWAYS DEFAULTS TO 1 (ONE)
337 When you need increasing numbers up to a certain maximum (say 10), each
338 separated by a certain step (say 4) you can let enum calculate the
339 needed starting value for you:
340 # enum .. 4 .. 10
342 2
343 6
344 10
345 In random mode LEFT is never calculated and defaults to 1 (one):
347 # enum -r .. 5x 4 .. 10
349 1
350 1
351 9
352 1
353 5
354 RANDOM DOES NOT MIX WITH INFINITY
356 In general, enum supports running towards infinity:
357 # enum 1 .. 2.0 ..
359 1.0
360 3.0
361 5.0
362 [..]
363 However, in random mode enum would now produce random numbers from 1 to
365 infinity (or a big number like FLT_MAX from <float.h>), which we have
366 decided against.
367
369 enum is a fusion of GNU seq and jot, feature-wise. At the core both
370 tools print sequences of numbers. GNU seq has a clean interface but
371 very limited functionality. jot on the other hand offers more advanced
372 features, like producing random numbers, at the cost of a rather
373 unfriendly interface.
374 With enum we try to offer a tool with the power of jot and a usable,
376 easily memorable interface. enum is licensed under a BSD license and
377 written in C89 for maximum portability.
378 The following sections take a look at the differences in detail.
380
382 Using enum instead of jot offers two main advantages:
383 · improved usability and
385 · uniform behavior across distributions and operating systems.
387 As of 2010-10-03, jot implementations still differ subtly between
389 DragonFlyBSD, FreeBSD, MirOS BSD, NetBSD, OpenBSD, and OS X. For
390 instance the command jot - 0 5 produces
391 · 6 integers from 0 to 5 on FreeBSD and OS X,
393 0 1 2 3 4 5
395 · 100 integers from 0 to 99 on NetBSD, and
397 0 1 2 [..] 97 98 99
399 · 100 integers from 0 to 5 (with consecutive duplicates) on
401 DragonFlyBSD, MirOS BSD, and OpenBSD.
402 0 0 0 0 0 0 0 0 0 0 1 1 [..] 4 4 5 5 5 5 5 5 5 5 5 5
404 Basically, the full feature set of jot plus a few enhancements is
406 contained in enum. Names of parameters have been retained for increased
407 compatibility, e.g. -p 2 works with enum as it does with jot:
408 # jot -p 2 3
410 1.00
411 2.00
412 3.00
413 # enum -p 2 3
415 1.00
416 2.00
417 3.00
418 Please see OPTIONS above for further details.
420 ADDITIONAL FEATURES
422 The extra features that enum offers over jot include:
423 MORE MEMORABLE COMMAND LINE USAGE
425 In order to produce 3 random numbers between 1 and 10
426 (inclusively), you would run
427 jot -r 3 1 10
429 with jot. We find these alternative calls to enum more intuitive:
431 enum -r 1 .. 3x .. 10
433 enum -r 1 3x 10
434 CUSTOM RESOLUTION OF RANDOM
436 With enum you can specify that the possible values to be randomly
437 selected from have a particular spacing. These two cases illustrate
438 the difference between a gap of 2 and 3:
439 # enum -r 4 .. 100x 2 .. 10 | sort -u -n
441 4
442 6
443 8
444 10
445 # enum -r 4 .. 100x 3 .. 10 | sort -u -n
447 4
448 7
449 10
450 SUPPORT FOR SEVERAL PLACEHOLDERS IN FORMAT STRINGS
452 jot on DragonFlyBSD, FreeBSD, MirOS BSD, OpenBSD, and OS X:
453 # jot -w %g%g 3
455 jot: too many conversions
456 jot on NetBSD:
458 # jot -w %g%g 3
460 jot: unknown or invalid format `%g%g'
461 enum on any platform:
463 # enum -f %g%g 3
465 11
466 22
467 33
468 SUPPORT FOR ESCAPE SEQUENCES
470 None of the jot implementations we tested (DragonFlyBSD, FreeBSD,
471 MirOS BSD, NetBSD, OpenBSD, and OS X) supports escape sequences,
472 say "\n", in FORMAT:
473 # jot -w '%g\x41' 1
475 1\x41
476 enum is able to unescape "\x41" properly:
478 # enum -w '%g\x41' 1
480 1A
481 On a side note, "\x25" produces a literal "%"; it does not make a
483 placeholder:
484 # enum -w '%g \x25g' 1
486 1 %g
487 NULL BYTES AS SEPARATOR
489 When using format strings containing spaces, you may run into
490 trouble in contexts like for loops or xargs: spaces are treated as
491 separators which breaks up your strings in pieces:
492 # enum -f 'sheep number %d' 2 | xargs -n 1 echo
494 sheep
495 number
496 1
497 sheep
498 number
499 2
500 To prevent this, you could pass --null to both enum and xargs:
502 # enum --null -f 'sheep number %d' 2 | xargs --null -n 1 echo
504 sheep number 1
505 sheep number 2
506 DIFFERENCES
508 HANDLING OF FORMATS WITHOUT PLACEHOLDERS
509 In contrast to jot, enum does not append the current value if the
510 formatting string does not contain a placeholder. Behavior of jot:
511 # jot 3 -w test_
513 test_1
514 test_2
515 test_3
516 Behavior of enum:
518 # enum -w test_ 3
520 test_
521 test_
522 test_
523 In order to achieve jot’s output with enum, you should manually
525 append a placeholder:
526 # enum -w test_%d 3
528 test_1
529 test_2
530 test_3
531 NON-NUMBER VALUES FOR LEFT AND RIGHT
533 enum does not support using ASCII characters instead of their
534 numerical values (e.g. "A" for 65) for LEFT and RIGHT. With jot you
535 can do:
536 # jot 3 A
538 65
539 66
540 67
541 Inconsistently,
543 # jot 3 0
545 0
546 1
547 2
548 jot does not interpret "0" as the ASCII character with code 48. We
550 have no intention of duplicating this mix, at the moment.
551
553 Basically, enum's usage is backwards-compatible to that of GNU seq.
554 ADDITIONAL FEATURES
556 The extra features enum offers over GNU seq include:
557 RANDOM NUMBER MODE
559 enum supports output of constrained random numbers, e.g.
560 enum -r 4 .. 3x 2.0 .. 11
562 produces three (possibly duplicate) random numbers from the set
564 {4.0, 6.0, 8.0, 10.0}.
565 SUPPORT FOR INVERSE ORDERING
567 In contrast to GNU seq, enum supports enumerating decreasing
568 values:
569 # seq 3 1
571 # enum 3 1
573 3
574 2
575 1
576 SUPPORT FOR SEVERAL PLACEHOLDERS IN FORMAT STRINGS
578 # seq -f %g%g 3
579 seq: format `%g%g' has too many % directives
580 # enum -f %g%g 3
582 11
583 22
584 33
585 SUPPORT FOR ESCAPE SEQUENCES
587 GNU seq does not support escape sequences, say "\n", in FORMAT:
588 # seq -f '%g\x41' 1
590 1\x41
591 In contrast, some of the other seq implementations around do. These
593 three behaviours can be observed (as of 2010-10-25):
594 seq of Plan 9, 9base, and GNU seq:
596 # seq -f '%g\x41' 3
598 1\x41
599 2\x41
600 3\x41
601 seq on FreeBSD and NetBSD:
603 # seq -f '%g\x41' 1
605 1A
606 2A
607 3A
608 seq on DragonFlyBSD:
610 # seq -f '%g\x41' 1
612 1A3
613 2A3
614 3A3
615 enum unescape "\x41" to "A" as well:
617 # enum -f '%g\x41' 3
619 1A
620 2A
621 3A
622 On a side note, "\x25" produces a literal "%"; it does not make a
624 placeholder:
625 # enum -f '%g \x25g' 1
627 1 %g
628 OMITTING FINAL NEWLINE
630 By specifying -n as a parameter, you can make enum omit the
631 trailing newline.
632 DIFFERENCES
634 GNU seq’s --equal-width shortcut -w conflicts with jot’s -w word. We
635 chose to make -e the shortcut for --equal-width in enum, instead.
636 Also, while GNU seq is licensed under GPL v3 or later, enum is licensed
638 under the New BSD license.
639
641 Elias Pipping, Andreas Gunschl, Justin B. Rye, David Prevot, Kamil
642 Dudka, Michael Bienia
643
645 Jan Hauke Rahm <jhr@debian.org>
646 Sebastian Pipping <sping@gentoo.org>
648
650 Main web site: https://fedorahosted.org/enum/
651 Gitweb: http://git.fedorahosted.org/git/?p=enum.git
653
655 jot(1), seq(1), printf(3)
656enum 1.1 02/02/2012 ENUM(1)