Class UnitParser
- java.lang.Object
-
- uk.me.nxg.unity.UnitParser
-
public class UnitParser extends java.lang.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, java.lang.String unitString)
Create a new unit parser and parse a unit string.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description UnitParser.Lexeme
getLexeme()
Return successive lexemes from the input.UnitExpr
getParsed()
Retrieve the parsed result.static boolean
isKnownParser(java.lang.String parser)
Indicates whether the argument is the name of a known parser.void
lex(java.lang.String unitString)
Prepare to lex a unit string.static void
main(java.lang.String[] args)
The library main program, for exploring the library's functionality.UnitExpr
parse(java.lang.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.
-
-
-
Constructor Detail
-
UnitParser
public UnitParser(Syntax syntax, java.lang.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 inSyntax
.- Parameters:
syntax
- one of the known syntaxesunitString
- 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 inSyntax
.- Parameters:
syntax
- one of the known syntaxes- Throws:
UnitParserException
- if no parser can be created (typically because the required syntax is unknown)
-
-
Method Detail
-
parse
public UnitExpr parse(java.lang.String unitString) throws UnitParserException
Parse a unit string.- Parameters:
unitString
- the non-null string to be parsed, such asm/s-1
- Returns:
- a parsed unit
- Throws:
UnitParserException
- if the parse fails
-
lex
public void lex(java.lang.String unitString)
Prepare to lex a unit string. After this is called, thengetLexeme()
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 withUnitParser(Syntax,String)
.- Returns:
- a unit expression, which will not be null
- Throws:
UnitParserException
- if the parse fails
-
isKnownParser
public static boolean isKnownParser(java.lang.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 tolex(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(java.lang.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
-
-