1ENUM(1)                            enum 1.1                            ENUM(1)
2
3
4

NAME

6       enum - seq- and jot-like enumerator
7

SYNOPSIS

9   GENERAL
10       enum [ OPTIONS ] LEFT .. COUNTx STEP .. RIGHT
11
12   SHORTCUTS
13       enum [ OPTIONS ] LEFT STEP RIGHT
14
15       enum [ OPTIONS ] LEFT RIGHT
16
17       enum [ OPTIONS ] RIGHT
18
19       ...
20

DESCRIPTION

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
28       Further enum usage details are covered in USAGE IN DETAIL.
29

EXAMPLES

31   USE IN FOR-LOOPS
32           for i in $(enum -e 1 20); do
33               touch file_${i}
34           done
35
36   USE FOR RANDOM NUMBERS
37           number=$(enum --random 3 .. 10)
38
39       instead of native Bash like
40
41           f() { min=$1; max=$2; echo $((RANDOM * (max - min + 1) / 32767 + min)); }
42           number=$(f 3 10)
43
44   SHOWING AN ASCII TABLE
45           enum -f '[%3i] "%c"' 0 127
46

OPTIONS

48   RANDOM MODE
49       -r, --random
50           Produces random numbers (potentially with duplicates) instead of
51           monotonic sequences.
52
53       -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
58   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
64       -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
68       -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
74       -f, --format=FORMAT
75           Overrides the default output format with FORMAT. For details on
76           allowed formats please see printf(3).
77
78           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
84       -l, --line
85           Shortcut for "-s ' '" which means having a space instead of a
86           newline as separator.
87
88       -n, --omit-newline
89           Omits the terminating string (defaults to newline) from output,
90           i.e. it’s a shortcut to "-t ''".
91
92       -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
98       -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
103       -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
108       -w, --word=FORMAT
109           Alias for --format, for compatibility with jot. For GNU seq’s -w
110           meaning --equal-width, see -e.
111
112       -z, --zero, --null
113           Print null bytes as separator, not a newline.
114
115   OTHER
116       -h, --help
117           Outputs usage information and exits with code 0 (success).
118
119       -V, --version
120           Displays version information and exits with code 0 (success).
121

USAGE IN DETAIL

123   ARGUMENTS
124       The logic of enum's command line parameters is:
125
126       enum [ OPTIONS ] LEFT .. COUNTx STEP .. RIGHT
127
128       Four arguments are involved:
129
130       ·    LEFT, the value to start enumeration with
131
132       ·    COUNT, the (maximum) number of values to produce
133
134       ·    STEP, the gap from one value to another
135
136       ·    RIGHT, the value to stop enumeration at (in some cases before)
137
138       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
143   VALID COMBINATIONS
144       With four arguments:
145
146       ·    enum LEFT ..  COUNTx STEP ..  RIGHT
147
148       With three arguments:
149
150       ·    enum LEFT COUNTx RIGHT
151
152       ·    enum LEFT ..  COUNTx STEP ..
153
154       ·    enum ..  COUNTx STEP ..  RIGHT
155
156       ·    enum LEFT ..  COUNTx ..  RIGHT
157
158       ·    enum LEFT ..  STEP ..  RIGHT
159
160       ·    enum LEFT STEP RIGHT (for GNU seq compatibility)
161
162       With two arguments:
163
164       ·    enum ..  COUNTx STEP ..
165
166       ·    enum ..  COUNTx ..  RIGHT
167
168       ·    enum COUNTx ..  RIGHT
169
170       ·    enum ..  STEP ..  RIGHT
171
172       ·    enum LEFT ..  COUNTx ..
173
174       ·    enum LEFT ..  STEP ..
175
176       ·    enum LEFT ..  RIGHT
177
178       ·    enum LEFT RIGHT (for GNU seq compatibility)
179
180       With one argument:
181
182       ·    enum ..  STEP ..
183
184       ·    enum ..  COUNTx ..
185
186       ·    enum ..  RIGHT
187
188       ·    enum RIGHT (for GNU seq compatibility)
189
190       ·    enum LEFT ..
191
192       ·    enum COUNTx
193
194       With less than three arguments, defaults apply. Details are described
195       in DERIVATION OF DEFAULTS below.
196
197       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
204   DERIVATION OF DEFAULTS
205       AUTO-SELECTION OF PRECISION
206           enum distinguishes between "2", "2.0", "2.00" and so on:
207
208               # enum 1 2
209               1
210               2
211
212               # enum 1 2.0
213               1.0
214               1.1
215               [..]
216               1.9
217               2.0
218
219           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
223               # enum 1 .. 3x .. 2
224               1.0
225               1.5
226               2.0
227
228           A specified precision always takes precedence, though:
229
230               # enum -p 2 1 .. 3x .. 2
231               1.00
232               1.50
233               2.00
234
235       ARGUMENT DEFAULTS
236           In general, three arguments are needed; any three imply the fourth.
237           This equation brings them together:
238
239           LEFT + (COUNT - 1) * STEP = RIGHT
240
241           If you specify less than three of them (see VALID COMBINATIONS),
242           the unspecified ones are derived or set to their defaults:
243
244           ·    LEFT defaults to 1 (unless STEP and RIGHT are specified, see
245               DERIVATION OF LEFT below)
246
247           ·    COUNT is infinity, unless it can be derived from the other
248               three values.
249
250           ·    STEP defaults to 1, unless it can be derived.
251
252           ·    RIGHT is +/-infinity, unless it can be derived from the other
253               three values.
254
255           Obviously, if COUNT is set to zero (0x), enum will output nothing,
256           regardless of the other arguments.
257
258       DERIVATION OF LEFT
259           In general, LEFT defaults to 1:
260
261               # enum .. 3
262               1
263               2
264               3
265
266           If STEP and RIGHT is given, it is derived as
267
268           LEFT = RIGHT - STEP * floor(RIGHT / STEP)
269
270               # enum .. 4 .. 10
271               2
272               6
273               10
274
275           If, in addition to STEP and RIGHT, COUNT is given, it is derived
276           as:
277
278           LEFT = RIGHT - (COUNT - 1) * STEP
279
280               # enum .. 2x 4 .. 10
281               6
282               10
283
284   GENERATION OF VALUES
285       When a custom step is requested, values are produced as follows:
286
287           value[0] = LEFT + 0 * STEP
288           value[1] = LEFT + 1 * STEP
289           ..
290           value[i] = LEFT + i * STEP
291
292       Otherwise, to avoid imprecision adding up, values are produced as
293       follows:
294
295           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
300       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

RANDOM MODE

305       Basically, random mode differs in these regards:
306
307       ·   Produced values are random.
308
309       ·   Argument COUNT defaults to 1 (one).
310
311       ·   Argument LEFT (always!) defaults to 1 (one).
312
313       ·   Argument RIGHT is required: Random does not mix with infinity.
314
315       This section covers these differences in detail.
316
317   COUNT DEFAULTS TO 1 (ONE)
318       In random mode only one value is produced, by default:
319
320           # enum 1 4
321           1
322           2
323           3
324           4
325
326           # enum -r 1 4
327           3
328
329       By specifying COUNT you can produce more values at a time:
330
331           # enum -r 1 .. 3x .. 4
332           2
333           1
334           3
335
336   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
341           # enum .. 4 .. 10
342           2
343           6
344           10
345
346       In random mode LEFT is never calculated and defaults to 1 (one):
347
348           # enum -r .. 5x 4 .. 10
349           1
350           1
351           9
352           1
353           5
354
355   RANDOM DOES NOT MIX WITH INFINITY
356       In general, enum supports running towards infinity:
357
358           # enum 1 .. 2.0 ..
359           1.0
360           3.0
361           5.0
362           [..]
363
364       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

HISTORY

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
375       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
379       The following sections take a look at the differences in detail.
380

COMPARISON TO JOT

382       Using enum instead of jot offers two main advantages:
383
384       ·   improved usability and
385
386       ·   uniform behavior across distributions and operating systems.
387
388       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
392       ·   6 integers from 0 to 5 on FreeBSD and OS X,
393
394               0 1 2 3 4 5
395
396       ·   100 integers from 0 to 99 on NetBSD, and
397
398               0 1 2 [..] 97 98 99
399
400       ·   100 integers from 0 to 5 (with consecutive duplicates) on
401           DragonFlyBSD, MirOS BSD, and OpenBSD.
402
403               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
405       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
409           # jot -p 2 3
410           1.00
411           2.00
412           3.00
413
414           # enum -p 2 3
415           1.00
416           2.00
417           3.00
418
419       Please see OPTIONS above for further details.
420
421   ADDITIONAL FEATURES
422       The extra features that enum offers over jot include:
423
424       MORE MEMORABLE COMMAND LINE USAGE
425           In order to produce 3 random numbers between 1 and 10
426           (inclusively), you would run
427
428               jot -r 3 1 10
429
430           with jot. We find these alternative calls to enum more intuitive:
431
432               enum -r 1 .. 3x .. 10
433               enum -r 1 3x 10
434
435       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
440               # enum -r 4 .. 100x 2 .. 10 | sort -u -n
441               4
442               6
443               8
444               10
445
446               # enum -r 4 .. 100x 3 .. 10 | sort -u -n
447               4
448               7
449               10
450
451       SUPPORT FOR SEVERAL PLACEHOLDERS IN FORMAT STRINGS
452           jot on DragonFlyBSD, FreeBSD, MirOS BSD, OpenBSD, and OS X:
453
454               # jot -w %g%g 3
455               jot: too many conversions
456
457           jot on NetBSD:
458
459               # jot -w %g%g 3
460               jot: unknown or invalid format `%g%g'
461
462           enum on any platform:
463
464               # enum -f %g%g 3
465               11
466               22
467               33
468
469       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
474               # jot -w '%g\x41' 1
475               1\x41
476
477           enum is able to unescape "\x41" properly:
478
479               # enum -w '%g\x41' 1
480               1A
481
482           On a side note, "\x25" produces a literal "%"; it does not make a
483           placeholder:
484
485               # enum -w '%g \x25g' 1
486               1 %g
487
488       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
493               # enum -f 'sheep number %d' 2 | xargs -n 1 echo
494               sheep
495               number
496               1
497               sheep
498               number
499               2
500
501           To prevent this, you could pass --null to both enum and xargs:
502
503               # enum --null -f 'sheep number %d' 2 | xargs --null -n 1 echo
504               sheep number 1
505               sheep number 2
506
507   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
512               # jot 3 -w test_
513               test_1
514               test_2
515               test_3
516
517           Behavior of enum:
518
519               # enum -w test_ 3
520               test_
521               test_
522               test_
523
524           In order to achieve jot’s output with enum, you should manually
525           append a placeholder:
526
527               # enum -w test_%d 3
528               test_1
529               test_2
530               test_3
531
532       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
537               # jot 3 A
538               65
539               66
540               67
541
542           Inconsistently,
543
544               # jot 3 0
545               0
546               1
547               2
548
549           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

COMPARISON TO GNU SEQ

553       Basically, enum's usage is backwards-compatible to that of GNU seq.
554
555   ADDITIONAL FEATURES
556       The extra features enum offers over GNU seq include:
557
558       RANDOM NUMBER MODE
559           enum supports output of constrained random numbers, e.g.
560
561               enum -r 4 .. 3x 2.0 .. 11
562
563           produces three (possibly duplicate) random numbers from the set
564           {4.0, 6.0, 8.0, 10.0}.
565
566       SUPPORT FOR INVERSE ORDERING
567           In contrast to GNU seq, enum supports enumerating decreasing
568           values:
569
570               # seq 3 1
571
572               # enum 3 1
573               3
574               2
575               1
576
577       SUPPORT FOR SEVERAL PLACEHOLDERS IN FORMAT STRINGS
578               # seq -f %g%g 3
579               seq: format `%g%g' has too many % directives
580
581               # enum -f %g%g 3
582               11
583               22
584               33
585
586       SUPPORT FOR ESCAPE SEQUENCES
587           GNU seq does not support escape sequences, say "\n", in FORMAT:
588
589               # seq -f '%g\x41' 1
590               1\x41
591
592           In contrast, some of the other seq implementations around do. These
593           three behaviours can be observed (as of 2010-10-25):
594
595           seq of Plan 9, 9base, and GNU seq:
596
597               # seq -f '%g\x41' 3
598               1\x41
599               2\x41
600               3\x41
601
602           seq on FreeBSD and NetBSD:
603
604               # seq -f '%g\x41' 1
605               1A
606               2A
607               3A
608
609           seq on DragonFlyBSD:
610
611               # seq -f '%g\x41' 1
612               1A3
613               2A3
614               3A3
615
616           enum unescape "\x41" to "A" as well:
617
618               # enum -f '%g\x41' 3
619               1A
620               2A
621               3A
622
623           On a side note, "\x25" produces a literal "%"; it does not make a
624           placeholder:
625
626               # enum -f '%g \x25g' 1
627               1 %g
628
629       OMITTING FINAL NEWLINE
630           By specifying -n as a parameter, you can make enum omit the
631           trailing newline.
632
633   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
637       Also, while GNU seq is licensed under GPL v3 or later, enum is licensed
638       under the New BSD license.
639

THANKS

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

AUTHORS

645       Jan Hauke Rahm <jhr@debian.org>
646
647       Sebastian Pipping <sping@gentoo.org>
648

RESOURCES

650       Main web site: https://fedorahosted.org/enum/
651
652       Gitweb: http://git.fedorahosted.org/git/?p=enum.git
653

SEE ALSO

655       jot(1), seq(1), printf(3)
656
657
658
659enum 1.1                          02/02/2012                           ENUM(1)
Impressum