\begin{DoxyAuthor}{Author} Norman Gray $<$\href{http://nxg.me.uk}{\tt http://nxg.me.uk}$>$ \end{DoxyAuthor} The Unity package provides a parser for unit strings. {\bfseries 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 1.0), which is a C library to help parse unit specification strings such as {\ttfamily W.mm$\ast$$\ast$-\/2}. There is also an associated Java class library which uses the same grammars. For more details, see \href{http://www.astro.gla.ac.uk/users/norman/ivoa/unity/}{\tt the library's home page}; the source is on \href{https://bitbucket.org/nxg/unity}{\tt bitbucket}. As well as parsing various unit strings, the library can also serialise a parsed expression in various formats, including the four formats that it can parse, a LaTeX version with name {\ttfamily latex} (which uses the {\ttfamily \{siunitx\}} package) and a {\ttfamily debug} format which lists the parsed unit in an unambiguous, but not otherwise useful, form.\hypertarget{index_intro}{}\section{Parsing Units}\label{index_intro} 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 : \begin{DoxyDescription} \item[fits ]FITS v3.0, section 4.3, W.D. Pence et al., A\&A 524, A42, 2010 \href{http://dx.doi.org/10.1051/0004-6361/201015362}{\tt doi:10.1051/0004-\/6361/201015362} \item[ogip ]\href{ftp://legacy.gsfc.nasa.gov/fits_info/fits_formats/docs/general/ogip_93_001/ogip_93_001.ps}{\tt OGIP memo OGIP/93-\/001, 1993} \item[cds ]\href{http://cdsweb.u-strasbg.fr/doc/catstd-3.2.htx}{\tt Standards for Astronomical Catalogues, Version 2.0, section 3.2, 2000} \item[vounits ]\href{http://ivoa.net/Documents/VOUnits/}{\tt IVOA VOUnits Proposed Recommendation} \end{DoxyDescription} See also: \begin{DoxyItemize} \item The \href{http://www.iau.org/static/publications/stylemanual1989.pdf}{\tt IAU style manual, section 5.1 (1989)} is by now rather old, but appears to be one of the few existing standards for units, specific to astronomy. \item ISO/IEC 80000 (parts 1–13) describes a variety of units, including the specification of the 'binary' prefixes kibi, mebi, and so on (see ISO/IEC 80000-\/13 Sect.4, and IEEE standard 1541-\/2002). \item The VOUnits Recommendation discusses various tradeoffs and conflicting specifications, at some length. \end{DoxyItemize} Each of these has an associated {\itshape writer\/}, which allows you to write a parsed \hyperlink{struct_unit_expression}{UnitExpression} to a string, in a format which should be conformant with the particular syntax's standard. See \hyperlink{unity_8h_a65393419adce33a293a12a77d8ca5986}{unity\_\-write\_\-formatted}. In addition, there is a {\itshape latex\/} writer, which produces a formatted form for the the expression, in a form suitable for inclusion in a LaTeX document, using the {\ttfamily siunitx} package. To use the resulting output in a LaTeX document, include the following in the preamble of the \href{file:}{\tt file:} \begin{DoxyPre} $\backslash$usepackage\{siunitx\} $\backslash$DeclareSIQualifier$\backslash$solar\{\$$\backslash$odot\$\} \end{DoxyPre} You may add any {\ttfamily siunitx} options that seem convenient, and you may omit the declaration of {\ttfamily $\backslash$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 functions \hyperlink{unity_8h_ad7068b8cc977b9b79c1ecaa1507ab797}{unity\_\-check\_\-unit} and \hyperlink{unity_8h_a76f1553b4a9a2b687140deb3e99fc26a}{unity\_\-check\_\-expression}. Note that SI prefixes are still noticed for unrecognised units: thus {\ttfamily furlongs/fortnight} will be parsed as femto-\/urlongs per femto-\/ortnight. The same is not true of recognised units: a {\ttfamily pixel/s} is a pixel per second, and does not involve a pico-\/ixel.\hypertarget{index_demo}{}\subsection{Demo}\label{index_demo} If you want to experiment with the library, build the program {\ttfamily src/c/unity} (in the distribution): \begin{DoxyPre} \% ./unity -icds -oogip 'mm2/s' mm**2 /s \% ./unity -icds -ofits -v mm/s mm s-1 check: all units recognised? yes check: all units recommended? yes check: all units satisfy constraints? yes \% ./unity -ifits -ocds -v 'merg/s' merg/s check: all units recognised? yes check: all units recommended? no check: all units satisfy constraints? no \% ./unity -icds -ofits -v 'merg/s' merg s-1 check: all units recognised? no check: all units recommended? no check: all units satisfy constraints? yes \end{DoxyPre} In the latter cases, the {\ttfamily -\/v} option {\itshape validates\/} the input string against various constraints. The expression {\ttfamily mm/s} is completely valid in all the syntaxes. In the FITS syntax, the {\ttfamily 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 {\ttfamily 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).\hypertarget{index_grammars}{}\section{Grammars supported}\label{index_grammars} 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. Current limitations: \begin{DoxyItemize} \item Currently ignores some of the odder unit restrictions (such as the OGIP requirement that 'Crab' can have a 'milli' prefix, but no other SI prefixes) \end{DoxyItemize} In the grammars below, the common terminals are as follows: \begin{DoxyItemize} \item WHITESPACE: one or more whitespace characters \item STAR, DOT: a star or a dot, generally used to indicate multiplication \item DIVISION: a slash \item STARSTAR, CARET: the former is '$\ast$$\ast$'; both are used to indicate exponentiation \item OPEN\_\-P, CLOSE\_\-P: open and close parentheses \item INTEGER, FLOAT: numbers; the syntax of FLOAT is {\ttfamily \mbox{[}+-\/\mbox{]}?\mbox{[}1-\/9\mbox{]}\mbox{[}0-\/9\mbox{]}$\ast$$\backslash$$\backslash$.\mbox{[}0-\/9\mbox{]}+}, so that there are no exponents allowed; the signed integers have a non-\/optional leading sign, the unsigned don't \item STRING: a sequence of upper-\/ and lower-\/case letters \end{DoxyItemize} There are some other terminals used in some grammars. See the VOUnits specification for further details.\hypertarget{index_grammar-fits}{}\subsection{The FITS grammar}\label{index_grammar-fits} \begin{DoxyPre} input: complete\_expression | scalefactor complete\_expression | scalefactor WHITESPACE complete\_expression | division unit\_expression ;\end{DoxyPre} \begin{DoxyPre}complete\_expression: product\_of\_units | product\_of\_units division unit\_expression ;\end{DoxyPre} \begin{DoxyPre}product\_of\_units: unit\_expression | product\_of\_units product unit\_expression ;\end{DoxyPre} \begin{DoxyPre}unit\_expression: term // m(2) is m^2, not function application | STRING parenthesized\_number | function\_application | OPEN\_P complete\_expression CLOSE\_P ;\end{DoxyPre} \begin{DoxyPre}function\_application: STRING OPEN\_P complete\_expression CLOSE\_P ;\end{DoxyPre} \begin{DoxyPre}scalefactor: LIT10 power numeric\_power | LIT10 SIGNED\_INTEGER ;\end{DoxyPre} \begin{DoxyPre}division: DIVISION;\end{DoxyPre} \begin{DoxyPre}term: unit | unit numeric\_power | unit power numeric\_power ;\end{DoxyPre} \begin{DoxyPre}unit: STRING ;\end{DoxyPre} \begin{DoxyPre}power: CARET | STARSTAR ;\end{DoxyPre} \begin{DoxyPre}numeric\_power: integer | parenthesized\_number ;\end{DoxyPre} \begin{DoxyPre}parenthesized\_number: OPEN\_P integer CLOSE\_P | OPEN\_P FLOAT CLOSE\_P | OPEN\_P integer division UNSIGNED\_INTEGER CLOSE\_P ;\end{DoxyPre} \begin{DoxyPre}integer: SIGNED\_INTEGER | UNSIGNED\_INTEGER;\end{DoxyPre} \begin{DoxyPre}product: WHITESPACE | STAR | DOT; \end{DoxyPre} \hypertarget{index_grammar-ogip}{}\subsection{The OGIP grammar}\label{index_grammar-ogip} \begin{DoxyPre} input: complete\_expression | scalefactor complete\_expression | scalefactor WHITESPACE complete\_expression ;\end{DoxyPre} \begin{DoxyPre}complete\_expression: product\_of\_units ;\end{DoxyPre} \begin{DoxyPre}product\_of\_units: unit\_expression | division unit\_expression | product\_of\_units product unit\_expression | product\_of\_units division unit\_expression ;\end{DoxyPre} \begin{DoxyPre}unit\_expression: term | function\_application | OPEN\_P complete\_expression CLOSE\_P ;\end{DoxyPre} \begin{DoxyPre}function\_application: STRING OPEN\_P complete\_expression CLOSE\_P ;\end{DoxyPre} \begin{DoxyPre}scalefactor: LIT10 power numeric\_power | LIT10 | FLOAT ;\end{DoxyPre} \begin{DoxyPre}division: DIVISION | WHITESPACE DIVISION | WHITESPACE DIVISION WHITESPACE | DIVISION WHITESPACE;\end{DoxyPre} \begin{DoxyPre}term: unit | unit power numeric\_power ;\end{DoxyPre} \begin{DoxyPre}unit: STRING ;\end{DoxyPre} \begin{DoxyPre}power: STARSTAR;\end{DoxyPre} \begin{DoxyPre}numeric\_power: UNSIGNED\_INTEGER | FLOAT | parenthesized\_number ;\end{DoxyPre} \begin{DoxyPre}parenthesized\_number: OPEN\_P integer CLOSE\_P | OPEN\_P FLOAT CLOSE\_P | OPEN\_P integer division UNSIGNED\_INTEGER CLOSE\_P ;\end{DoxyPre} \begin{DoxyPre}integer: SIGNED\_INTEGER | UNSIGNED\_INTEGER;\end{DoxyPre} \begin{DoxyPre}product: WHITESPACE | STAR | WHITESPACE STAR | WHITESPACE STAR WHITESPACE | STAR WHITESPACE; \end{DoxyPre} \hypertarget{index_grammar-cds}{}\subsection{The CDS grammar}\label{index_grammar-cds} This is quite similar to the OGIP grammar, but with more restrictions. The {\ttfamily CDSFLOAT} terminal is a string matching the regular expression {\ttfamily \mbox{[}0-\/9\mbox{]}+$\backslash$$\backslash$.\mbox{[}0-\/9\mbox{]}+x10\mbox{[}-\/+\mbox{]}\mbox{[}0-\/9\mbox{]}+} (that is, something resembling {\ttfamily 1.5x10+11}). The termainals {\ttfamily OPEN\_\-SQ} and {\ttfamily CLOSE\_\-SQ} are opening and closing square brackets {\ttfamily \mbox{[}...\mbox{]}}. \begin{DoxyPre} input: complete\_expression | scalefactor complete\_expression ;\end{DoxyPre} \begin{DoxyPre}complete\_expression: product\_of\_units ;\end{DoxyPre} \begin{DoxyPre}product\_of\_units: unit\_expression | division unit\_expression | product\_of\_units product unit\_expression | product\_of\_units division unit\_expression ;\end{DoxyPre} \begin{DoxyPre}unit\_expression: term | function\_application | OPEN\_P complete\_expression CLOSE\_P ;\end{DoxyPre} \begin{DoxyPre}function\_application: OPEN\_SQ complete\_expression CLOSE\_SQ ;\end{DoxyPre} \begin{DoxyPre}scalefactor: LIT10 power numeric\_power | LIT10 SIGNED\_INTEGER | UNSIGNED\_INTEGER | LIT10 | CDSFLOAT | FLOAT ;\end{DoxyPre} \begin{DoxyPre}division: DIVISION;\end{DoxyPre} \begin{DoxyPre}term: unit | unit numeric\_power ;\end{DoxyPre} \begin{DoxyPre}unit: STRING | PERCENT ;\end{DoxyPre} \begin{DoxyPre}power: STARSTAR;\end{DoxyPre} \begin{DoxyPre}numeric\_power: integer ;\end{DoxyPre} \begin{DoxyPre}integer: SIGNED\_INTEGER | UNSIGNED\_INTEGER;\end{DoxyPre} \begin{DoxyPre}product: DOT; \end{DoxyPre} \hypertarget{index_grammar-vou}{}\subsection{The VOUnits grammar}\label{index_grammar-vou} The {\ttfamily VOUFLOAT} and {\ttfamily QUOTED\_\-STRING} features are extensions beyond the other grammars. These aside, this syntax is a strict subset of the FITS and CDS grammars, in the sense that any VOUnit unit string, without these extensions, 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. The {\ttfamily VOUFLOAT} terminal is a string matching either of the regular expressions {\ttfamily 0$\backslash$$\backslash$.\mbox{[}0-\/9\mbox{]}+(\mbox{[}eE\mbox{]}\mbox{[}+-\/\mbox{]}?\mbox{[}0-\/9\mbox{]}+)?} or {\ttfamily \mbox{[}1-\/9\mbox{]}\mbox{[}0-\/9\mbox{]}$\ast$($\backslash$$\backslash$.\mbox{[}0-\/9\mbox{]}+)?(\mbox{[}eE\mbox{]}\mbox{[}+-\/\mbox{]}?\mbox{[}0-\/9\mbox{]}+)?} (that is, something resembling, for example, {\ttfamily 0.123} or {\ttfamily 1.5e+11}). Also {\ttfamily QUOTED\_\-STRING} is a {\ttfamily STRING} enclosed in single quotes {\ttfamily '...'}. \begin{DoxyPre} input: complete\_expression | scalefactor complete\_expression ;\end{DoxyPre} \begin{DoxyPre}complete\_expression: product\_of\_units | product\_of\_units division unit\_expression ;\end{DoxyPre} \begin{DoxyPre}product\_of\_units: unit\_expression | product\_of\_units product unit\_expression ;\end{DoxyPre} \begin{DoxyPre}unit\_expression: term | function\_application | OPEN\_P complete\_expression CLOSE\_P ;\end{DoxyPre} \begin{DoxyPre}function\_application: STRING OPEN\_P complete\_expression CLOSE\_P ;\end{DoxyPre} \begin{DoxyPre}scalefactor: LIT10 power numeric\_power | LIT10 | VOUFLOAT ;\end{DoxyPre} \begin{DoxyPre}division: DIVISION;\end{DoxyPre} \begin{DoxyPre}term: unit | unit power numeric\_power ;\end{DoxyPre} \begin{DoxyPre}unit: STRING | QUOTED\_STRING | STRING QUOTED\_STRING ;\end{DoxyPre} \begin{DoxyPre}power: STARSTAR;\end{DoxyPre} \begin{DoxyPre}numeric\_power: integer | parenthesized\_number ;\end{DoxyPre} \begin{DoxyPre}parenthesized\_number: OPEN\_P integer CLOSE\_P | OPEN\_P FLOAT CLOSE\_P | OPEN\_P integer division UNSIGNED\_INTEGER CLOSE\_P ;\end{DoxyPre} \begin{DoxyPre}integer: SIGNED\_INTEGER | UNSIGNED\_INTEGER;\end{DoxyPre} \begin{DoxyPre}product: DOT; \end{DoxyPre}