(units.info)Defining new units
7 Defining new units
All of the units and prefixes that `units' can convert are defined in
the units data file. If you want to add your own units, you can supply
your own file. You can also add your own units definitions in the
`.units.dat' file in your home directory. If this file exists it is
read before the units data file. It will not be read if any units
files are specified on the command line.
A unit is specified on a single line by giving its name and an
equivalence. Comments start with a `#' character, which can appear
anywhere in a line. The backslash character (`\') acts as a
continuation character if it appears as the last character on a line,
making it possible to spread definitions out over several lines if
desired. A file can be included by giving the command `!include'
followed by the file's name. The file will be sought in the same
directory as the parent file unless a full path is given.
Unit names must not contain any of the operator characters `+', `-',
`*', `/', `|', `^' or the parentheses. They cannot begin with a digit
or a decimal point (`.'), nor can they end with a digit (except for
zero). Be careful to define new units in terms of old ones so that a
reduction leads to the primitive units, which are marked with `!'
characters. Dimensionless units are indicated by using the string
`!dimensionless' for the unit definition.
When adding new units, be sure to use the `-c' option to check that
the new units reduce properly. If you create a loop in the units
definitions, then `units' will hang when invoked with the `-c' options.
You will need to use the `--check-verbose' option which prints out each
unit as it checks them. The program will still hang, but the last unit
printed will be the unit which caused the infinite loop.
If you define any units which contain `+' characters, carefully
check them because the `-c' option will not catch non-conformable sums.
Be careful with the `-' operator as well. When used as a binary
operator, the `-' character can perform addition or multiplication
depending on the options used to invoke `units'. To ensure consistent
behavior use `-' only as a unary negation operator when writing units
definitions. To multiply two units leave a space or use the `*'
operator with care, recalling that it has two possible precedence
values and may require parentheses to ensure consistent behavior. To
compute the difference of `foo' and `bar' write `foo+(-bar)' or even
Here is an example of a short units file that defines some basic
m ! # The meter is a primitive unit
sec ! # The second is a primitive unit
rad !dimensionless # A dimensionless primitive unit
micro- 1e-6 # Define a prefix
minute 60 sec # A minute is 60 seconds
hour 60 min # An hour is 60 minutes
inch 0.0254 m # Inch defined in terms of meters
ft 12 inches # The foot defined in terms of inches
mile 5280 ft # And the mile
A unit which ends with a `-' character is a prefix. If a prefix
definition contains any `/' characters, be sure they are protected by
parentheses. If you define `half- 1/2' then `halfmeter' would be
equivalent to `1 / 2 meter'.
automatically generated by info2www version 18.104.22.168