|
||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
See:
Description
Class Summary | |
---|---|
Dimensions | A dimensions specification is a record of the measurement dimensions of a quantity. |
FunctionDefinition | Describes a function. |
FunctionDefinitionMap | Provides a mapping from function abbreviations to function definitions. |
FunctionOfUnit | Represents a function of a unit, such as log(m) . |
OneUnit | A single unit. |
SimpleUnit | A single simple unit. |
UnitDefinition | Describes a unit. |
UnitDefinitionMap | Provides a mapping from unit abbreviations to unit definitions. |
UnitExpr | A parsed unit expression. |
UnitParser | A parser for unit strings. |
UnitParser.Lexeme | A single lexeme. |
UnitRepresentation | A description of the way that a unit is represented in a particular syntax. |
Version | Manage version information |
Exception Summary | |
---|---|
UnitParserException | Thrown when an expression cannot be parsed. |
The Unity package provides a parser for unit strings.
NOTE: The library should currently be regarded as beta quality: the implementation and interface may change in response to experience and comments.
This is the unity parser (version 0.7),
which is a
Java class library
to help parse unit specification strings such as W mm^-2
.
There is also an associated
C library,
which uses the same grammars.
For more details, see
the library's home page; the source is on
bitbucket.
As well as parsing various unit strings, the library can also
serialise a parsed expression in various formats, including the three
formats that it can parse, a LaTeX version with name
latex
(which uses the {siunitx}
package) and
a debug
format which lists the parsed unit in an
unambiguous, but not otherwise useful, form.
You can parse units using a couple of different syntaxes since, unfortunately, there is no general consensus on which syntax the world should agree on. The ones supported (and their names within this library) are as follows:
See also the IAU style manual, section 5.1, 1989, though this is by now rather old.
Each of these has an associated writer, which allows you to
write a parsed UnitExpression to a string, in a format which should be
conformant with the particular syntax's standard.
See UnitExpr.toString()
.
In addition, there is a latex writer, which produces a
formatted form for the the expression, in a form suitable for
inclusion in a LaTeX document, using the siunitx
package. To use the resulting output in a LaTeX document, include the
following in the preamble of the file:
\usepackage{siunitx} \DeclareSIQualifier\solar{$\odot$}
You may add any siunitx
options that seem convenient,
and you may omit the declaration of \solar
if the units
in the document do not include the various solar ones.
The parsing is permissive, to the extent that it permits non-recognised and deprecated
units. The result of the parse may be checked for conformance with
one or other standard using
the methods
UnitExpr.allUnitsRecognised(java.lang.String)
,
UnitExpr.allUnitsRecommended(java.lang.String)
and
UnitExpr.allUsageConstraintsSatisfied(java.lang.String)
.
Note that SI prefixes are still noticed for unrecognised units: thus furlongs/fortnight
will be parsed as femto-urlongs per femto-ortnight. The same is not
true of recognised units: a pixel/s
is a pixel per
second, and does not involve a pico-ixel.
If you want to experiment with the library, you can do so using the jar file:
% java -jar unity.jar -icds -oogip 'mm2/s' mm**2 /s % java -jar unity.jar -icds -ofits -v mm/s mm s-1 check: all units recognised? yes check: all units recommended? yes check: all units satisfy constraints? yes % java -jar unity.jar -ifits -ocds -v 'merg/s' merg/s check: all units recognised? yes check: all units recommended? no check: all units satisfy constraints? no % java -jar unity.jar -icds -ofits -v 'merg/s' merg s-1 check: all units recognised? no check: all units recommended? no check: all units satisfy constraints? yes
In the latter cases, the -v
option validates the input string
against various constraints. The expression mm/s
is completely valid
in all the syntaxes. In the FITS syntax, the erg
is a recognised
unit, but it is deprecated; although it is recognised, it is not
permitted to have SI prefixes. In the CDS syntax, the erg
is neither
recognised nor (a fortiori) recommended; since there are no
constraints on it in this syntax, it satisfies all of them (this
latter behaviour is admittedly slightly counterintuitive).
The four supported grammars have a fair amount in common, but the differences are nonetheless significant enough that they require separate grammars. Important differences are in the number of solidi they allow in the units specifications, and the symbols they use for products and powers.
The CDS specification permits non-round factors (that is, factors which aren't a power of ten). These are not permitted in this CDS parser, partly because they're arguably quantities rather than units, but more practically because it significantly complicates the implementation.
Current limitations:
In the grammars below, the terminals are as follows:
[+-]?[1-9][0-9]*\.[0-9]+
-- that is, there are no
exponents allowed; the signed integers have a non-optional leading
sign, the unsigned don't[0-9]+\.[0-9]+x10[-+][0-9]+
input: complete_expression | scalefactor complete_expression | scalefactor WHITESPACE complete_expression | division unit_expression ; complete_expression: product_of_units | product_of_units division unit_expression ; product_of_units: unit_expression | product_of_units product unit_expression ; unit_expression: unit | STRING OPEN_P complete_expression CLOSE_P | OPEN_P complete_expression CLOSE_P ; scalefactor: LIT10 power numeric_power | LIT10 SIGNED_INTEGER ; division: DIVISION; unit: STRING | STRING power numeric_power | STRING numeric_power ; power: CARET | STARSTAR ; numeric_power: integer | OPEN_P integer CLOSE_P | OPEN_P FLOAT CLOSE_P | OPEN_P integer division UNSIGNED_INTEGER CLOSE_P ; integer: SIGNED_INTEGER | UNSIGNED_INTEGER; product: WHITESPACE | STAR | DOT;
input: complete_expression | scalefactor complete_expression | scalefactor WHITESPACE complete_expression ; complete_expression: product_of_units ; product_of_units: unit_expression | division unit_expression | product_of_units product unit_expression | product_of_units division unit_expression ; unit_expression: unit | STRING OPEN_P complete_expression CLOSE_P | OPEN_P complete_expression CLOSE_P ; scalefactor: LIT10 power numeric_power | LIT10 | FLOAT ; division: DIVISION | WHITESPACE DIVISION | WHITESPACE DIVISION WHITESPACE | DIVISION WHITESPACE; unit: STRING | STRING power numeric_power ; power: STARSTAR; numeric_power: UNSIGNED_INTEGER | FLOAT | OPEN_P integer CLOSE_P | OPEN_P FLOAT CLOSE_P | OPEN_P integer division UNSIGNED_INTEGER CLOSE_P ; integer: SIGNED_INTEGER | UNSIGNED_INTEGER; product: WHITESPACE | STAR | WHITESPACE STAR | WHITESPACE STAR WHITESPACE | STAR WHITESPACE;
This is quite similar to the OGIP grammar, but with more restrictions
input: complete_expression | scalefactor complete_expression ; complete_expression: product_of_units ; product_of_units: unit_expression | division unit_expression | product_of_units product unit_expression | product_of_units division unit_expression ; unit_expression: unit | OPEN_SQ complete_expression CLOSE_SQ | OPEN_P complete_expression CLOSE_P ; scalefactor: LIT10 power numeric_power | LIT10 SIGNED_INTEGER | UNSIGNED_INTEGER | LIT10 | CDSFLOAT | FLOAT ; division: DIVISION; unit: STRING | STRING numeric_power ; power: STARSTAR; numeric_power: integer ; integer: SIGNED_INTEGER | UNSIGNED_INTEGER; product: DOT;
This is intended to be as nearly as possible in the intersection of the various grammars above. It is a strict subset of the FITS and CDS grammars (in the sense that any VOUnit unit string is a valid FITS and CDS string, too), and it is almost a subset of the OGIP grammar, except that it uses the dot for multiplication rather than star.
input: complete_expression | scalefactor complete_expression | division unit_expression ; complete_expression: product_of_units | product_of_units division unit_expression ; product_of_units: unit_expression | product_of_units product unit_expression ; unit_expression: unit | STRING OPEN_P complete_expression CLOSE_P | OPEN_P complete_expression CLOSE_P ; scalefactor: LIT10 power numeric_power ; division: DIVISION; unit: STRING | STRING power numeric_power ; power: STARSTAR; numeric_power: integer | OPEN_P integer CLOSE_P | OPEN_P FLOAT CLOSE_P | OPEN_P integer division UNSIGNED_INTEGER CLOSE_P ; integer: SIGNED_INTEGER | UNSIGNED_INTEGER; product: DOT;
|
||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |