SafsExpression (SAFS API DOCUMENT)

java.lang.Object
- org.safs.tools.expression.SafsExpression

public class SafsExpression
extends java.lang.Object

 (Copied from RRAFS StringUtilities -- the original implementation.)

      Given an expression attempt to locate variable assignment references
      and other operators and process the expressions into a result string.

      Valid operators (default values):

              ^                    '(Caret) Variable Prefix
              =                    'Assignment operator
              "                    'A single Double-Quote mark
              &                    'String concatenate operator
              +                    'Addition operator
              -                    'Subtraction operator
              *                    'Multiplication operator
              /                    'Division operator
              %                    'Modulus/Remainder operator
              (                    'Open Group operator
              )                    'Close Group operator

      Double-quote marks are used to enclose literal text strings or values.
      To include a double-quote inside a literal text string use two
      double-quote marks with no intervening characters.


      Precedence:

      Groupings ( ) are processed first.  Within groupings, and after all groups
      have been processed, operators are processed in the following order:

          * / % + - &

      The expression will be trimmed of leading and trailing whitespace on
      entry.  Use double-quote marks (literal text) to retain significant
      leading and trailing whitespace.

      Variable assignment references are identified by a leading caret (^)
      immediately followed by the name of the variable, an equal sign (=),
      and the value to assign to that variable. Whitespace can exist on either
      side of the equal sign.

      Variable names must conform to the SAFS standard (need link).

      Variable lookups(GET) and assignments(SET) will be done via the current
      SAFSVARS service or its equivalent.

      If the proposed value is NOT another variable reference then the proposed
      value will be trimmed of leading and trailing whitespace (spaces and tabs).
      And, yes, a variable can be assigned the value of another variable.

      Additionally, if there is text or operators that are not to be considered as
      variables they should be enclosed in double-quote marks.

      NOTE:
      Expressions containing groupings but no other legitimate operators may
      produce unexpected results that may not be the same on later versions of
      these routines.

Author:: Jack

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`ALL_OPERATORS` + - * / % & =
`protected boolean`	`booErrors`
`boolean`	`debugPrint`
`protected java.lang.String`	`expEncodedQuote` ((char) 11).toString()
`protected java.lang.String`	`expVarEncodedQuote` ((char) 1).toString()
`protected int`	`iExpressionlength`
`protected int`	`numDecimalPlaces` 14
`static java.lang.String`	`NUMERIC_OPERATORS` + - * / %
`protected java.lang.String`	`qt` "\""
`protected char`	`quoteEncoded` (char) 11
`protected java.lang.String`	`sExpression`
`protected java.lang.String`	`strErrors`
`protected boolean`	`stripLeadZero`
`protected boolean`	`stripTrailingDecimalPoint`
`protected boolean`	`stripTrailingZeros`
`protected SimpleVarsInterface`	`varinterface`
`protected char`	`varQuoteEncoded` (char) 1
`protected java.util.Vector`	`vQuoteLocs`
`protected java.util.Vector`	`vSubStrings`
`protected java.util.Vector`	`vVariableNames`

Constructor Summary

Constructors
Constructor and Description
`SafsExpression()` Method SafsExpression.
`SafsExpression(SimpleVarsInterface vi)` Method SafsExpression.
`SafsExpression(java.lang.String sText)` Method SafsExpression.
`SafsExpression(java.lang.String sText, SimpleVarsInterface vi)` Method SafsExpression.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected java.lang.String`	`dereferenceVariable(java.lang.String strText)` Method dereferenceVariable.
`protected java.lang.String`	`encodeDereferencedVariable(java.lang.String strText)` Method encodeDereferencedVariable.
`java.lang.String`	`evalExpression()` The main entry point to process the overall expression.
`protected java.lang.String`	`evalExpression(java.lang.String strExpr)` Recursively called with each nested parenthetical expression, if any.
`protected java.lang.String`	`evalPrimative(java.lang.String strLeftOperand, java.lang.String strOperator, java.lang.String strRightOperand)` Method evalPrimative.
`protected java.lang.String`	`evalSimple(java.lang.String strExpr)` Method evalSimple.
`java.lang.String`	`evalVariables()` Method evalVariables.
`protected java.lang.String`	`evalVariables(java.lang.String strExpr)` Method evalVariables.
`protected java.lang.String`	`extractVariables(java.lang.String strExpr)` called internally by evalVariables
`java.lang.String`	`getExpression()` Method getExpression.
`protected java.lang.String`	`getLeftOperand(java.lang.String strExpr, int iOperatorLoc)` Method getLeftOperand.
`java.util.Vector`	`getQuoteLocs()` Method getQuoteLocs.
`protected java.lang.String`	`getRightOperand(java.lang.String strExpr, int iOperatorLoc)` Method getRightOperand.
`java.util.Vector`	`getSubStrings()` Method getSubStrings.
`java.util.Vector`	`getVariableNames()` Method getVariableNames.
`SimpleVarsInterface`	`getVarInterface()` Method getVarInterface.
`protected java.lang.String`	`getVarValue(java.lang.String strVarName)` Method getVarValue.
`protected java.lang.String`	`handleOperators(java.lang.String strExpr, java.lang.String strOps)` Method handleOperators.
`protected void`	`initData(java.lang.String sText)` Method initData.
`protected boolean`	`isNumericOperator(java.lang.String sOperator)`
`static void`	`main(java.lang.String[] args)`
`int`	`numDecimalPlaces()` Method numDecimalPlaces.
`void`	`numDecimalPlaces(int i)` Method numDecimalPlaces.
`void`	`setExpression(java.lang.String sText)` Method setExpression.
`protected void`	`setVariableNames()` Method setVariableNames.
`void`	`setVarInterface(SimpleVarsInterface vi)` Method setVarInterface.
`protected java.lang.String`	`setVarValue(java.lang.String strVarName, java.lang.String strVarValue)` Method setVarValue.
`boolean`	`stripLeadZero()` Method stripLeadZero.
`void`	`stripLeadZero(boolean b)` Method stripLeadZero.
`boolean`	`stripTrailingDecimalPoint()` Method stripTrailingDecimalPoint.
`void`	`stripTrailingDecimalPoint(boolean b)` Method stripTrailingDecimalPoint.
`boolean`	`stripTrailingZeros()` Method stripTrailingZeros.
`void`	`stripTrailingZeros(boolean b)` Method stripTrailingZeros.
`protected java.lang.String`	`substituteVariables(java.lang.String strExpr)` called internally by evalVariables
`protected boolean`	`validateParens()` Method validateParens.
`protected void`	`validateQuoteMatches()`
`protected void`	`validateVariableAssignments()`
`protected void`	`validateVariableNames()` Method validateVariableNames.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - debugPrint
```
public boolean debugPrint
```
  - sExpression
```
protected java.lang.String sExpression
```
  - iExpressionlength
```
protected int iExpressionlength
```
  - varinterface
```
protected SimpleVarsInterface varinterface
```
  - vQuoteLocs
```
protected java.util.Vector vQuoteLocs
```
  - vSubStrings
```
protected java.util.Vector vSubStrings
```
  - vVariableNames
```
protected java.util.Vector vVariableNames
```
  - strErrors
```
protected java.lang.String strErrors
```
  - booErrors
```
protected boolean booErrors
```
  - stripLeadZero
```
protected boolean stripLeadZero
```
  - stripTrailingZeros
```
protected boolean stripTrailingZeros
```
  - stripTrailingDecimalPoint
```
protected boolean stripTrailingDecimalPoint
```
  - numDecimalPlaces
```
protected int numDecimalPlaces
```
    14
  - qt
```
protected final java.lang.String qt
```
    "\""
    
    See Also:
    
    Constant Field Values
  - quoteEncoded
```
protected char quoteEncoded
```
    (char) 11
  - expEncodedQuote
```
protected java.lang.String expEncodedQuote
```
    ((char) 11).toString()
  - varQuoteEncoded
```
protected char varQuoteEncoded
```
    (char) 1
  - expVarEncodedQuote
```
protected java.lang.String expVarEncodedQuote
```
    ((char) 1).toString()
  - NUMERIC_OPERATORS
```
public static final java.lang.String NUMERIC_OPERATORS
```
    + - * / %
    
    See Also:
    
    Constant Field Values
  - ALL_OPERATORS
```
public static final java.lang.String ALL_OPERATORS
```
    + - * / % & =
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - SafsExpression
```
public SafsExpression()
```
    Method SafsExpression. Basic contstructor with no arguments. Defaults sExpression to empty string.
  - SafsExpression
```
public SafsExpression(java.lang.String sText)
               throws java.lang.Exception
```
    Method SafsExpression.
    
    Parameters:
    
    sText - The SAFS string expression
    
    Throws:
    
    java.lang.Exception - Error messages such as unmatched parentheses or illegal variable names
  - SafsExpression
```
public SafsExpression(SimpleVarsInterface vi)
```
    Method SafsExpression.
    
    Parameters:
    
    vi - Any object that implements org.safs.tools.vars.SimpleVarsInterface used to get and set SAFS variables.
  - SafsExpression
```
public SafsExpression(java.lang.String sText,
                      SimpleVarsInterface vi)
               throws java.lang.Exception
```
    Method SafsExpression.
    
    Parameters:
    
    sText - The SAFS string expression
    
    vi - Any object that implements org.safs.tools.vars.SimpleVarsInterface used to get and set SAFS variables.
    
    Throws:
    
    java.lang.Exception - Error messages such as unmatched parentheses or illegal variable names
- Method Detail
  - setVarInterface
```
public void setVarInterface(SimpleVarsInterface vi)
```
    Method setVarInterface. Sets the SAFS variable interface object.
    
    Parameters:
    
    vi - Any object that implements org.safs.tools.vars.SimpleVarsInterface used to get and set SAFS variables.
  - getVarInterface
```
public SimpleVarsInterface getVarInterface()
```
    Method getVarInterface. Gets the SAFS variable interface object.
    
    Returns:
    
    SimpleVarsInterface The SAFS variable interface used to get and set variables.
  - setExpression
```
public void setExpression(java.lang.String sText)
                   throws java.lang.Exception
```
    Method setExpression. Sets the SAFS expression to a new value and initializes internals
    
    Parameters:
    
    sText - The SAFS string expression
    
    Throws:
    
    java.lang.Exception - Error messages such as unmatched parentheses or illegal variable names
  - getExpression
```
public java.lang.String getExpression()
```
    Method getExpression. Accessor for the protected field sExpression
    
    Returns:
    
    String The SAFS expression
  - getQuoteLocs
```
public java.util.Vector getQuoteLocs()
```
    Method getQuoteLocs. Accessor for the protected field vQuoteLocs
    
    Returns:
    
    Vector Integer objects containing locations of the quotes (if any)
  - getSubStrings
```
public java.util.Vector getSubStrings()
```
    Method getSubStrings. Accessor for the protected field vSubStrings
    
    Returns:
    
    Vector String objects containing quoted substrings of the expression (if any)
  - getVariableNames
```
public java.util.Vector getVariableNames()
```
    Method getVariableNames. Accessor for the protected field vVariableNames
    
    Returns:
    
    Vector String objects that are the variables found within the expression sExpression
  - stripLeadZero
```
public void stripLeadZero(boolean b)
```
    Method stripLeadZero. Setter for the protected field stripLeadZero
    sets option to strip the leading zero from expression results. For example, if the expression evaluates to 0.1 and stripLeadZero is true, the result will be formatted such that the leading zero is not shown, which would be .1
    
    Parameters:
    
    b - true or false specifying whether or not leading zeros should be stripped
  - stripLeadZero
```
public boolean stripLeadZero()
```
    Method stripLeadZero. Accessor for the protected field stripLeadZero
    
    Returns:
    
    boolean The current specified option to strip leading zeros
  - stripTrailingZeros
```
public void stripTrailingZeros(boolean b)
```
    Method stripTrailingZeros. Setter for the protected field stripTrailingZeros
    sets option to strip the trailing zeros from expression results. For example, if the expression evaluates to 1.100 and stripTrailingZeros is true, the result will be formatted such that the trailing zeros are not shown, which would be 1.1
    
    Parameters:
    
    b - true or false specifying whether or not trailing zeros should be stripped
  - stripTrailingZeros
```
public boolean stripTrailingZeros()
```
    Method stripTrailingZeros. Accessor for the protected field stripTrailingZeros
    
    Returns:
    
    boolean The current specified option to strip trailing zeros
  - stripTrailingDecimalPoint
```
public void stripTrailingDecimalPoint(boolean b)
```
    Method stripTrailingDecimalPoint. Setter for the protected field stripTrailingDecimalPoint
    sets option to strip the trailing decimal points from expression results. For example, if the expression evaluates to 1. and stripTrailingDecimalPoint is true, the result will be formatted such that the trailing zeros are not shown, which would be 1
    
    Parameters:
    
    b - true or false specifying whether or not trailing decimal points should be stripped
  - stripTrailingDecimalPoint
```
public boolean stripTrailingDecimalPoint()
```
    Method stripTrailingDecimalPoint. Accessor for the protected field stripTrailingDecimalPoint
    
    Returns:
    
    boolean The current specified option to strip trailing decimal point
  - numDecimalPlaces
```
public void numDecimalPlaces(int i)
```
    Method numDecimalPlaces. Setter for the protected field numDecimalPlaces
    
    Parameters:
    
    i - int specifying the number of decimal places to round half up in division operations
  - numDecimalPlaces
```
public int numDecimalPlaces()
```
    Method numDecimalPlaces. Accessor for the protected field numDecimalPlaces
    
    Returns:
    
    int The number of decimal places to round half up in division operations
  - evalExpression
```
public java.lang.String evalExpression()
```
    The main entry point to process the overall expression.
    
    Returns:
    
    String The result of evaluating the expression
    
    See Also:
    
    evalExpression(String)
  - evalVariables
```
public java.lang.String evalVariables()
```
    Method evalVariables. This is the method called to evaluate the expression and return the result. This is in support of old-style variable handling before expressions were allowed.
    
    Returns:
    
    String The result of evaluating the variables
  - initData
```
protected void initData(java.lang.String sText)
                 throws java.lang.Exception
```
    Method initData. Initialize internal data fields and validate the expression
    
    Parameters:
    
    sText - The SAFS string expression
    
    Throws:
    
    java.lang.Exception - Error messages such as unmatched parentheses or illegal variable names
  - isNumericOperator
```
protected boolean isNumericOperator(java.lang.String sOperator)
```
    Parameters:
    
    sOperator - The first char will be tested against known numeric operators
    
    Returns:
    
    true if the first char in sOperator is a known numeric operator.
  - setVariableNames
```
protected void setVariableNames()
```
    Method setVariableNames. Used to populate the protected field vVariableNames
  - validateParens
```
protected boolean validateParens()
```
    Method validateParens. Returns true or false specifying whether or not the expression has correctly matched parentheses
    
    Returns:
    
    boolean
  - validateVariableAssignments
```
protected void validateVariableAssignments()
```
  - validateVariableNames
```
protected void validateVariableNames()
```
    Method validateVariableNames. Make sure the variables within the expression are legally named. Set error string and flag for illegally named variables.
  - validateQuoteMatches
```
protected void validateQuoteMatches()
```
  - getVarValue
```
protected java.lang.String getVarValue(java.lang.String strVarName)
```
    Method getVarValue. Retrieve the SAFS variable value
    
    Parameters:
    
    strVarName - The name of the variable to retrieve
    
    Returns:
    
    String The value of the variable
  - setVarValue
```
protected java.lang.String setVarValue(java.lang.String strVarName,
                                       java.lang.String strVarValue)
```
    Method setVarValue. Set the specified variable to the specified value
    
    Parameters:
    
    strVarName - The name of the variable to set
    
    strVarValue - The value to set the variable to
  - evalExpression
```
protected java.lang.String evalExpression(java.lang.String strExpr)
```
    Recursively called with each nested parenthetical expression, if any.
    
    Parameters:
    
    strExpr - The expression to evaluate
    
    Returns:
    
    String The result of the evaluation
    
    See Also:
    
    evalExpression()
  - substituteVariables
```
protected java.lang.String substituteVariables(java.lang.String strExpr)
```
    called internally by evalVariables
  - extractVariables
```
protected java.lang.String extractVariables(java.lang.String strExpr)
```
    called internally by evalVariables
  - evalVariables
```
protected java.lang.String evalVariables(java.lang.String strExpr)
```
    Method evalVariables. Supports old-style variables processing when expressions are not enabled. This essentially requires that the first char of strExpr is a CARET (^). If not, the input string is returned unaltered.
    
    Parameters:
    
    strExpr - The expression to evaluate
    
    Returns:
    
    String The result of the evaluation
  - evalSimple
```
protected java.lang.String evalSimple(java.lang.String strExpr)
```
    Method evalSimple. A simple expression is one without parentheses
    
    Parameters:
    
    strExpr - The simple expression to evaluate
    
    Returns:
    
    String The simple expression evaluated
  - handleOperators
```
protected java.lang.String handleOperators(java.lang.String strExpr,
                                           java.lang.String strOps)
```
    Method handleOperators. The grunt work of handling operators at the same precedence.
    
    Parameters:
    
    strExpr - The expression to evaluate
    
    strOps - The operators to handle at the same precedence. For example "+-&" are evaluated at the same precedence.
    
    Returns:
    
    String The result of the expression evaluation
  - dereferenceVariable
```
protected java.lang.String dereferenceVariable(java.lang.String strText)
```
    Method dereferenceVariable. If strText is a variable, return its value
    
    Parameters:
    
    strText - The string to check wich may or may not be a variable
    
    Returns:
    
    String The string strText or the value of the variable if strText is a variable
  - encodeDereferencedVariable
```
protected java.lang.String encodeDereferencedVariable(java.lang.String strText)
```
    Method encodeDereferencedVariable. If strText is a variable, return its value. Encode any embedded quotes with the non-printable encoding character.
    
    Parameters:
    
    strText - The string to check which may or may not be a variable
    
    Returns:
    
    String The string strText or the value of the variable if strText is a variable
  - getRightOperand
```
protected java.lang.String getRightOperand(java.lang.String strExpr,
                                           int iOperatorLoc)
```
    Method getRightOperand. Using infix notation, the right operand is the string to the right of the operator at iOperatorLoc up to a termination character.
    
    Parameters:
    
    strExpr - The expression
    
    iOperatorLoc - The int location of the operator within strExpr
    
    Returns:
    
    String The right operand
  - getLeftOperand
```
protected java.lang.String getLeftOperand(java.lang.String strExpr,
                                          int iOperatorLoc)
```
    Method getLeftOperand. Using infix notation, the left operand is the string to the left of the operator at iOperatorLoc up to a termination character.
    
    Parameters:
    
    strExpr - The expression
    
    iOperatorLoc - The int location of the operator within strExpr
    
    Returns:
    
    String The left operand
  - evalPrimative
```
protected java.lang.String evalPrimative(java.lang.String strLeftOperand,
                                         java.lang.String strOperator,
                                         java.lang.String strRightOperand)
```
    Method evalPrimative. Primative means an expression in infix notation as "LeftOperand Operator RightOperand" only
    
    Parameters:
    
    strLeftOperand - The left operand
    
    strOperator - The operator
    
    strRightOperand - The right operand
    
    Returns:
    
    String The result of evaluating "LeftOperand Operator RightOperand"
  - main
```
public static void main(java.lang.String[] args)
```

Class SafsExpression

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

debugPrint

sExpression

iExpressionlength

varinterface

vQuoteLocs

vSubStrings

vVariableNames

strErrors

booErrors

stripLeadZero

stripTrailingZeros

stripTrailingDecimalPoint

numDecimalPlaces

qt

quoteEncoded

expEncodedQuote

varQuoteEncoded

expVarEncodedQuote

NUMERIC_OPERATORS

ALL_OPERATORS

Constructor Detail

SafsExpression

SafsExpression

SafsExpression

SafsExpression

Method Detail

setVarInterface

getVarInterface

setExpression

getExpression

getQuoteLocs

getSubStrings

getVariableNames

stripLeadZero

stripLeadZero

stripTrailingZeros

stripTrailingZeros

stripTrailingDecimalPoint

stripTrailingDecimalPoint

numDecimalPlaces

numDecimalPlaces

evalExpression

evalVariables

initData

isNumericOperator

setVariableNames

validateParens

validateVariableAssignments

validateVariableNames

validateQuoteMatches

getVarValue

setVarValue

evalExpression

substituteVariables

extractVariables

evalVariables

evalSimple

handleOperators

dereferenceVariable

encodeDereferencedVariable

getRightOperand

getLeftOperand

evalPrimative

main