Package uk.me.nxg.unity

# Class UnitParser

java.lang.Object
uk.me.nxg.unity.UnitParser

public class UnitParser extends Object
A parser for unit strings. The parser will parse a single string.

There are a number of different parsers available, enumerated in `Syntax`.

See the `uk.me.nxg.unity` package documentation for fuller discussion of the grammars.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`UnitParser.Lexeme`
A single lexeme.

## Field Summary

Fields
Modifier and Type
Field
Description
`protected boolean`
`guessUnits`

## Constructor Summary

Constructors
Constructor
Description
`UnitParser(Syntax syntax)`
Create a new unit parser.
`UnitParser(Syntax syntax, String unitString)`
Create a new unit parser and parse a unit string.

## Method Summary

Modifier and Type
Method
Description
`UnitParser.Lexeme`
`getLexeme()`
Return successive lexemes from the input.
`UnitExpr`
`getParsed()`
Retrieve the parsed result.
`static boolean`
`isKnownParser(String parser)`
Indicates whether the argument is the name of a known parser.
`void`
`lex(String unitString)`
Prepare to lex a unit string.
`static void`
`main(String[] args)`
The library main program, for exploring the library's functionality.
`UnitExpr`
`parse(String unitString)`
Parse a unit string.
`void`
`setGuessing(boolean guess_p)`
When parsing units, should we try to guess units? By default, we don't guess.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### guessUnits

protected boolean guessUnits

## Constructor Details

### UnitParser

public UnitParser(Syntax syntax, String unitString) throws UnitParserException
Create a new unit parser and parse a unit string.

The possible parser syntaxes are available from `Syntax.values()`, or can alternatively be specified using the values enumerated in `Syntax`.

Parameters:
  `syntax` - one of the known syntaxes
  `unitString` - the string to be parsed, which must be non-null
Throws:
  `UnitParserException` - if no parser can be created (typically because the required syntax is unknown), or if the string is invalid

### UnitParser

public UnitParser(Syntax syntax) throws UnitParserException
Create a new unit parser.

The possible parser syntaxes are available from `Syntax.values()`, or can alternatively be specified using the values enumerated in `Syntax`.

Parameters:
  `syntax` - one of the known syntaxes
Throws:
  `UnitParserException` - if no parser can be created (typically because the required syntax is unknown)

## Method Details

### parse

public UnitExpr parse(String unitString) throws UnitParserException
Parse a unit string.

Parameters:
  `unitString` - the non-null string to be parsed, such as `m/s-1`
Returns:
  a parsed unit
Throws:
  `UnitParserException` - if the parse fails

### lex

public void lex(String unitString)
Prepare to lex a unit string. After this is called, then `getLexeme()` may be repeatedly called to return one lexeme after another. This is primarily a debugging method.

Parameters:
  `unitString` - the string to return lexemes from

### getParsed

public UnitExpr getParsed() throws UnitParserException
Retrieve the parsed result.

This will either be the result of the last call of the `parse(java.lang.String)` method, or the parsed result if the object was created with `UnitParser(Syntax,String)`.

Returns:
  a unit expression, which will not be null
Throws:
  `UnitParserException` - if the parse fails

### isKnownParser

public static boolean isKnownParser(String parser)
Indicates whether the argument is the name of a known parser.

Parameters:
  `parser` - the string name of a parser (eg "fits")
Returns:
  true if the parser corresponds to the name of one of the elements of `Syntax`

### setGuessing

public void setGuessing(boolean guess_p)
When parsing units, should we try to guess units? By default, we don't guess. But if we are asked to guess, then unrecognised units will be re-examined with some set of heuristics so that, for example, ‘degrees’ will be recognised as the degree of angle. The set of heuristics is not specified here.

The guessing process is agnostic about which syntax it gets its guesses from. That is, even when parsing in the CDS syntax, we will still guess `ergs` as the Erg, which the CDS syntax doesn't otherwise recognise.

A guessed unit will always be a recognised unit in one or other syntax, but not necessarily the syntax this parser is configured to use. A quoted unit is never guessed (because it's by definition not a recognised unit, and because quoting is not attempted for such explicitly-marked units).

Parameters:
  `guess_p` - true to turn on guessing

### getLexeme

public UnitParser.Lexeme getLexeme() throws UnitParserException
Return successive lexemes from the input. This must follow a call to `lex(java.lang.String)`. Primarily for debugging.

Returns:
  a Lexeme object, or null when the lexemes are exhausted
Throws:
  `UnitParserException` - if there is a lexical error within the input

### main

public static void main(String[] args)
The library main program, for exploring the library's functionality.

Usage:

     UnitParser [-isyntax] [-osyntax] [-v] unit-expression

Parse and redisplay the string expression given as argument. The `-i` and `-o` flags specify the input and output syntaxes.

     UnitParser -S

List the set of available syntaxes

Parameters:
  `args` - the command-line arguments and options