This release brings a new feature to Rule Machine: Rule Functions. A Rule Function is a special type of rule, one that can be called by another Rule or Button Rule, with an optional parameter, and returns a value to the calling rule. Rule Functions don't have Triggers or Required Expressions, only Actions. A new Action, Return Value is available, and the value returned can be String, Integer, Decimal or Boolean.
Initial Rule Function setup
To create a Rule Function, simply flip the selector input at the top of the rule:
Once selected, the layout of the rule is updated to omit Triggers and Required Expression, and adds a built in Function Param shown in the Local Variables table. When first defining such a Rule Function, the Function Param won't have a value, as the Rule Function will obtain that value when it is called with a parameter.
To pass a parameter to the Rule Function, a Hub Variable is selected . The value of that Hub Variable is available within the rule with %param%. In order to use that value it will most likely need to be assigned to an appropriate variable (local or Hub Variable), using a String option to set a variable. For example, here the Rule Function is expecting a DateTime value as its parameter, and it assigns that to a local variable:
In this screenshot, the Rule Function has not been called yet, so the actions have not run, the datex variable has not been set and %param% is null.
Once the Rule Function has been called, the value of datex has been updated, and the rule returns the parameter as a String. This is not a meaningful Rule Function, but shown to illustrate the nature of what you'll see as you build these.
Rule Functions have a special action available only to them, Return Value. Return Value allows the selection of String, Integer, Decimal or Boolean values to return, allowing either an explicit value or a variable of the appropriate type to be selected:
There are appropriate input selections for each type:
Using Rule Function in a Rule or Button Rule
To use a Rule Function in another rule, you will find Rule Function as an option for setting a variable (except for DateTime variables, which are not supported in this release). Rule Functions are also available to be used in Button Rules under Button Controller 5.1. The selector is part of Set Variable String Operations, and looks like this:
And then we can select the Rule Function from a drop-down, and the optional parameter variable from another droop-down.
And results in this Action:
Real Example
A user wanted a way to take a number of seconds, and turn it into a meaningful representation of hours, minutes and seconds. This Rule Function does this, and you can see why you would not want to embed these actions in many rules. Using a Rule Function allows this rather dirty set of actions to be used in any number of rules that have a need to change a number of seconds into such a time representation:
This example has to deal with values that return just seconds (e.g., < 60), or ones with minutes and seconds but not hours, and deal with leading zeros that might be needed (it is messy).
Update: The original Actions I posted above had bugs in it (gasp), I fixed the ones I found. RM was not intended to serve as a programming language, and it's actually harder to do the Pretty Print Seconds in RM than it is in Groovy.
