Class 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.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • guessUnits

        protected boolean guessUnits
    • 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 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 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 as m/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, 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
      • 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
      • 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