com.eteks.parser
Class FunctionParser

java.lang.Object
  |
  +--com.eteks.parser.Parser
        |
        +--com.eteks.parser.FunctionParser

Direct Known Subclasses:

ExpressionParser, JeksFunctionParser

public class FunctionParser

extends Parser

Parser able to compile functions with parameters of the form function (list of parameters) = expression operating on parameters. The expression may contain unary or binary operators, conditions, common functions or other functions operating on literals, constants and paramaters of the function.
A parser is associated to a syntax, instance of the Syntax interface that describes the different lexicals used by the parser and their type.
The CompiledFunction compileFunction (String functionDefinition) method of this class allows to parse and compile the definition functionDefinition of a function, that must be made of the following elements :

• The function name and its parameters must be strings validated by the isValidIdentifier () method of the syntax of the parser. These strings mustn't be reserved words of the syntax of the parser, i.e. getLiteral (), getConstantKey (), getUnaryOperatorKey (), getBinaryOperatorKey (), getConditionPartKey () and getCommonFunctionKey () methods of the syntax must return null for these strings. The name of the function mustn't also be a function already defined by the syntax (the getFunction () method of the syntax must return null for the name of the function).
• The list of parameters may contain as many parameters as needed by the expression, separated by the character returned by the getParameterSeparator () method of the syntax. This list may be empty and must be bracketed between the characters returned by getOpeningBracket () and getClosingBracket () methods of the syntax.
• The declaration of the function and its parameters must be followed by the operator of assignment returned by the getAssignmentOperator () method of the syntax.
• Following the operator of assignment is the expression of the function that describes the operations to apply to the parameters, using the following syntactic elements :
  • literals (numbers, quoted strings) accepted by the getLiteral () method of the syntax
  • constants (PI true false ...) accepted by the getConstantKey () method of the syntax
  • unary operators(- ! ...) accepted by the getUnaryOperatorKey () method of the syntax
  • binary operators (- + / ...) accepted by the getBinaryOperatorKey () method of the syntax and whose priority is returned by the getBinaryOperatorPriority () method
  • conditions whose parts (? :) are accepted by the getConditionPartKey () method of the syntax
  • common functions (log sin ...) accepted by the getCommonFunctionKey () method of the syntax
  • other functions accepted by the getFunction () method of the syntax. Parameters passed to functions must be bracketed between the characters returned by getOpeningBracket () and getClosingBracket () methods of the syntax, and separated by the character returned by the getParameterSeparator () method. These functions are instances of classes implementing the Function interface. They may be classes written in Java or functions compiled previously with a parser (the CompiledFunction class implements Function).
  As the function may call itself recursively or call functions compiled previously, users may create any kind of computer operations (in the limit of the stack). Binary operators processed by this parser are infixed, unary operators and functions are prefixed. Some parts of the expression may be bracketed between the characters returned by getOpeningBracket () and getClosingBracket () methods.

White spaces returned by the getWhiteSpaceCharacters () method of the syntax may be used anywhere in the definition of the function.
If the compileFunction () method fails to compile a definition, it throws a CompilationException exception that describe the found error (syntax error or other error).
Once a funtion is compiled, the computeFunction () methods available for the returned object allow to compute its value according to the value of the parameters passed to them.

Here are a few examples of functions that can be compiled with this parser :

 // Create a parser with the syntax PascalSyntax
 FunctionParser parser = new FunctionParser (new PascalSyntax ());

 // Compile functions with this parser
 CompiledFunction f = parser.compileFunction ("F(x) = x * LN (x)");
 CompiledFunction fact = parser.compileFunction ("FACT(x) = IF x <= 0 THEN 1 ELSE x * FACT (x - 1)");
 CompiledFunction cotan = parser.compileFunction ("COTAN(x) = 1 / TAN (x)");
 // Add function cotan to be able to use it in other functions
 ((PascalSyntax)parser.getSyntax ()).addFunction (cotan);
 CompiledFunction f4 = parser.compileFunction ("F4(x,y,z) = 5.1E-1 * COTAN (X) * COTAN (Y) * COTAN (Z)");

 // Compute functions with double values
 double r1 = f.computeFunction (new double [] {2.1});
 double fact10 = fact.computeFunction (new double [] {10});
 // Compute the 100 value of cotan between 0 and Math.PI
 double cotanValues [] = new double [100];
 double cotanParam  [] = new double [1];
 for (int i = 0; i < cotanValues.length; i++)
 {
   // Use the same table for parameters to avoid useless creations of table
   cotanParam  [0] = Math.PI / i;
   cotanValues [i] = cotan.computeFunction (cotanParam).doubleValue ();
 }
 double r4 = f4.computeFunction (new double [] {1, 3, 3});

The methods of this class are thread safe.

Since:

Jeks 1.0

Version:

1.0.2

Author:

Emmanuel Puybaret

See Also:

Syntax, Function, CompiledFunction

Constructor Summary

FunctionParser()
Creates a parser for functions whose syntax is an instance of DefaultSyntax.

FunctionParser(Syntax syntax)
Creates a parser for functions with the syntax syntax.

Method Summary

CompiledFunction	compileFunction(java.lang.String functionDefinition) Compiles the definition of a function functionDefinition and returns the instance of CompiledFunction matching the definition.
Syntax	getSyntax() Returns the syntax used by this parser.

Methods inherited from class java.lang.Object

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

Constructor Detail

FunctionParser

public FunctionParser()

Creates a parser for functions whose syntax is an instance of DefaultSyntax.

FunctionParser

public FunctionParser(Syntax syntax)

Creates a parser for functions with the syntax syntax.

Parameters:

syntax - syntax of the parser.

Method Detail

getSyntax

public Syntax getSyntax()

Returns the syntax used by this parser.

Returns:

the syntax of the parser.

compileFunction

public CompiledFunction compileFunction(java.lang.String functionDefinition)
                                 throws CompilationException

Compiles the definition of a function functionDefinition and returns the instance of CompiledFunction matching the definition. This method builds a tree of type ExpressionNode matching the expression of the function. This tree is used to compute the value of a function at interpretation time.

Parameters:

functionDefinition - the definition of the function.

Returns:

an instance of CompiledFunction, with which values can be computed.

Throws:

CompilationException - if the syntax of the function is incorrect or if some elements (literals, constants, operators, functions,...) of its expression are not accepted by the syntax of the parser.