Package adams.flow.transformer

Class ReportMathExpression

  • All Implemented Interfaces:
    AdditionalInformationHandler, CleanUpHandler, Destroyable, GlobalInfoSupporter, LoggingLevelHandler, LoggingSupporter, OptionHandler, QuickInfoSupporter, ShallowCopySupporter<Actor>, SizeOfHandler, Stoppable, StoppableWithFeedback, VariablesInspectionHandler, VariableChangeListener, Actor, ErrorHandler, InputConsumer, OutputProducer, GrammarSupplier, Serializable, Comparable
    public class ReportMathExpression
extends AbstractTransformer
implements GrammarSupplier
    Evaluates a mathematical expression based on report values.
    Either outputs the updated report or the report handler if that allows updating the report. The calculated value can be output by itself, if the 'outputResult' property is enabled.
    Variables are supported as well, e.g.: pow(X,@{exp}) with '@{exp}' being a variable available at execution time.

    The following grammar is used for the expressions:

    expr_list ::= '=' expr_list expr_part | expr_part ;
    expr_part ::= expr ;

    expr ::= ( expr )

    # data types
    | number
    | string
    | boolean
    | date

    # constants
    | true
    | false
    | pi
    | e
    | now()
    | today()

    # negating numeric value
    | -expr

    # comparisons
    | expr < expr
    | expr <= expr
    | expr > expr
    | expr >= expr
    | expr = expr
    | expr != expr (or: expr <> expr)

    # boolean operations
    | ! expr (or: not expr)
    | expr & expr (or: expr and expr)
    | expr | expr (or: expr or expr)
    | if[else] ( expr , expr (if true) , expr (if false) )
    | ifmissing ( variable , expr (default value if variable is missing) )
    | isNaN ( expr )

    # arithmetics
    | expr + expr
    | expr - expr
    | expr * expr
    | expr / expr
    | expr ^ expr (power of)
    | expr % expr (modulo)
    ;

    # numeric functions
    | abs ( expr )
    | sqrt ( expr )
    | cbrt ( expr )
    | log ( expr )
    | log10 ( expr )
    | exp ( expr )
    | sin ( expr )
    | sinh ( expr )
    | cos ( expr )
    | cosh ( expr )
    | tan ( expr )
    | tanh ( expr )
    | atan ( expr )
    | atan2 ( exprY , exprX )
    | hypot ( exprX , exprY )
    | signum ( expr )
    | rint ( expr )
    | floor ( expr )
    | pow[er] ( expr , expr )
    | ceil ( expr )
    | min ( expr1 , expr2 )
    | max ( expr1 , expr2 )
    | year ( expr )
    | month ( expr )
    | day ( expr )
    | hour ( expr )
    | minute ( expr )
    | second ( expr )
    | weekday ( expr )
    | weeknum ( expr )

    # string functions
    | substr ( expr , start [, end] )
    | left ( expr , len )
    | mid ( expr , start , len )
    | right ( expr , len )
    | rept ( expr , count )
    | concatenate ( expr1 , expr2 [, expr3-5] )
    | lower[case] ( expr )
    | upper[case] ( expr )
    | trim ( expr )
    | matches ( expr , regexp )
    | trim ( expr )
    | len[gth] ( str )
    | find ( search , expr [, pos] )
    | replace ( str , pos , len , newstr )
    | substitute ( str , find , replace [, occurrences] )
    ;

    Notes:
    - Variables are either all upper case letters (e.g., "ABC") or any character apart from "]" enclosed by "[" and "]" (e.g., "[Hello World]").
    - 'start' and 'end' for function 'substr' are indices that start at 1.
    - Index 'end' for function 'substr' is excluded (like Java's 'String.substring(int,int)' method)
    - Line comments start with '#'.
    - Semi-colons (';') or commas (',') can be used as separator in the formulas,
    e.g., 'pow(2,2)' is equivalent to 'pow(2;2)'
    - dates have to be of format 'yyyy-MM-dd' or 'yyyy-MM-dd HH:mm:ss'
    - times have to be of format 'HH:mm:ss' or 'yyyy-MM-dd HH:mm:ss'
    - the characters in square brackets in function names are optional:
    e.g. 'len("abc")' is the same as 'length("abc")'

    A lot of the functions have been modeled after LibreOffice:
    https://help.libreoffice.org/Calc/Functions_by_Category

    Additional functions:
    - env(String): String
       First argument is the name of the environment variable to retrieve.
       The result is the value of the environment variable.

    Additional procedures:
    - println(...)
       One or more arguments are printed as comma-separated list to stdout.
       If no argument is provided, a simple line feed is output.


    Input/output:
    - accepts:
       adams.data.report.Report
       adams.data.report.ReportHandler
    - generates:
       adams.data.report.Report
       adams.data.report.ReportHandler


    -logging-level <OFF|SEVERE|WARNING|INFO|CONFIG|FINE|FINER|FINEST> (property: loggingLevel)
    The logging level for outputting errors and debugging output.
    default: WARNING
 
    -name <java.lang.String> (property: name)
    The name of the actor.
    default: ReportMathExpression
 
    -annotation <adams.core.base.BaseAnnotation> (property: annotations)
    The annotations to attach to this actor.
    default: 
 
    -skip <boolean> (property: skip)
    If set to true, transformation is skipped and the input token is just forwarded 
    as it is.
    default: false
 
    -stop-flow-on-error <boolean> (property: stopFlowOnError)
    If set to true, the flow gets stopped in case this actor encounters an error;
     useful for critical actors.
    default: false
 
    -silent <boolean> (property: silent)
    If enabled, then no errors are output in the console.
    default: false
 
    -expression <adams.parser.MathematicalExpressionText> (property: expression)
    The mathematical expression to evaluate.
    default: 42
 
    -field <adams.data.report.Field> (property: field)
    The field in the report to update.
    default: Blah[N]
 
    -output-result <boolean> (property: outputResult)
    If enabled, then the result is output instead of the report field updated.
    default: false
    Author:
    fracpete (fracpete at waikato dot ac dot nz)
    See Also:
    MathematicalExpression, Serialized Form

    • Field Detail

      • m_Field

        protected Field m_Field
        the field for the result.

      • m_OutputResult

        protected boolean m_OutputResult
        whether to output the result instead of updating the report.

    • Constructor Detail

      • ReportMathExpression

        public ReportMathExpression()

    • Method Detail

      • getGrammar

        public String getGrammar()
        Returns a string representation of the grammar.
        Specified by:
        getGrammar in interface GrammarSupplier
        Returns:
        the grammar, null if not available

      • setExpression

        public void setExpression​(MathematicalExpressionText value)
        Sets the mathematical expression to evaluate.
        Parameters:
        value - the expression

      • getExpression

        public MathematicalExpressionText getExpression()
        Returns the mathematical expression to evaluate.
        Returns:
        the expression

      • expressionTipText

        public String expressionTipText()
        Returns the tip text for this property.
        Returns:
        tip text for this property suitable for displaying in the GUI or for listing the options.

      • setField

        public void setField​(Field value)
        Sets the field to update.
        Parameters:
        value - the field

      • getField

        public Field getField()
        Returns the field to update.
        Returns:
        the field

      • fieldTipText

        public String fieldTipText()
        Returns the tip text for this property.
        Returns:
        tip text for this property suitable for displaying in the GUI or for listing the options.

      • setOutputResult

        public void setOutputResult​(boolean value)
        Sets whether to output the result instead of updating the report field.
        Parameters:
        value - true if the result is output instead

      • getOutputResult

        public boolean getOutputResult()
        Returns whether to output the result instead of updating the report field.
        Returns:
        true if the result is output instead

      • outputResultTipText

        public String outputResultTipText()
        Returns the tip text for this property.
        Returns:
        tip text for this property suitable for displaying in the GUI or for listing the options.

      • accepts

        public Class[] accepts()
        Returns the class that the consumer accepts.
        Specified by:
        accepts in interface InputConsumer
        Returns:
        adams.data.report.Report.class, adams.data.report.ReportHandler.class

      • generates

        public Class[] generates()
        Returns the class of objects that it generates.
        Specified by:
        generates in interface OutputProducer
        Returns:
        adams.data.report.Report.class, adams.data.report.ReportHandler.class

      • doExecute

        protected String doExecute()
        Executes the flow item.
        Specified by:
        doExecute in class AbstractActor
        Returns:
        null if everything is fine, otherwise error message