Package apg

Class Parser

  • public class Parser
extends java.lang.Object
    The Parser class is used to construct a parser for a specific grammar. It is initialized with a generated Grammar class object and optional UDT and rule callback functions. Optionally, the Parser class can be configured to generate an AST, parsing statistics, and/or a trace of the syntax tree nodes processed during the parse.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      class  Parser.CallbackData
      Provisioned by the Parser for rule and UDT callback functions.
      class  Parser.Result
      Defines the Parser's results.
      static class  Parser.RuleCallback
      The base class for all rule callback functions.
      static class  Parser.UdtCallback
      Base class for all User-Defined Terminals (UDTs).

    • Constructor Summary

      Constructors 
      Constructor Description
      Parser​(Grammar grammar)
      The Parser constructor.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addAstRuleNode​(int id, int offset, int length, boolean match)
      NOTE: This function should only be called from UdtCallback or RuleCallback callback functions.
      void addAstUdtNode​(int id, int offset, int length, boolean match)
      NOTE: This function should only be called from UdtCallback or RuleCallback callback functions.
      Ast enableAst​(boolean enable)
      Enables or disables the generation of an Abstract Syntax Tree (AST).
      Statistics enableStatistics​(boolean enable)
      Enables or disables the generation of a parsing statistics.
      Trace enableTrace​(boolean enable)
      Enables or disables the generation of a Trace.
      int executeRule​(int id, int offset)
      NOTE: This function should only be called from UdtCallback or RuleCallback callback functions.
      int executeUdt​(int id, int offset)
      NOTE: This function should only be called from UdtCallback or RuleCallback callback functions.
      Parser.Result parse()
      Call this function to parser the input string.
      void setInputString​(char[] input)
      Sets the input string to be parsed.
      void setInputString​(java.lang.String input)
      Sets the input string to be parsed.
      void setMyData​(java.lang.Object data)
      Called to provision the callback functions with a user-defined data class.
      void setRuleCallback​(int id, Parser.RuleCallback callback)
      Sets the user-defined callback function to be called when processing the identified rule nodes.
      void setStartRule​(int start)
      Sets the start rule.
      void setUdtCallback​(int id, Parser.UdtCallback callback)
      Sets the user-defined callback function to be called when processing the identified UDT nodes.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • Parser

        public Parser​(Grammar grammar)
        The Parser constructor.
        Parameters:
        grammar - an instance of a Generator-generated Grammar class.

    • Method Detail

      • enableAst

        public Ast enableAst​(boolean enable)
        Enables or disables the generation of an Abstract Syntax Tree (AST). The Ast class has no public constructor and this function is the only way to generate an instance.
        Parameters:
        enable - if true, an AST will be generated, if false, not. By default enable is false.
        Returns:
        an instance of the Ast class.
        See Also:
        Ast

      • enableTrace

        public Trace enableTrace​(boolean enable)
        Enables or disables the generation of a Trace. Trace has no public constructor and this function is the only way to generate an instance.
        Parameters:
        enable - if true, an trace will be generated, if false, not. By default enable is false.
        Returns:
        an instance of the Trace class.
        See Also:
        Trace

      • enableStatistics

        public Statistics enableStatistics​(boolean enable)
        Enables or disables the generation of a parsing statistics. Statistics has no public constructor and this function is the only way to generate an instance.
        Parameters:
        enable - if true, statistics will be generated, if false, not. By default enable is false.
        Returns:
        an instance of the Statistics class.
        See Also:
        Statistics

      • setStartRule

        public void setStartRule​(int start)
                  throws java.lang.IllegalArgumentException
        Sets the start rule. By default start = 0 which identifies the first rule in the grammar definition.
        Parameters:
        start - the identifier for the desired start rule.
        Throws:
        java.lang.IllegalArgumentException - thrown if the start identifier is out of range.
        See Also:
        GeneratorGrammar.RuleNames

      • setInputString

        public void setInputString​(java.lang.String input)
        Sets the input string to be parsed. A call to this function is required prior to calling parse()
        Parameters:
        input - the input string

      • setInputString

        public void setInputString​(char[] input)
        Sets the input string to be parsed. A call to this function is required prior to calling parse()
        Parameters:
        input - the input string

      • setRuleCallback

        public void setRuleCallback​(int id,
                            Parser.RuleCallback callback)
        Sets the user-defined callback function to be called when processing the identified rule nodes.
        Parameters:
        id - identifier of the rule for which this callback is to be called.
        callback - an instance of a user-written extension of the RuleCallback class.
        See Also:
        GeneratorGrammar.RuleNames

      • setUdtCallback

        public void setUdtCallback​(int id,
                           Parser.UdtCallback callback)
        Sets the user-defined callback function to be called when processing the identified UDT nodes.
        Parameters:
        id - identifier of the UDT for which this callback is to be called.
        callback - an instance of a user-written extension of the UdtCallback class.
        See Also:
        GeneratorGrammar.UdtNames

      • setMyData

        public void setMyData​(java.lang.Object data)
        Called to provision the callback functions with a user-defined data class. null by default.
        Parameters:
        data - any object of the user's choice.

      • parse

        public Parser.Result parse()
                    throws java.lang.Exception
        Call this function to parser the input string. A call to setInputString is required prior to calling this function.
        Returns:
        a Result class with information about the parser results.
        Throws:
        java.lang.Exception - thrown if any callback function returns an illegal value. Illegal values are phrase lengths longer than the length of the remaining input string or a zero (empty) length by a UDT designated as non-empty. (UDTs having names beginning with "u_" are designated as non-empty. UDTs having names beginning with "e_" are designated as empty.)
        See Also:
        Parser.Result

      • executeRule

        public int executeRule​(int id,
                       int offset)
                throws java.lang.IllegalArgumentException,
                       java.lang.Exception
        NOTE: This function should only be called from UdtCallback or RuleCallback callback functions. Results will be unpredictable if called otherwise.

        Parses the requested rule as if it were a child node of the calling function. A call to this function alters the grammar being parsed and should be used with care.

        Parameters:
        id - grammar id of the rule to parse. Must be in the range 0 - (rule count-1).
        offset - offset of the first character in the input string of the phrase to match.
        Returns:
        the length of the matched phrase if the parse is successful. -1 otherwise. Phrase lengths must in the range 0 - (n-1), where n is the remaining string length.
        Throws:
        java.lang.IllegalArgumentException - thrown if id is out of range (see above).
        java.lang.Exception - thrown if the callback function returns an illegal value. An illegal value would be a phrase length L >= n or a zero (empty) length by a UDT designated as non-empty. (UDTs having names beginning with "u_" are designated as non-empty. UDTs having names beginning with "e_" are designated as empty.)

      • executeUdt

        public int executeUdt​(int id,
                      int offset)
               throws java.lang.Exception
        NOTE: This function should only be called from UdtCallback or RuleCallback callback functions. Results will be unpredictable if called otherwise.

        Parses the requested UDT as if it were a child node of the calling function. A call to this function alters the grammar being parsed and should be used with care.

        Parameters:
        id - grammar id of the UDT to parse. Must be in the range 0 - (UDT count-1).
        offset - offset of the first character in the input string of the phrase to match.
        Returns:
        the length of the matched phrase if the parse is successful. -1 otherwise. Phrase lengths must in the range 0 - (n-1), where n is the remaining string length.
        Throws:
        java.lang.IllegalArgumentException - thrown if id is out of range (see above).
        java.lang.Exception - thrown if the callback function returns an illegal value. An illegal value would be a phrase length L >= n or a zero (empty) length by a UDT designated as non-empty. (UDTs having names beginning with "u_" are designated as non-empty. UDTs having names beginning with "e_" are designated as empty.)

      • addAstRuleNode

        public void addAstRuleNode​(int id,
                           int offset,
                           int length,
                           boolean match)
                    throws java.lang.IllegalArgumentException,
                           java.lang.Exception
        NOTE: This function should only be called from UdtCallback or RuleCallback callback functions. Results will be unpredictable if called otherwise.

        Adds a rule node to the AST. May alter the grammar the AST is representing and should only be used with care.

        Parameters:
        id - grammar id of the rule name node to add.
        offset - offset into the input string to the first character of the phrase this node has matched.
        length - length of the matched phrase. Must not be larger than the remaining input string length.
        match - is not used.
        Throws:
        java.lang.IllegalArgumentException - thrown if the id is out of range or the
        java.lang.Exception - thrown if the callback function returns an illegal value. An illegal value would be a phrase length L >= n, where n is the remaining length of the input string, or a zero (empty) length by a UDT designated as non-empty. (UDTs having names beginning with "u_" are designated as non-empty. UDTs having names beginning with "e_" are designated as empty.)

      • addAstUdtNode

        public void addAstUdtNode​(int id,
                          int offset,
                          int length,
                          boolean match)
                   throws java.lang.IllegalArgumentException,
                          java.lang.Exception
        NOTE: This function should only be called from UdtCallback or RuleCallback callback functions. Results will be unpredictable if called otherwise.

        Adds a UDT node to the AST. May alter the grammar the AST is representing and should only be used with care.

        Parameters:
        id - grammar id of the UDT name node to add.
        offset - offset into the input string to the first character of the phrase this node has matched.
        length - length of the matched phrase. Must not be larger than the remaining input string length.
        match - is not used.
        Throws:
        java.lang.IllegalArgumentException - thrown if the id is out of range or the
        java.lang.Exception - thrown if the callback function returns an illegal value. An illegal value would be a phrase length L >= n, where n is the remaining length of the input string, or a zero (empty) length by a UDT designated as non-empty. (UDTs having names beginning with "u_" are designated as non-empty. UDTs having names beginning with "e_" are designated as empty.)