.Dd October 3, 2008
.Dt COUNT 1
.Os NetBSD 1.4T
.Sh NAME
.Nm count
.Nd counting utility
.Sh SYNOPSIS
.Nm
.\" What I want is...
.\" .Op Ar keyword Ar value Op Ar keyword Ar value ...
.\" but that runs into a number-of-arguments limit, and using .Xo/.Xc
.\" doesn't work with .Op.  So....
.Bo
.Ar keyword
.Ar value
.Op Ar keyword Ar value ...
.Bc
.Sh DESCRIPTION
.Nm
counts.  The keyword-value pairs allow specifying many aspects of the
counting operation; the allowed keywords are:
.br
\ \&
.br
.Bl -tag -compact -width indent
.It from
The number to start counting at.
.It to
The number to stop counting at.
.It by
The increment between numbers.
.It for
The count of numbers to generate.
.It range
The range of numbers to generate.
.It random
Specifies random generation instead of normal counting.  (This does not
actually fit the pattern; it has no
.Ar value . )
.It base
The base to count in.
.It mod
The modulus to reduce modulo.
.It multiples-of
Print only multiples of this number.
.It pad
The width to pad the numbers to (pad with spaces).
.It 0pad
The width to pad the numbers to (pad with zeroes).
.It prefix
A string to print before the numbers.
.It postfix
A string to print after the numbers.
.It delay
How long, in seconds, to pause between each value and the next.  (May
be a float.)
.It sync
(This does not actually fit the pattern; it has no
.Ar value . )
When used with
.Ar delay ,
.Ar sync
tells
.Nm
to count not every so many seconds since startup, but rather to count
at times which are multiples of that number.  For example,
.Ar delay Ar 60
will print one number at startup and every 60 seconds thereafter;
.Ar delay Ar 60 Ar sync
will print numbers one per minute, on the minute.  (If
.Ar delay
is not used,
.Ar sync
does nothing.)
.El
.br
\ \&
.br
All of these have defaults.  The defaults are usually sensible;
specifically, the following rules are used to supply any missing
values:
.Bl -bullet -width indent
.It
If no
.Ar start
value was given, then if either
.Ar by
or
.Ar to
was given with a negative value, then the starting value is \-1,
otherwise it's 1.
.It
If no
.Ar by
value was given, then if a
.Ar to
value was given and its value is less than the (possibly defaulted)
starting value, the increment is \-1, otherwise it's 1.
.It
If
.Ar random
is not given, numbers are not randomly generated.
.It
If no
.Ar mod
value was given, numbers are not reduced modulo anything.
.It
If no
.Ar multiples-of
value was given, all numbers are printed.
.It
If no padding
.Pf ( Ar pad
or
.Ar 0pad )
was specified, no padding is provided; the effect is as if
.Sq "pad\ 1"
were specified.
.It
If no
.Ar prefix
is specified, a zero-length string is used as the prefix.
.It
If no
.Ar postfix
is specified, a single newline is used as the postfix.  (Note that
specifying a
.Ar postfix
overrides this default; if you want a newline, you must specify it.)
.It
If no
.Ar base
is specified, the default is 10.
.It
If no
.Ar delay
is given, no pause is done.
.It
If
.Ar sync
is not given, ticks are not synchronized.
.El
.br
\ \&
.br
Modular reduction (the
.Ar mod
keyword) is always done just before printing; in particular, it's done
after testing the limit condition.  For example, it makes perfect sense
to count
.Sq from 2 to 75 mod 10 .
.Ar mod
reduction is also performed after
.Ar multiples-of
processing.
.Pp
The difference between
.Ar for
and
.Ar range
lies in the use of the
.Ar by
keyword.
.Ar for
specifies the number of numbers to generate;
.Ar range
specifies the range of numbers to generate.  For example,
.D1 count from 1 by 2 for 6
generates six numbers (1, 3, 5, 7, 9, 11);
.D1 count from 1 by 2 range 6
generates only four (1, 3, 5, 7).  Specifying
.Ar for
(or
.Ar range )
with both 
.Ar from
and
.Ar to ,
or specifying both
.Ar for
and
.Ar range ,
is an error, even if the values given do not conflict.  It does not
make sense to give
.Ar for
a negative or zero argument, but
.Ar range
may be positive, negative, or zero; it is semantically equivalent to
the difference between the
.Ar from
and
.Ar to
values.
.Pp
Any numeric
.Ar value Ns s
may be given in binary, octal, decimal, or hex.  If the first two
characters of the number are 0b or 0B, the number is in binary; if 0o
or 0O, the number is in octal; if 0t or 0T, decimal; if 0x or 0X, hex.
Otherwise, the number is in decimal, unless it has a leading 0, which
indicates octal.  (This does not apply to
.Ar delay ,
even though it is in a sense numeric.)
.Pp
String values are examined for \e escapes.  If the character following
the \e is one of
.Sq abefnrt ,
the two-character sequence is replaced with a bell, a backspace, an
escape, a form-feed, a newline, a carriage-return, or a tab,
respectively.  If the following character is an octal digit, then a
string of up to three following octal digits is taken to specify a
character code.  If the following character is an x or X, a string of
hex digits of unlimited length is taken to specify a character code.
If the following character is a \&-, both the \e and the \&- are
dropped.  Otherwise, the \e is removed and the following character is
retained.
.Pp
If the
.Ar start
and
.Ar to
values are equal, only one number is printed.
.Pp
If the
.Ar by
value is zero, the result is an infinite loop, unless the previous
paragraph applies.
.Pp
.Ar multiples-of
is defined as a filter on numbers that would otherwise be printed,
applied before
.Ar mod
and
.Ar delay
processing.  For example,
.D1 count from 1 to 10 by 0 multiples-of 5
prints nothing, not the infinite stream of
.\" It ought to work to write
.\"	.Sq 5 Ns s
.\" but that puts the s inside the quotes!  So we blow off the ` '.
5s
that might be expected based on an implementation that adjusts the
.Ar from
and
.Ar to
values.
.Pp
.Ar random ,
which is incompatible with
.Ar by
and
.Ar range ,
specifies that, instead of counting,
.Nm
should generate random numbers instead.  (The numbers are generated
using
.Xr random 3
seeded with the current time at startup; in particular, they are not of
cryptographic quality.)  This changes the interpretation of some other
options:
.Bl -tag -width indent
.It by
.It range
As mentioned above, these are incompatible with
.Ar random .
.It from
.It to
.Ar from
and
.Ar to
give a range (inclusive) to select random numbers from.  If not
specified,
.Ar from
defaults to zero and
.Ar to
defaults to the largest available positive integer.
.It for
Specifies a maximum number of random numbers to generate.
.El
.Pp
Other arguments, such as
.Ar delay ,
.Ar base ,
and
.Ar mod ,
either act as a filter on the resulting stream of numbers or affect
output formatting in a way independent of number generation, and thus
work equally well with or without
.Ar random .
.Sh BUGS
There are probably bugs lurking around the use of the most negative
integer on two's-complement architectures; it's best to avoid it.
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents.montreal.qc.ca .