Package com.singularsys.jep

# Class PrintVisitor

java.lang.Object
com.singularsys.jep.PrintVisitor

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

Direct Known Subclasses:
  `PrintVisitor.NullPrintVisitor`

public class PrintVisitor extends Object implements ParserVisitor, JepComponent
Prints an expression with configuration options.

By default, expressions are printed with only necessary bracketing. For example, if an expression "a+(b+c)" is parsed and printed, it will be printed as `a+b+c` since the bracketing does not affect the evaluation.

Enabling the FULL_BRACKET mode prints the expression with many brackets as `((-1.0)/sqrt((1.0-(x^2.0))))`.

To use the PrintVisitor, you can invoke it through the Jep class as follows:

     Jep j = ...; Node in = ...;
     j.print(in, "x");

You can also print expressions independently from the Jep class by using this class and calling the various print methods.

Since:
  Dec 04 and NumberFormat object can be supplied to modify printing of numbers., Dec 04 PrintVisitor can now cope with 3 or more arguments to + and *., 3.3 greater customisation now possible, 4.0 Operators can implement PrintRulesI, 4.1 The NullPrintVisitor overrides addSpecialRule and getSpecialRule etc. to do nothing.
Author:
  Rich Morris Created on 20-Jun-2003
See Also:
  - `Jep.print(Node)`
  - `Jep.print(Node, PrintStream)`
  - `Jep.println(Node)`
  - `Jep.println(Node, PrintStream)`
  - `Jep.toString(Node)`
  - Printing documentation
  - Serialized Form

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `PrintVisitor.NullPrintVisitor`
  A do-nothing version of a PrintVisitor for reducing memory usage.
  `static interface`
  `PrintVisitor.PrintRulesI`
  This interface specifies the method needed to implement a special print rule.
  `static final class`
  `PrintVisitor.StdElePrintRule`
  Prints a list access in form a[3] or for multidimensional access use the list syntax.
  `static final class`
  `PrintVisitor.StdListPrintRule`
  Prints a list of elements using '[' and ']' as delimiters and ',' as a separators.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `COMPLEX_I`
  Enable this mode to print complex numbers as 3+2 i
  `protected NumberFormat`
  `format`
  The NumberFormat object used to print numbers.
  `protected FieldPosition`
  `fp`
  `static final int`
  `FULL_BRACKET`
  Enable this mode to print all brackets.
  `protected String`
  `FunctionArgSep`
  `protected String`
  `FunLBracket`
  `protected String`
  `FunRBracket`
  `protected String`
  `LBracket`
  `protected int`
  `mode`
  The current mode for printing.
  `static final PrintVisitor.NullPrintVisitor`
  `NULL_PRINT_VISITOR`
  A do-nothing PrintVisitor, useful for reducing memory usage when printing not required.
  `protected OperatorTableI`
  `ot`
  `protected String`
  `RBracket`
  `protected StringBuffer`
  `sb`
  `protected Map<String,PrintVisitor.PrintRulesI>`
  `specialFunRules`
  `protected Map<Operator,PrintVisitor.PrintRulesI>`
  `specialRules`
  `protected Map<String,String>`
  `specialVarName`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PrintVisitor()`
  Creates a visitor to create and print string representations of an expression tree.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addSpecialRule(Operator op, PrintVisitor.PrintRulesI rule)`
  Adds a special print rule to be added for a given operator.
  `void`
  `addSpecialRule(String funName, PrintVisitor.PrintRulesI rule)`
  Adds a special print rule to be added for a given function.
  `String`
  `addSpecialVarName(String oldName, String newName)`
  Allows a replacement for a specific variable name
  `void`
  `append(String s)`
  Add a string to buffer.
  `String`
  `formatValue(Object val)`
  Returns a formatted version of the value.
  `void`
  `formatValue(Object val, StringBuffer sb1)`
  Appends a formatted versions of val to the string buffer.
  `String`
  `getFunArgSep()`
  Get the string separating function arguments.
  `String`
  `getFunLBracket()`
  Get the string for left bracket around function arguments.
  `String`
  `getFunRBracket()`
  Get the string for right bracket around function arguments.
  `String`
  `getLBracket()`
  Get the string for left brackets.
  `JepComponent`
  `getLightWeightInstance()`
  Gets a light-weight instance suitable for using in multiple threads.
  `int`
  `getMaxLen()`
  `int`
  `getMode()`
  Return the current print mode.
  `boolean`
  `getMode(int testmode)`
  Returns true if the specified testmode is active.
  `String`
  `getRBracket()`
  Get the string for right brackets.
  `PrintVisitor.PrintRulesI`
  `getSpecialFunRule(String key)`
  Finds the special rule, if any, associated with an operator.
  `PrintVisitor.PrintRulesI`
  `getSpecialRule(Operator op)`
  Finds the special rule, if any, associated with an operator.
  `String`
  `getSpecialVarName(String name)`
  Finds the replacement string, if any, associated with a variable.
  `void`
  `init(Jep jep)`
  Initialize the component.
  `void`
  `print(Node node)`
  Prints on System.out.
  `void`
  `print(Node node, PrintStream out)`
  Prints the tree descending from node with lots of brackets or specified stream.
  `void`
  `printBrackets(Node node)`
  Print a node surrounded by brackets.
  `void`
  `println(Node node)`
  Prints on System.out.
  `void`
  `println(Node node, PrintStream out)`
  Prints the tree descending from node with a newline at end.
  `void`
  `printNoBrackets(Node node)`
  Print the node with no brackets.
  `void`
  `printWrap(StringBuffer sb1, PrintStream out)`
  Utility method to print a wrapped version of the output.
  `void`
  `setFunArgSep(String functionArgSep)`
  Set the string separating function arguments.
  `void`
  `setFunLBracket(String funLBracket)`
  Set the string for left bracket around function arguments.
  `void`
  `setFunRBracket(String funRBracket)`
  Set the string for right bracket around function arguments.
  `void`
  `setLBracket(String bracket)`
  Set the string for left brackets.
  `void`
  `setMaxLen(int i)`
  Sets the maximum length printed per line.
  `void`
  `setMode(int mode, boolean flag)`
  Set printing mode.
  `void`
  `setNumberFormat(NumberFormat format)`
  Sets the number format to use.
  `void`
  `setRBracket(String bracket)`
  Set the string for right brackets.
  `boolean`
  `testLeft(Operator top, Node lhs)`
  Test if brackets are necessary around left-hand side.
  `boolean`
  `testMid(Operator top, Node mid)`
  Test if brackets are needed around a middle argument `x + (y) + z`
  `boolean`
  `testRight(Operator top, Node rhs)`
  Tests if brackets are necessary around the RHS child of an operator.
  `String`
  `toString(Node node)`
  Returns a String representation of the equation.
  `Object`
  `visit(ASTConstant node, Object data)`
  `Object`
  `visit(ASTFunNode node, Object data)`
  Prints a standard function: fun(arg, arg)
  `Object`
  `visit(ASTOpNode node, Object data)`
  `Object`
  `visit(ASTVarNode node, Object data)`
  `void`
  `visit(Node node)`
  Visit a node, printing the results.
  `protected void`
  `visitBinary(ASTOpNode node)`
  `protected void`
  `visitNaryBinary(ASTFunNode node, Operator op)`
  `protected void`
  `visitUnary(ASTOpNode node)`
  Print a unary operator.

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

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

- ## Field Details

  - ### LBracket

    protected String LBracket

  - ### RBracket

    protected String RBracket

  - ### FunLBracket

    protected String FunLBracket

  - ### FunRBracket

    protected String FunRBracket

  - ### FunctionArgSep

    protected String FunctionArgSep

  - ### FULL_BRACKET

    public static final int FULL_BRACKET
    Enable this mode to print all brackets. Removes all ambiguity.
    See Also:
      - Constant Field Values

  - ### COMPLEX_I

    public static final int COMPLEX_I
    Enable this mode to print complex numbers as 3+2 i
    See Also:
      - Constant Field Values

  - ### sb

    protected transient StringBuffer sb

  - ### mode

    protected int mode
    The current mode for printing. Stores multiple flags as a bit field.

  - ### specialRules

    protected Map<Operator,PrintVisitor.PrintRulesI> specialRules

  - ### specialFunRules

    protected Map<String,PrintVisitor.PrintRulesI> specialFunRules

  - ### specialVarName

    protected Map<String,String> specialVarName

  - ### format

    protected NumberFormat format
    The NumberFormat object used to print numbers.

  - ### fp

    protected transient FieldPosition fp

  - ### ot

    protected OperatorTableI ot

  - ### NULL_PRINT_VISITOR

    public static final PrintVisitor.NullPrintVisitor NULL_PRINT_VISITOR
    A do-nothing PrintVisitor, useful for reducing memory usage when printing not required. This is static Singleton instance which can be safely be reused.
    Since:
      3.5

- ## Constructor Details

  - ### PrintVisitor

    public PrintVisitor()
    Creates a visitor to create and print string representations of an expression tree.

- ## Method Details

  - ### init

    public void init(Jep jep)
    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:
      `jep` - the current Jep instance

  - ### print

    public void print(Node node, PrintStream out)
    Prints the tree descending from node with lots of brackets or specified stream.
    See Also:
      - `Jep.println(Node, PrintStream)`

  - ### printWrap

    public void printWrap(StringBuffer sb1, PrintStream out)
    Utility method to print a wrapped version of the output. Each line will be a maximum of maxLen characters wide with lines broken on
    Parameters:
      `sb1` - the StringBuffer to print
      `out` - the output stream

  - ### print

    public void print(Node node)
    Prints on System.out.

  - ### println

    public void println(Node node, PrintStream out)
    Prints the tree descending from node with a newline at end.

  - ### println

    public void println(Node node)
    Prints on System.out.

  - ### toString

    public String toString(Node node)
    Returns a String representation of the equation.

  - ### append

    public void append(String s)
    Add a string to buffer. Classes implementing `PrintVisitor.PrintRulesI` should call this method.
    Parameters:
      `s` - the string to append
    Since:
      3.4.0

  - ### addSpecialRule

    public void addSpecialRule(Operator op, PrintVisitor.PrintRulesI rule)
    Adds a special print rule to be added for a given operator.
    Parameters:
      `op` - the operator the rule applies to
      `rule` - the print rule to use

  - ### addSpecialRule

    public void addSpecialRule(String funName, PrintVisitor.PrintRulesI rule)
    Adds a special print rule to be added for a given function.
    Parameters:
      `funName` - name of function
      `rule` - the print rule to use

  - ### getSpecialRule

    public PrintVisitor.PrintRulesI getSpecialRule(Operator op)
    Finds the special rule, if any, associated with an operator.
    Parameters:
      `op` - the Operator
    Returns:
      the rule or null, if there is no special rule

  - ### getSpecialFunRule

    public PrintVisitor.PrintRulesI getSpecialFunRule(String key)
    Finds the special rule, if any, associated with an operator.
    Parameters:
      `key` - name of the function
    Returns:
      the rule or null, if there is no special rule

  - ### getSpecialVarName

    public String getSpecialVarName(String name)
    Finds the replacement string, if any, associated with a variable.
    Parameters:
      `name` - of the variable
    Returns:
      the name or null, if there is no special name

  - ### addSpecialVarName

    public String addSpecialVarName(String oldName, String newName)
    Allows a replacement for a specific variable name
    Parameters:
      `oldName` - name of variable to replace
      `newName` - string to print as replacement

  - ### printNoBrackets

    public void printNoBrackets(Node node) throws JepException
    Print the node with no brackets.
    Throws:
      `JepException`

  - ### printBrackets

    public void printBrackets(Node node) throws JepException
    Print a node surrounded by brackets.
    Throws:
      `JepException`

  - ### visit

    public void visit(Node node) throws JepException
    Visit a node, printing the results. This method can be used by instances of PrintRulesI to print a child node.
    Parameters:
      `node` - the node to visit
    Throws:
      `JepException` - on error
    Since:
      Jep 4.1

  - ### visitUnary

    protected void visitUnary(ASTOpNode node) throws JepException
    Print a unary operator.
    Throws:
      `JepException`

  - ### visitBinary

    protected void visitBinary(ASTOpNode node) throws JepException
    Throws:
      `JepException`

  - ### testLeft

    public boolean testLeft(Operator top, Node lhs)
    Test if brackets are necessary around left-hand side.
    Parameters:
      `top` - The current operator being printed.
      `lhs` - The node on the left-hand side.
    Returns:
      True if a bracket is necessary, false otherwise.

  - ### testMid

    public boolean testMid(Operator top, Node mid)
    Test if brackets are needed around a middle argument `x + (y) + z`
    Parameters:
      `top` - The current operator being printed.
      `mid` - The node in the middle of a chain.
    Returns:
      True if a bracket is necessary, false otherwise.

  - ### testRight

    public boolean testRight(Operator top, Node rhs)
    Tests if brackets are necessary around the RHS child of an operator.
    Parameters:
      `top` - The operator.
      `rhs` - The right hand side node.
    Returns:
      True if brackets are necessary, false otherwise.

  - ### visitNaryBinary

    protected void visitNaryBinary(ASTFunNode node, Operator op) throws JepException
    Throws:
      `JepException`

  - ### visit

    public Object visit(ASTFunNode node, Object data) throws JepException
    Prints a standard function: fun(arg, arg)
    Specified by:
      `visit` in interface `ParserVisitor`
    Throws:
      `JepException`

  - ### visit

    public Object visit(ASTOpNode node, Object data) throws JepException
    Specified by:
      `visit` in interface `ParserVisitor`
    Throws:
      `JepException`

  - ### visit

    public Object visit(ASTVarNode node, Object data) throws JepException
    Specified by:
      `visit` in interface `ParserVisitor`
    Throws:
      `JepException`

  - ### visit

    public Object visit(ASTConstant node, Object data)
    Specified by:
      `visit` in interface `ParserVisitor`

  - ### formatValue

    public void formatValue(Object val, StringBuffer sb1)
    Appends a formatted versions of val to the string buffer.
    Parameters:
      `val` - The value to format
      `sb1` - The StringBuffer to append to

  - ### formatValue

    public String formatValue(Object val)
    Returns a formatted version of the value.

  - ### getMode

    public int getMode()
    Return the current print mode. Note that the mode is a bit field.

  - ### getMode

    public boolean getMode(int testmode)
    Returns true if the specified testmode is active.
    Parameters:
      `testmode` - The mode to check.
    Returns:
      True if the specified mode is active.

  - ### setMode

    public void setMode(int mode, boolean flag)
    Set printing mode. In full bracket mode the brackets each element in the tree will be surrounded by brackets to indicate the tree structure. In the default mode, (full bracket off) the number of brackets is minimized so (x+y)+z will be printed as x+y+z.
    Parameters:
      `mode` - which flags to change, typically FULL_BRACKET
      `flag` - whether to switch this mode on or off

  - ### setNumberFormat

    public void setNumberFormat(NumberFormat format)
    Sets the number format to use. A useful format is a DecimalFormat with minimum fraction digits set to zero. This makes simple powers, like x^2, print nicely.

        DecimalFormat fmt = new DecimalFormat();
        fmt.setMinimumFractionDigits(0);
        fmt.setMaximumFractionDigits(15);
        jep.getPrintVisitor().setNumberFormat(fmt);

    Parameters:
      `format` - format to use, if null just uses toString

  - ### setMaxLen

    public void setMaxLen(int i)
    Sets the maximum length printed per line. If the value is not -1 then the string will be broken into chunks each of which is less than the max length.
    Parameters:
      `i` - the maximum length

  - ### getMaxLen

    public int getMaxLen()
    Returns:
      the maximum length printed per line

  - ### getLightWeightInstance

    public JepComponent getLightWeightInstance()
    Description copied from interface: `JepComponent`
    Gets a light-weight instance suitable for using in multiple threads.
    Specified by:
      `getLightWeightInstance` in interface `JepComponent`
    Returns:
      either a new instance, null or 'this'.

  - ### getLBracket

    public String getLBracket()
    Get the string for left brackets.

  - ### setLBracket

    public void setLBracket(String bracket)
    Set the string for left brackets.

  - ### getRBracket

    public String getRBracket()
    Get the string for right brackets.

  - ### setRBracket

    public void setRBracket(String bracket)
    Set the string for right brackets.

  - ### getFunLBracket

    public String getFunLBracket()
    Get the string for left bracket around function arguments.

  - ### setFunLBracket

    public void setFunLBracket(String funLBracket)
    Set the string for left bracket around function arguments.

  - ### getFunRBracket

    public String getFunRBracket()
    Get the string for right bracket around function arguments.

  - ### setFunRBracket

    public void setFunRBracket(String funRBracket)
    Set the string for right bracket around function arguments.

  - ### getFunArgSep

    public String getFunArgSep()
    Get the string separating function arguments.

  - ### setFunArgSep

    public void setFunArgSep(String functionArgSep)
    Set the string separating function arguments.