Package com.singularsys.jep.configurableparser

# Class ConfigurableParser

java.lang.Object
com.singularsys.jep.configurableparser.ConfigurableParser

All Implemented Interfaces:
  `JepComponent`, `Parser`, `Serializable`

Direct Known Subclasses:
  `ConfigurableParserWithRange`, `ParallelConfigurableParser`, `StandardConfigurableParser`

public class ConfigurableParser extends Object implements Parser
A configurable parser.

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final List<TokenFilter>`
  `filters`
  `protected final List<GrammarMatcher>`
  `g`
  `protected GrammarParserFactory`
  `gpf`
  `protected Jep`
  `jep`
  `protected final List<TokenMatcher>`
  `m`
  `protected OperatorTokenMatcher`
  `otm`
  `protected SymbolTokenMatcher`
  `stm`
  `protected TokenizerFactory`
  `tf`
  `protected Tokenizer`
  `tk`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ConfigurableParser()`
  Create a configurable parser with no matchers set.
  `ConfigurableParser(ConfigurableParser base)`
  Copy constructor, creates new lists for TokenMatchers etc. and adds all the TokenMatchers, TokenFilters, GrammarMatchers from the base.
  `ConfigurableParser(Jep j, ConfigurableParser base)`
  Create a configurable parser reusing the list of matchers from the given parser.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `GrammarMatcher`
  `addArrayAccessMatcher(String open, String close)`
  Matches array access: a[3]
  `GrammarMatcher`
  `addBracketMatcher(String open, String close)`
  Matches bracketed expressions: (2+3).
  `TokenMatcher`
  `addDoubleQuoteStrings()`
  Recognize double quote strings "...".
  `TokenMatcher`
  `addExponentNumbers()`
  Recognize numbers with optional exponents, 1.2e3, 1.2E-3, 1.2, 1.
  `GrammarMatcher`
  `addFunctionMatcher(String open, String close, String sep)`
  Matches functions: atan2(y,x).
  `GrammarMatcher`
  `addGrammarMatcher(GrammarMatcher gm)`
  Adds a GrammarMatcher
  `TokenMatcher`
  `addHashComments()`
  Recognize comments of the form #....
  `TokenMatcher`
  `addIdentifiers()`
  Adds java-style function and variable names.
  `GrammarMatcher`
  `addListMatcher(String open, String close, String sep)`
  Matches vectors/list: [1,2,3]
  `GrammarMatcher`
  `addListOrBracketMatcher(String open, String close, String sep)`
  Matches bracketed expressions or lists depending on number of arguments.
  `TokenMatcher`
  `addOperatorTokenMatcher()`
  Recognize operators.
  `TokenMatcher`
  `addSemiColonTerminator()`
  Adds a matcher which will terminate the parsing process when a semicolon is encountered.
  `TokenMatcher`
  `addSimpleNumbers()`
  Recognize numbers without exponents 1.2.
  `TokenMatcher`
  `addSingleQuoteStrings()`
  Recognize single quote strings '...'.
  `void`
  `addSlashComments()`
  Recognize comments of the form //... or /* ... */.
  `TokenMatcher`
  `addSymbols(String... symbols)`
  Recognise given set of symbols.
  `TokenFilter`
  `addTokenFilter(TokenFilter tf1)`
  Adds a TokenFilter.
  `TokenMatcher`
  `addTokenMatcher(TokenMatcher tm)`
  Adds a TokenMatcher.
  `TokenMatcher`
  `addWhiteSpace()`
  Recognize java white space characters.
  `TokenFilter`
  `addWhiteSpaceCommentFilter()`
  Filter out whitespace and comments between the tokenizing and grammar matching stages.
  `Node`
  `continueParse()`
  Parse the next expressions from existing stream.
  `Iterator<Token>`
  `filter(List<Token> input)`
  Filters the tokens to remove whitespace etc.
  `List<GrammarMatcher>`
  `getGrammarMatchers()`
  Return the list of GrammarMatchers.
  `GrammarParserFactory`
  `getGrammarParserFactory()`
  Factory used to create GrammarParsers
  `Jep`
  `getJep()`
  The Jep instance used by the parser
  `JepComponent`
  `getLightWeightInstance()`
  Returns a lightweight instance, suitable for use in multiple evaluation threads.
  `TokenMatcher`
  `getOperatorTokenMatcher()`
  Return the OperatorTokenMatcher.
  `SymbolToken`
  `getSymbolToken(String sym)`
  Return the SymbolToken for the given string.
  `SymbolTokenMatcher`
  `getSymbolTokenMatcher()`
  Return the SymbolTokenMatcher.
  `Token`
  `getToken(String sym)`
  Return the Token for the given string.
  `List<TokenFilter>`
  `getTokenFilters()`
  Return the list of filters.
  `TokenizerFactory`
  `getTokenizerFactory()`
  The factory used to create Tokenizers
  `List<TokenMatcher>`
  `getTokenMatchers()`
  Return the list of TokenMatchers
  `void`
  `init(Jep jep1)`
  Initialize the component.
  `Node`
  `parse(Reader stream)`
  Parse a single equation.
  `Node`
  `parse(Iterator<Token> it)`
  Perform the syntax analysis stage.
  `boolean`
  `replaceGrammarMatcher(Class<? extends GrammarMatcher> c, GrammarMatcher gm)`
  Replaces an existing GrammarMatcher with the new one.
  `boolean`
  `replaceTokenMatcher(Class<? extends TokenMatcher> c, TokenMatcher tm)`
  Replaces an existing TokenMatcher with the new one.
  `void`
  `restart(Reader stream)`
  Load a new stream to read from.
  `List<Token>`
  `scan()`
  Scan next equations from an existing stream.
  `List<Token>`
  `scan(Reader stream)`
  Scan the input.
  `void`
  `setGrammarParserFactory(GrammarParserFactory gpf)`
  Sets the GrammarParserFactory
  `void`
  `setImplicitMultiplicationSymbols(String... symbols)`
  Sets those symbols which can appear on the right-hand side of implicit multiplication.
  `void`
  `setTokenizerFactory(TokenizerFactory tf)`
  Sets the TokenizerFactory used to create Tokenizers.

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

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

- ## Field Details

  - ### m

    protected final List<TokenMatcher> m

  - ### filters

    protected final List<TokenFilter> filters

  - ### g

    protected final List<GrammarMatcher> g

  - ### tk

    protected transient Tokenizer tk

  - ### jep

    protected transient Jep jep

  - ### otm

    protected OperatorTokenMatcher otm

  - ### stm

    protected SymbolTokenMatcher stm

  - ### gpf

    protected GrammarParserFactory gpf

  - ### tf

    protected TokenizerFactory tf

- ## Constructor Details

  - ### ConfigurableParser

    public ConfigurableParser()
    Create a configurable parser with no matchers set.

  - ### ConfigurableParser

    public ConfigurableParser(ConfigurableParser base)
    Copy constructor, creates new lists for TokenMatchers etc. and adds all the TokenMatchers, TokenFilters, GrammarMatchers from the base. It also copies the TokenizerFactory, GrammarParserFactory, OperatorTokenMatcher and TokenizerFactory, GrammarParserFactory, OperatorTokenMatcher and SymbolTokenMatcher from the base. The jep instance is not copied and the `init(Jep)` method should be called.
    Parameters:
      `base` - the base ConfigurableParser
    Since:
      Jep 4.1
    See Also:
      - `init(Jep)`

  - ### ConfigurableParser

    public ConfigurableParser(Jep j, ConfigurableParser base)
    Create a configurable parser reusing the list of matchers from the given parser. New instances can be used in multiple threads. They have exactly the same lists of matchers as the given parser. It reuses the list of `TokenMatcher`s, `TokenFilter`s, `GrammarMatcher`s the `GrammarParserFactory` and `TokenizerFactory` and the `Jep` instance from the base parser. The `init(Jep)` method should not be called after construction and no matchers should be added to the parser.
    Parameters:
      `j` - the Jep instance to use
      `base` - the parser to copy matchers from
    Since:
      Jep 4.1

- ## Method Details

  - ### init

    public void init(Jep jep1)
    Description copied from interface: `JepComponent`
    Initialize the component. This method is called whenever a component is added to Jep. Hence, it allows components to keep track of the other components they may rely on.
    Specified by:
      `init` in interface `JepComponent`
    Parameters:
      `jep1` - the current Jep instance

  - ### parse

    public Node parse(Reader stream) throws ParseException
    Parse a single equation.
    Specified by:
      `parse` in interface `Parser`
    Parameters:
      `stream` - the input stream to read from
    Returns:
      top node of the expression
    Throws:
      `ParseException` - if there is a syntax error in the input or an empty expression

  - ### restart

    public void restart(Reader stream)
    Load a new stream to read from.
    Specified by:
      `restart` in interface `Parser`
    Parameters:
      `stream` - input stream
    See Also:
      - `continueParse()`

  - ### continueParse

    public Node continueParse() throws ParseException
    Parse the next expressions from existing stream. Empty expressions such as `;;` are silently ignored.
    Specified by:
      `continueParse` in interface `Parser`
    Returns:
      top node of the expression or null at end of file
    Throws:
      `ParseException` - if there is a syntax error in the input
    See Also:
      - `restart(java.io.Reader)`

  - ### scan

    public List<Token> scan(Reader stream) throws ParseException
    Scan the input. Just perform the tokenizing stage. Not for normal use.
    Parameters:
      `stream` - input
    Returns:
      a list of tokens, including white space and comments, null at end of input. An empty list is returned for empty equations.
    Throws:
      `ParseException` - if there is a syntax error in the input

  - ### scan

    public List<Token> scan() throws ParseException
    Scan next equations from an existing stream. Not for normal use.
    Returns:
      List of tokens, including white space and comments, null at end of input. An empty list is returned for empty equations.
    Throws:
      `ParseException` - if there is a syntax error in the input

  - ### filter

    public Iterator<Token> filter(List<Token> input) throws ParseException
    Filters the tokens to remove whitespace etc. Not for normal use.
    Parameters:
      `input` - list of tokens
    Returns:
      and iterator with the filtered tokens
    Throws:
      `ParseException` - if there is a syntax error in the input

  - ### parse

    public Node parse(Iterator<Token> it) throws ParseException
    Perform the syntax analysis stage. Not for normal used.
    Parameters:
      `it` - an iterator with a list of tokens
    Returns:
      top node of the parsed expression
    Throws:
      `ParseException` - if there is a grammatical error in the input

  - ### getLightWeightInstance

    public JepComponent getLightWeightInstance()
    Returns a lightweight instance, suitable for use in multiple evaluation threads. Always returns null.
    Specified by:
      `getLightWeightInstance` in interface `JepComponent`
    Returns:
      null

  - ### addTokenMatcher

    public TokenMatcher addTokenMatcher(TokenMatcher tm)
    Adds a TokenMatcher.
    Parameters:
      `tm` - the TokenMatcher to add
    Returns:
      the TokenMatcher

  - ### getTokenMatchers

    public List<TokenMatcher> getTokenMatchers()
    Return the list of TokenMatchers
    Returns:
      the list

  - ### addGrammarMatcher

    public GrammarMatcher addGrammarMatcher(GrammarMatcher gm)
    Adds a GrammarMatcher
    Parameters:
      `gm` - the GrammarMatcher to add
    Returns:
      the GrammarMatcher

  - ### getGrammarMatchers

    public List<GrammarMatcher> getGrammarMatchers()
    Return the list of GrammarMatchers.
    Returns:
      the list

  - ### addHashComments

    public TokenMatcher addHashComments()
    Recognize comments of the form #....
    Returns:
      the corresponding matcher.

  - ### addSlashComments

    public void addSlashComments()
    Recognize comments of the form //... or /* ... */. Does not return a given matcher.

  - ### addDoubleQuoteStrings

    public TokenMatcher addDoubleQuoteStrings()
    Recognize double quote strings "...".
    Returns:
      the corresponding matcher.

  - ### addSingleQuoteStrings

    public TokenMatcher addSingleQuoteStrings()
    Recognize single quote strings '...'.
    Returns:
      the corresponding matcher.

  - ### addWhiteSpace

    public TokenMatcher addWhiteSpace()
    Recognize java white space characters.
    Returns:
      the corresponding matcher.

  - ### addWhiteSpaceCommentFilter

    public TokenFilter addWhiteSpaceCommentFilter()
    Filter out whitespace and comments between the tokenizing and grammar matching stages.
    Returns:
      the WhiteSpaceCommentFilter

  - ### addExponentNumbers

    public TokenMatcher addExponentNumbers()
    Recognize numbers with optional exponents, 1.2e3, 1.2E-3, 1.2, 1.
    Returns:
      the corresponding matcher.

  - ### addSimpleNumbers

    public TokenMatcher addSimpleNumbers()
    Recognize numbers without exponents 1.2.
    Returns:
      the corresponding matcher.

  - ### addOperatorTokenMatcher

    public TokenMatcher addOperatorTokenMatcher()
    Recognize operators.
    Returns:
      the OperatorTokenMatcher.

  - ### getOperatorTokenMatcher

    public TokenMatcher getOperatorTokenMatcher()
    Return the OperatorTokenMatcher. Note this matcher is only added if addOperatorTokenMatcher() is called.
    Returns:
      the OperatorTokenMatcher.

  - ### addSymbols

    public TokenMatcher addSymbols(String... symbols)
    Recognise given set of symbols.
    Parameters:
      `symbols` - one or more string for the symbols.
    Returns:
      the SymbolTokenMatcher.

  - ### getSymbolTokenMatcher

    public SymbolTokenMatcher getSymbolTokenMatcher()
    Return the SymbolTokenMatcher. Note this matcher is only added if addSymbols() is called.
    Returns:
      the SymbolTokenMatcher

  - ### getSymbolToken

    public SymbolToken getSymbolToken(String sym)
    Return the SymbolToken for the given string.
    Parameters:
      `sym` - string representing the symbol.
    Returns:
      the corresponding SymbolToken.

  - ### getToken

    public Token getToken(String sym)
    Return the Token for the given string. It first searches the `OperatorTokenMatcher` if not found it searches the symbol tokens.
    Parameters:
      `sym` - string representing the symbol.
    Returns:
      either an OperatorToken or a SymbolToken
    Since:
      Jep 4.1

  - ### setImplicitMultiplicationSymbols

    public void setImplicitMultiplicationSymbols(String... symbols)
    Sets those symbols which can appear on the right-hand side of implicit multiplication.
    Parameters:
      `symbols` - one or more string for the symbols.

  - ### addIdentifiers

    public TokenMatcher addIdentifiers()
    Adds java-style function and variable names. These start with A-Z, a-z, or _ and are followed by zero or more alphanumeric characters or _.
    Returns:
      the IdentifierTokenMatcher.

  - ### addSemiColonTerminator

    public TokenMatcher addSemiColonTerminator()
    Adds a matcher which will terminate the parsing process when a semicolon is encountered.
    Returns:
      the TerminatorTokenMatcher

  - ### addBracketMatcher

    public GrammarMatcher addBracketMatcher(String open, String close)
    Matches bracketed expressions: (2+3).
    Parameters:
      `open` - symbol for opening brace
      `close` - symbol for closing brace
    Returns:
      the corresponding GrammarMatcher

  - ### addFunctionMatcher

    public GrammarMatcher addFunctionMatcher(String open, String close, String sep)
    Matches functions: atan2(y,x).
    Parameters:
      `open` - symbol for opening brace
      `close` - symbol for closing brace
      `sep` - symbol for argument separator
    Returns:
      the corresponding GrammarMatcher

  - ### addListMatcher

    public GrammarMatcher addListMatcher(String open, String close, String sep)
    Matches vectors/list: [1,2,3]
    Parameters:
      `open` - symbol for opening brace
      `close` - symbol for closing brace
      `sep` - symbol for argument separator
    Returns:
      the corresponding GrammarMatcher

  - ### addArrayAccessMatcher

    public GrammarMatcher addArrayAccessMatcher(String open, String close)
    Matches array access: a[3]
    Parameters:
      `open` - symbol for opening brace
      `close` - symbol for closing brace
    Returns:
      the corresponding GrammarMatcher

  - ### addListOrBracketMatcher

    public GrammarMatcher addListOrBracketMatcher(String open, String close, String sep)
    Matches bracketed expressions or lists depending on number of arguments.
    Parameters:
      `open` - symbol for opening brace
      `close` - symbol for closing brace
      `sep` - symbol for argument separator
    Returns:
      the corresponding GrammarMatcher

  - ### replaceTokenMatcher

    public boolean replaceTokenMatcher(Class<? extends TokenMatcher> c, TokenMatcher tm)
    Replaces an existing TokenMatcher with the new one. The first TokenMatcher that is an instance of the given class is replaced.
    Parameters:
      `c` - the class of the TokenMatcher to replace
      `tm` - the new TokenMatcher
    Returns:
      true if a TokenMatcher was replaced
    Since:
      jep 4.1

  - ### replaceGrammarMatcher

    public boolean replaceGrammarMatcher(Class<? extends GrammarMatcher> c, GrammarMatcher gm)
    Replaces an existing GrammarMatcher with the new one. The first GrammarMatcher that is an instance of the given class is replaced.
    Parameters:
      `c` - the class of the GrammarMatcher to replace
      `gm` - the new GrammarMatcher
    Returns:
      true if a GrammarMatcher was replaced
    Since:
      jep 4.1

  - ### getJep

    public Jep getJep()
    The Jep instance used by the parser
    Returns:
      the instance
    Since:
      3.4

  - ### getTokenizerFactory

    public TokenizerFactory getTokenizerFactory()
    The factory used to create Tokenizers
    Returns:
      the factory
    Since:
      3.4

  - ### setTokenizerFactory

    public void setTokenizerFactory(TokenizerFactory tf)
    Sets the TokenizerFactory used to create Tokenizers.
    Parameters:
      `tf` - factory to use
    Since:
      3.4

  - ### addTokenFilter

    public TokenFilter addTokenFilter(TokenFilter tf1)
    Adds a TokenFilter.
    Parameters:
      `tf1` - the TokenFilter to add
    Returns:
      the TokenFilter

  - ### getTokenFilters

    public List<TokenFilter> getTokenFilters()
    Return the list of filters.
    Returns:
      the list

  - ### getGrammarParserFactory

    public GrammarParserFactory getGrammarParserFactory()
    Factory used to create GrammarParsers
    Returns:
      the factory
    Since:
      3.4

  - ### setGrammarParserFactory

    public void setGrammarParserFactory(GrammarParserFactory gpf)
    Sets the GrammarParserFactory
    Parameters:
      `gpf` - the factory
    Since:
      3.4