Package com.singularsys.jep.misc

# Class MacroFunction

java.lang.Object
com.singularsys.jep.functions.PostfixMathCommand
com.singularsys.jep.misc.MacroFunction

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

public class MacroFunction extends PostfixMathCommand implements JepComponent
A function specified by a string. For example

     MacroFunction fact = new MacroFunction(
                "fact",new String[]{"x"},
                "if(x>1,x*fact(x-1),1)");
     jep.addFunction("fact",fact);
     fact.init(jep);
     Node n = jep.parse("fact(5)");

Author:
  R Morris.
See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Evaluator`
  `ev`
  `protected final String`
  `expression`
  `protected Jep`
  `jep`
  `protected NodeFactory`
  `nf`
  `protected final Node`
  `preCompiled`
  `protected SubstitutionVisitor`
  `sv`
  `protected Node`
  `topNode`
  `protected final String[]`
  `varNames`
  `protected Variable[]`
  `vars`

  ### Fields inherited from class com.singularsys.jep.functions.PostfixMathCommand

  `curNumberOfParameters, description, name, NaN, numberOfParameters`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `MacroFunction(Jep jep, String funName, String[] parameters, String expression)`
  Create a macro function with two or more arguments defined by an expression.
  `MacroFunction(Jep jep, String funName, String parameter, String expression)`
  Create a macro function with a single arguments defined by an expression.
  `MacroFunction(String funName, String[] parameters, String expression)`
  Create a macro function with two or more arguments defined by an expression.
  `MacroFunction(String funName, String[] parameters, String expression, Node root)`
  Create a MacroFunction from a node tree.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `getDescription()`
  Return a description of the function from the properties file.
  `JepComponent`
  `getLightWeightInstance()`
  Returns a new copy of the function, uses the `MacroFunction(String, String[], String, Node)` constructor.
  `String[]`
  `getParameterNames()`
  The names specified in the constructor.
  `Node`
  `getTopNode()`
  The actual expression used for evaluation, after substitution of variable names.
  `Variable[]`
  `getVars()`
  Get the internal variables used, these have specific names like 'fun::x'
  `void`
  `init(Jep j)`
  The init method must be called after construction.
  `void`
  `run(Stack<Object> stack)`
  Calculates the value of the expression.
  `void`
  `setName(String newName)`
  Change the name of a MacroFunction.
  `String`
  `toString()`
  Return a string representation of the function.

  ### Methods inherited from class com.singularsys.jep.functions.PostfixMathCommand

  `asArray, asBool, asDouble, asInt, asLong, asStrictInt, asString, asType, checkNumberOfParameters, getDescription, getDescriptionWithType, getName, getNumberOfParameters, setCurNumberOfParameters, setDescription, toString`

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

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

- ## Field Details

  - ### varNames

    protected final String[] varNames

  - ### expression

    protected final String expression

  - ### preCompiled

    protected final Node preCompiled

  - ### topNode

    protected transient Node topNode

  - ### ev

    protected transient Evaluator ev

  - ### vars

    protected transient Variable[] vars

  - ### sv

    protected transient SubstitutionVisitor sv

  - ### jep

    protected transient Jep jep

  - ### nf

    protected transient NodeFactory nf

- ## Constructor Details

  - ### MacroFunction

    public MacroFunction(Jep jep, String funName, String[] parameters, String expression)
    Create a macro function with two or more arguments defined by an expression.
    Parameters:
      `jep` - The jep instance
      `funName` - name of the function
      `parameters` - an array of the formal parameter names used by the function
      `expression` -
    Since:
      3.4.0

  - ### MacroFunction

    public MacroFunction(Jep jep, String funName, String parameter, String expression)
    Create a macro function with a single arguments defined by an expression.
    Parameters:
      `jep` - The jep instance
      `funName` - name of the function
      `parameter` - the name of the formal parameter.
      `expression` -
    Since:
      3.4.0

  - ### MacroFunction

    public MacroFunction(String funName, String[] parameters, String expression)
    Create a macro function with two or more arguments defined by an expression. Use this method for recursive functions like factorial. The `init(Jep)` method must be called after the function is added to the function table, which will recompile the function.
    Parameters:
      `funName` - name of the function
      `parameters` - an array of the formal parameter names used by the function
      `expression` -

  - ### MacroFunction

    public MacroFunction(String funName, String[] parameters, String expression, Node root)
    Create a MacroFunction from a node tree. The `init(Jep)` method must be called to compile the expression.
    Parameters:
      `funName` - function name
      `parameters` - list of parameters
      `expression` - string representation of equation
      `root` - root of expressions tree.
    Since:
      Jep 4.0

- ## Method Details

  - ### init

    public void init(Jep j)
    The init method must be called after construction. This complies the equation, either by parsing the expression, or by copying the node tree specified in the `MacroFunction(String, String[], String, Node)` constructor. Names of variables are changed to be of the form `name::varname`, or as specified by the `misc.MacroFunction.variableNameFormat` message.
    Specified by:
      `init` in interface `JepComponent`
    Parameters:
      `j` - Jep instance
    Throws:
      `JepRuntimeException` - if errors compiling the expression.

  - ### setName

    public void setName(String newName)
    Change the name of a MacroFunction. Names of all variables are also changed.
    Specified by:
      `setName` in interface `PostfixMathCommandI`
    Overrides:
      `setName` in class `PostfixMathCommand`
    Parameters:
      `newName` - the function name

  - ### run

    public void run(Stack<Object> stack) throws EvaluationException
    Calculates the value of the expression.
    Specified by:
      `run` in interface `PostfixMathCommandI`
    Overrides:
      `run` in class `PostfixMathCommand`
    Parameters:
      `stack` - arguments for function
    Throws:
      `EvaluationException` - if the calculation cannot be performed

  - ### getTopNode

    public Node getTopNode()
    The actual expression used for evaluation, after substitution of variable names.
    Returns:
      top node of expression

  - ### getParameterNames

    public String[] getParameterNames()
    The names specified in the constructor.
    Returns:
      an array of names.

  - ### getVars

    public Variable[] getVars()
    Get the internal variables used, these have specific names like 'fun::x'
    Returns:
      list of variables

  - ### toString

    public String toString()
    Description copied from class: `PostfixMathCommand`
    Return a string representation of the function. If the name is not null, return the name, otherwise return the class name.
    Overrides:
      `toString` in class `PostfixMathCommand`

  - ### getLightWeightInstance

    public JepComponent getLightWeightInstance()
    Returns a new copy of the function, uses the `MacroFunction(String, String[], String, Node)` constructor.
    Specified by:
      `getLightWeightInstance` in interface `JepComponent`
    Returns:
      either a new instance, null or 'this'.

  - ### getDescription

    public String getDescription()
    Description copied from class: `PostfixMathCommand`
    Return a description of the function from the properties file. The property name is the class name followed by ".description". The property is found using the `JepMessages` class, which can be configured to add additional properties files. If `PostfixMathCommand.setDescription(String)` has been called, return the description set by that method instead.
    Specified by:
      `getDescription` in interface `PostfixMathCommandI`
    Overrides:
      `getDescription` in class `PostfixMathCommand`
    Returns:
      the description of the function