Package adams.flow.transformer

Class SetVariable

  • 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 SetVariable
extends AbstractTransformer
implements VariableUpdater
    Sets the value of a variable. Each time a token passes through, the variable value will get updated according to the update type.
    Optionally, the specified value (or incoming value) can be expanded, in case it is made up of variables itself.
    The transformer just forwards tokens that it receives after the variable has been set.

    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)
    | contains ( str , find ) (checks whether 'str' string contains 'find' string)
    | replace ( str , pos , len , newstr )
    | replaceall ( str , regexp , replace ) (applies regular expression to 'str' and replaces all matches with 'replace')
    | 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)
    | contains ( str , find ) (checks whether 'str' string contains 'find' string)
    | replace ( str , pos , len , newstr )
    | replaceall ( str , regexp , replace ) (applies regular expression to 'str' and replaces all matches with 'replace')
    | 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)
    | contains ( str , find ) (checks whether 'str' string contains 'find' string)
    | replace ( str , pos , len , newstr )
    | replaceall ( str , regexp , replace ) (applies regular expression to 'str' and replaces all matches with 'replace')
    | 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: SetVariable
 
    -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-name <adams.core.VariableName> (property: variableName)
    The name of the variable to update.
    default: variable
 
    -var-value <adams.core.base.BaseText> (property: variableValue)
    The fixed value to use instead of the current token; only used if non-empty.
    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
 
    -update-type <REPLACE|APPEND|PREPEND> (property: updateType)
    Determines how to update the variable.
    default: REPLACE
 
    -expand-value <boolean> (property: expandValue)
    If enabled, the value (either parameter value or incoming token) gets expanded
    first in case it is made up of variables itself.
    default: false
 
    -output-value <boolean> (property: outputValue)
    If enabled, the variable values is forwarded instead of the token passing
    through.
    default: false
    Author:
    fracpete (fracpete at waikato dot ac dot nz)
    See Also:
    Serialized Form

    • Field Detail

      • m_VariableName

        protected VariableName m_VariableName
        the name of the variable.

      • m_VariableValue

        protected BaseText m_VariableValue
        the optional fixed value.

      • m_ExpandValue

        protected boolean m_ExpandValue
        whether to expand the value.

      • m_OutputValue

        protected boolean m_OutputValue
        whether to output the value.

    • Constructor Detail

      • SetVariable

        public SetVariable()
        Default constructor.

      • SetVariable

        public SetVariable​(VariableName name)
        Constructor for setting variable name.
        Parameters:
        name - the variable name

      • SetVariable

        public SetVariable​(String name)
        Constructor for setting variable name.
        Parameters:
        name - the variable name

      • SetVariable

        public SetVariable​(VariableName name,
                   BaseText value)
        Constructor for setting variable name and value.
        Parameters:
        name - the variable name
        value - the variable value

      • SetVariable

        public SetVariable​(String name,
                   String value)
        Constructor for setting variable name and value.
        Parameters:
        name - the variable name
        value - the variable value

    • Method Detail

      • setVariableName

        public void setVariableName​(String value)
        Sets the name of the variable to update.
        Parameters:
        value - the name

      • setVariableName

        public void setVariableName​(VariableName value)
        Sets the name of the variable to update.
        Parameters:
        value - the name

      • getVariableName

        public VariableName getVariableName()
        Returns the name of the variable to update.
        Returns:
        the name

      • variableNameTipText

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

      • setVariableValue

        public void setVariableValue​(String value)
        Sets the fixed value to use instead of current token.
        Parameters:
        value - the value

      • setVariableValue

        public void setVariableValue​(BaseText value)
        Sets the fixed value to use instead of current token.
        Parameters:
        value - the value

      • getVariableValue

        public BaseText getVariableValue()
        Returns the fixed value to use instead of current token.
        Returns:
        the name

      • variableValueTipText

        public String variableValueTipText()
        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.

      • setUpdateType

        public void setUpdateType​(SetVariable.UpdateType value)
        Sets how to update the variable.
        Parameters:
        value - the type

      • getUpdateType

        public SetVariable.UpdateType getUpdateType()
        Returns how to update the variable.
        Returns:
        the type

      • updateTypeTipText

        public String updateTypeTipText()
        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.

      • setOutputValue

        public void setOutputValue​(boolean value)
        Sets whether to output the variable value instead of the token passing through.
        Parameters:
        value - true if to expand

      • getOutputValue

        public boolean getOutputValue()
        Returns whether to output the variable value instead of the token passing through.
        Returns:
        true if expanded

      • outputValueTipText

        public String outputValueTipText()
        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:
        adams.flow.core.Unknown.class

      • doExecute

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

      • generates

        public Class[] generates()
        Returns the class of objects that it generates.
        Specified by:
        generates in interface OutputProducer
        Returns:
        adams.flow.core.Unknown.class