NUMBERS(1)

NAME
numbers - Locate and print interesting numbers in files

SYNOPSIS
numbers [OPTIONS]... list-of-File-or-Directory

DESCRIPTION
Numbers extracts numeric literals (the current release limits itself to values containing a decimal point or exponent) from its input files and compares them against values contained in an interesting numbers database. A match causes information about the number to be output, for instance that the number matched corresponds to the diameter of the Sun or the orbit of Mercury suggests an astronomical related domain.

The interesting numbers database is a collection of text files that users are encouraged to add to. The default directory for these files is called ndb and is initially searched for in the directory containing the numbers program executable. If the argument is a directory all files in that directory and any contained subdirectories will be processed.

OPTIONS

Options may be abbreviated to the first three characters after the - character. Many options parameters may be immediately followed by a + or - sign to specify on/off. If neither of these characters is used a + is assumed.

-help, -v, -V
    Prints a version, copyright and usage message to stdout and exits.

-allow space+
    By default a space character is treated as a delimiter, i.e., it causes space separated literals to be treated as two separate literals. Enabling the space option causes numbers to skip a single space character if it occurs between two sequences of digit characters.

-fuzz-percent <number>
    By default numbers compares literal values looking for a match that is within 0.01% of a value in the interesting number database. The value of <number> is used as the fuzzyness for this comparison, e.g., to match within 0.1% use:
    numbers stuff.txt -fuzz 0.001

-ignore comments-
    Switching this option on causes the contents of comments to be ignored. A filename's suffix is taken to specify the programming language it contains and provided number's language_info file contains information on that language then the contents of single line comments are ignored.

-levenstein-distance <number>
    The -match option includes support for comparing digit sequences rather than numeric values. A sequence comparison does not have to be exact to succeed. This option specifies the levenstein distance to be used as the criteria for a successful match, e.g., to specify a levenstein distance of 3:
    numbers stuff.txt -match mantissa -lev 3
    The distance between two changed digits that are adjacent on the keyboard is 1. Every other kind of difference has a distance of 2.

-match mantissa
    Sometimes the value appearing in the input file is a scaled, by some power of ten, version of a value in the interesting number database. While a value comparison would not succeed in this case a comparison against the digits appearing in the mantissa would. This option enables the checking of mantissa digit sequences: By default this option is off, to switch it on: numbers stuff.txt -match mantissa
    It is possible to perform a fuzzy match on the mantissa digit sequence. The fuzzyness can be controlled either by specifying the number of significant digits that must match (default 5) or by specifying a minimum levenstein distance of the comparison (default 2).

-match <number>
    Most literals contain a small number of non-zero digits and are unlikely to be 'interesting'. For a match to be attempted on a given input literal it must contain at least <number> non-zero digits (default 5). There is one exception to this matching rule. A match will always be attempted against any values in the interesting number database that contain less than <number> non-zero digits.

-match value
    By default comparisons are performed using a fuzzy match against numeric values. This form of comparison can be switched off using this option:

    numbers stuff.txt -match value- -match mantissa+

-mkndb all
    This option generates a text file in 'number database' format containing all of the numeric literals in the input files that do not match any value in the current interesting number database.

-mkndb <number>
    This option generates a text file in 'number database' format containing all of the numeric literals in the input files that contain at least <number> significant digits and do not match any value in the current interesting number database.

-ndb file-name
    Causes file-name to be read as an interesting numbers database prior to processing any input files.

-need failmax <number>
    After one or more values in a need sequence are encountered the match is deemed to have failed if <number> consecutive values that do not match any need sequence are encountered.

-need percent <number>
    If <number> percent of all values in a need sequence match before a failmax match failures occur, output this information.

-need suspect <number>
    If <number> values in a need sequence match before a failmax match failures occur and at least 40% of the sequence matches, output this information.

-print all
    Print all numeric literals encountered in the input. Default off.

-print match
    Print all numeric literals encountered in the input that match against a value in the interesting number database. Default on.

-print nomatch
    Print all numeric literals encountered in the input that do not match against a value in the interesting number database. Default off.

-print word
    Words that occur before a value may provide some context about the application domain it comes from. This option enables the printing of words (default value 5) that occur immediately prior to a literal. Default off.

-print <number>
    A specified number of significant digits that must occur in a literal's mantissa for it to be printed. Default 5.

-summary match
    Causes a summary of the literals matched to be output after all of the input files have been processed. Default on. The significant digits in the numeric literal that match the corresponding digit in the interesting number value are printed as '.'.

-summary nomatch
    Causes a summary of the literals not matched to be output after all of the input files have been processed. Default off.

-trace input
    Causes the contents of the input files to be printed as they are processed. Default off.

-trace ndb
    Causes the contents of the interesting numbers database to be printed as it is processed. Default off.

-trace progress
    By default the names of directories being processed are printed. This progress trace can be switched off using:
    number /usr/source -trace progress-

-usage file
    When switch on causes a list of all filename suffixes (character sequences appearing after a period and containing four or less characters) encountered to be printed at the end of processing (first column is files not processed, second colum files processed).

-usage value
    When switch on causes information on the literal values encountered to be summarised at the end of processing.

-wildcard <shell-wildcard>
    Only process those files that match the <shell-wildcard> pattern. Primarily of use when processing multiple directories. For example, the following would result in only C source and header files being processed. The double-quotes are needed to prevent shell expansion:
    numbers /usr/src-dir -wild "*.[ch]"
    Note: Shell expansion supports a subset of the patterns supported by the ls command. Multiple -wild options can be used to acheive the same effect, for instance to also match files that end in for.
    numbers /usr/src-dir -wild "*.[ch]" -wild "*.for"
    This functionality is only available on platforms that support the <fnmatch.h> system header and the patterns supported may depend on the characteristics of the host shell.

-words <number>
    Specified the number of words to print for the -print word option. Default value 20.

Interesting number database
This database consists of one of more text files each of which may contain comments, lines containing a number and associated message and lines specifying directives. The default database is called default.txt and is expected to occur in a directory called ndb that is contained in the same directory as the numbers executable program. Additional interesting number databases may be specified via the -ndb option. Any line starting with the character # is treated as a comment. The format of a number information line is: digit-sequence | character-sequence When 'digit-sequence' is matched 'character-sequence' is printed. Some examples: 3.14159 26535 89793 23846 26433 83279 50288 | pi
-0.27368494524164255994e+2 as you can see digit sequences may be separated by spaces for clarity and if there is no message the vertical bar may be omitted. The character-sequence is treated like the first argument to printf (i.e., escape sequences are expanded to the appropriate character, e.g., becomes a new-line character). Any line starting with the character ! is treated as a directive. The directives are:

!fuzz <number>
    <number> is treated as the fuzz factor to use in numeric comparisons for all values in the current file or until another !fuzz directive is encountered.

!include character_sequence
    The character sequence is treated as the name of a ndb file that should be processed at this point.

!msgpostfix character-sequence
    The character sequence is added to the end of every message output when a number in the current file, or up to the next !msgpostfix directive, matches.

!msgprefix character-sequence
    The character sequence is added to the start of every message output when a number in the current file, or up to the next !msgpostfix directive, matches.

!need number
    Sometimes matching one number is not of interest but it is of interest when two or more numbers match. The !need directive specifies how many of the following numbers must match before any message is output. The character sequence all means that all of the following numbers in the current file, or until another !need directive is encountered, must match.

!title character-sequence.
    The character sequence is treated as the title of the file. Currently has no external effect.

EXAMPLES
Check whether a given value is contained in the Interesting number database:
echo "3.14159" | numbers
A list of wildcard options that have been found to be effective in matching source files is: -wild "*.[chfmCHF]" -wild "*.cc" -wild "*.hh" -wild "*.[ch]xx" -wild "*.[chi]pp" -wild "*.[fF]90" -wild "*.py" -wild "*.java" -wild "*.lisp" -wild "*.[hi]cc"

HOME PAGE FOR NUMBERS:
Please see the following web site for updates, further documentation, bug reports and patches: http://www.coding-guidelines.com/numbers/

AUTHOR
Written by Derek M. Jones

REPORTING BUGS
Report bugs to <numbers@knosof.co.uk>.

COPYRIGHT
Copyright © 2010 Knowledge Software Ltd
The hashtable implementation: Copyright (C) 2004 Christopher Clark <firstname.lastname@cl.cam.ac.uk>
The hashfunction implementation: by Bob Jenkins, May 2006, Public Domain.