Class SetManyVariables

  • All Implemented Interfaces:
    AdditionalInformationHandler, CleanUpHandler, Destroyable, GlobalInfoSupporter, LoggingLevelHandler, LoggingSupporter, OptionHandler, QuickInfoSupporter, ShallowCopySupporter<Actor>, SizeOfHandler, Stoppable, StoppableWithFeedback, VariablesInspectionHandler, VariableUpdater, VariableChangeListener, Actor, ErrorHandler, InputConsumer, OutputProducer, Serializable, Comparable

    public class SetManyVariables
    extends AbstractTransformer
    implements VariableUpdater
    Sets the values of the variables whenever a token passes through, but does not use the token's value.
    Optionally, the specified values can be expanded, in case it is made up of variables itself.

    Grammar for mathematical expressions (value type 'MATH_EXPRESSION, MATH_EXPRESSION_ROUND'):

    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) )
    | has ( variable )
    | 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] ) (find 'search' in 'expr', return 1-based position)
    | replace ( str , pos , len , newstr )
    | substitute ( str , find , replace [, occurrences] )
    | str ( expr )
    | str ( expr , numdecimals )
    | str ( expr , decimalformat )
    | ext ( file_str ) (extracts extension from file)
    | replaceext ( file_str, ext_str ) (replaces the extension of the file with the new one)
    ;

    Notes:
    - Variables are either all alphanumeric and _, starting with uppercase letter (e.g., "ABc_12"),
    any character apart from "]" enclosed by "[" and "]" (e.g., "[Hello World]") or
    enclosed by single quotes (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")'
    - 'str' uses java.text.DecimalFormat when supplying a format string

    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.


    Grammar for boolean expressions (value type 'BOOL_EXPRESSION'):

    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) )
    | has ( variable )
    | 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] ) (find 'search' in 'expr', return 1-based position)
    | replace ( str , pos , len , newstr )
    | substitute ( str , find , replace [, occurrences] )
    | str ( expr )
    | str ( expr , numdecimals )
    | str ( expr , decimalformat )
    | ext ( file_str ) (extracts extension from file)
    | replaceext ( file_str, ext_str ) (replaces the extension of the file with the new one)

    # array functions
    | len[gth] ( array )
    | get ( array , index )
    ;

    Notes:
    - Variables are either all alphanumeric and _, starting with uppercase letter (e.g., "ABc_12"),
    any character apart from "]" enclosed by "[" and "]" (e.g., "[Hello World]") or
    enclosed by single quotes (e.g., "'Hello World'").
    - 'start' and 'end' for function 'substr' are indices that start at 1.
    - 'index' for function 'get' starts 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")'
    - 'str' uses java.text.DecimalFormat when supplying a format string

    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.


    Grammar for string expressions (value type 'STRING_EXPRESSION'):

    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) )
    | has ( variable )
    | 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] ) (find 'search' in 'expr', return 1-based position)
    | replace ( str , pos , len , newstr )
    | substitute ( str , find , replace [, occurrences] )
    | str ( expr )
    | str ( expr , numdecimals )
    | str ( expr , decimalformat )
    | ext ( file_str ) (extracts extension from file)
    | replaceext ( file_str, ext_str ) (replaces the extension of the file with the new one)

    # array functions
    | len[gth] ( array )
    | get ( array , index )
    ;

    Notes:
    - Variables are either all alphanumeric and _, starting with uppercase letter (e.g., "ABc_12"),
    any character apart from "]" enclosed by "[" and "]" (e.g., "[Hello World]") or
    enclosed by single quotes (e.g., "'Hello World'").
    - 'start' and 'end' for function 'substr' are indices that start at 1.
    - 'index' for function 'get' starts 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")'
    - 'str' uses java.text.DecimalFormat when supplying a format string

    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.flow.core.Unknown
    - generates:
       adams.flow.core.Unknown


    -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: SetManyVariables
     
    -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 execution at this level gets stopped in case this
        actor encounters an error; the error gets propagated; useful for critical
        actors.
        default: false
     
    -silent <boolean> (property: silent)
        If enabled, then no errors are output in the console; Note: the enclosing
        actor handler must have this enabled as well.
        default: false
     
    -var-pair <adams.core.VariableNameValuePair> [-var-pair ...] (property: variablePairs)
        The name/value pairs of the variables to update.
        default:
     
    -value-type <STRING|MATH_EXPRESSION|MATH_EXPRESSION_ROUND|BOOL_EXPRESSION|STRING_EXPRESSION|FILE_FORWARD_SLASHES> (property: valueType)
        How to interpret the 'value' string.
        default: STRING
     
    -expand-value <boolean> (property: expandValue)
        If enabled, the value gets expanded first in case it is made up of variables
        itself.
        default: false
     
    Version:
    $Revision$
    Author:
    fracpete (fracpete at waikato dot ac dot nz)
    See Also:
    Serialized Form
    • Field Detail

      • m_ExpandValue

        protected boolean m_ExpandValue
        whether to expand the value.
    • Constructor Detail

      • SetManyVariables

        public SetManyVariables()
    • Method Detail

      • addVariablePair

        public void addVariablePair​(VariableNameValuePair value)
        Adds the variable name/value pair.
        Parameters:
        value - the pair to add
      • setVariablePairs

        public void setVariablePairs​(VariableNameValuePair[] value)
        Sets the variable (name/value) pairs.
        Parameters:
        value - the pairs
      • getVariablePairs

        public VariableNameValuePair[] getVariablePairs()
        Returns the variable (name/value) pairs.
        Returns:
        the pairs
      • variablePairsTipText

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

        public void setValueType​(VariableValueType value)
        Sets how to interpret the value string.
        Parameters:
        value - the type
      • getValueType

        public VariableValueType getValueType()
        Returns how to interpret the value string.
        Returns:
        the type
      • valueTypeTipText

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

        public void setExpandValue​(boolean value)
        Sets whether to expand the value before settting it (eg if it is made up of variables itself).
        Parameters:
        value - true if to expand
      • getExpandValue

        public boolean getExpandValue()
        Returns whether the value gets expanded before setting it (eg if it is made up of variables itself).
        Returns:
        true if expanded
      • expandValueTipText

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

        public boolean isUpdatingVariables()
        Returns whether variables are being updated.
        Specified by:
        isUpdatingVariables in interface VariableUpdater
        Returns:
        true if variables are updated
      • accepts

        public Class[] accepts()
        Returns the class that the consumer accepts.
        Specified by:
        accepts in interface InputConsumer
        Returns:
        the Class of objects that can be processed
      • generates

        public Class[] generates()
        Returns the class of objects that it generates.
        Specified by:
        generates in interface OutputProducer
        Returns:
        the Class of the generated tokens
      • doExecute

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