Documentation
¶
Overview ¶
Numbers is a text-based calculator language.
numbers [file...]
Numbers executes the input files given on the command line, or else standard input.
The input is a sequence of value definitions, such as:
Tax = Income * Tax Rate Tax Rate = 5.3% Income = $10,000
The output shows all computed values that were not otherwise used. In the example above, the computation of Tax uses the other two values but is not itself used, so the output of the program is the value of Tax:
Tax = $530.00
The computation expressed by a numbers program is not dependent on the order of the input lines. All permutations of the input above produce the same result. Of course, it is not allowed for a computation to use its own value.
The printed results occur in the order their definitions appear in the input.
Expressions ¶
An expression is a constant, a variable name, or a computation.
Constants are numbers, percentages, or dollar amounts: 42, 5.3%, $10,000. The commas in large dollar amounts are required.
Variable names are alphanumeric text beginning with an alphabetic character. They may contain embedded spaces and apostrophes.
A computation expression is one of the following, where x, y, and z are themselves expressions.
(x) # parenthesization -x # negation x + y # addition x - y # subtraction x * y # multiplication x / y # division x < y # compare less than x <= y # compare less than or equal x > y # compare greater than x >= y # compare greater than or equal x == y # compare equal x != y # compare not equal max(x, y) # maximum of x and y min(x, y) # minimum of x and y cond(x, y, z) # if x is true, y, otherwise z
Each expression evaluates to a typed value. Constants have the types number, percentage, or dollar amount, depending on their form.
Addition and subtraction require operands of the same type. The result has the same type.
Multiplication requires one of its operands to be a number or percentage. The result has the type of the other operand.
Division can operate in two ways. If the divisor is a number or percentage, the result has the type of the dividend. If the divisor has the same type as the dividend, the result is a number.
Comparisons require operands of the same type. The result is a boolean.
Max and min require operands of the same type. The result has the same type.
Cond requires that the condition x be a boolean, and that y and z have the same type. Cond is not short-circuit: both y and z are evaluated. The result has the type of y and z.
All values are stored as float64s.
Statements ¶
The most common form of statement is the definition:
variable name = expression
This defines the meaning of variable name. All variables referred to in expressions must have definitions. Definitions may be given in any order but the computation of “expression” must not require the use of the value of “variable name.”
There must not be multiple definitions for a single variable name. However, there is also a weak definition:
variable name ?= expression
A weak definition for variable name is used only if there is no standard definition. This allows one program file to provide a default value that another program file might or might not override.
In addition to these definitional statements, there are four directives:
include file-name
Read additional definitions from file-name, interpreted relative to the directory containing the current input file.
use(x, y, z, ...)
Mark the expressions as used, so that variable names they refer to are not printed in the program output.
print(x, y, z, ...)
Print the values of the expressions in the program output, before printing the usual output. Printing a value counts as a use of it, so print can be used to reorder the output without reordering the corresponding definitions. It is also useful for debugging.
check(x, y, z, ...)
Check that each of the expressions evaluates to the boolean value true. If not, print a message and exit.
Examples ¶
The source code directory contains example programs that demonstrate how numbers might be used to compute income taxes.
Source Files