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.

  • 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