actions/MathActions.js

  1. /**
  2.  *  MathActions - Actions that calculate math
  3.  * 
  4.  *  This code is licensed under the MIT License (MIT).
  5.  *  
  6.  *  Copyright 2020, 2021, 2022 Rolf Bagge, Janus B. Kristensen, CAVI,
  7.  *  Center for Advanced Visualization and Interaction, Aarhus University
  8.  *  
  9.  *  Permission is hereby granted, free of charge, to any person obtaining a copy
  10.  *  of this software and associated documentation files (the “Software”), to deal
  11.  *  in the Software without restriction, including without limitation the rights 
  12.  *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
  13.  *  copies of the Software, and to permit persons to whom the Software is 
  14.  *  furnished to do so, subject to the following conditions:
  15.  *  
  16.  *  The above copyright notice and this permission notice shall be included in 
  17.  *  all copies or substantial portions of the Software.
  18.  *  
  19.  *  THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
  20.  *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
  21.  *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
  22.  *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
  23.  *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
  24.  *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 
  25.  *  THE SOFTWARE.
  26.  *  
  27.  */
  29. /**
  30.  * Actions that do math
  31.  * @namespace MathActions
  32.  */
  34. class IncrementDecrementAction extends Action {
  35.     constructor(name, decrement, options, concept) {
  36.         // Handle string shorthand
  37.         if(typeof options === "string"){
  38.             options = {
  39.                 property: options
  40.             }
  41.         }
  43.         const defaultOptions = {
  44.             by: 1
  45.         }
  47.         super(name, Object.assign({}, defaultOptions, options), concept);
  49.         this.decrement = decrement;
  50.     }
  52.     /**
  53.      * @param {VarvContext[]} context
  54.      * @returns {Promise<VarvContext[]>}
  55.      */
  56.     async apply(contexts, actionArguments = {}) {
  57.         const self = this;
  59.         if(this.options.property == null && this.options.variable == null) {
  60.             throw new Error("Either 'property' or 'variable' needs to be set for action 'increment'");
  61.         }
  63.         return this.forEachContext(contexts, actionArguments, async (context, options)=>{
  64.             if(options.property != null) {
  65.                 const lookup = await VarvEngine.lookupProperty(context.target, self.concept, options.property);
  67.                 if(lookup == null) {
  68.                     throw new Error("No property ["+options.of.property+"] found");
  69.                 }
  71.                 const concept = lookup.concept;
  72.                 const property = lookup.property;
  73.                 const target = lookup.target;
  75.                 let currentValue = await property.getValue(target);
  77.                 if (this.decrement) {
  78.                     currentValue -= options.by;
  79.                 } else {
  80.                     currentValue += options.by;
  81.                 }
  83.                 await property.setValue(target, currentValue);
  84.             } else if(options.variable != null) {
  85.                 let currentValue = Action.getVariable(context, options.variable);
  87.                 if (this.decrement) {
  88.                     currentValue -= options.by;
  89.                 } else {
  90.                     currentValue += options.by;
  91.                 }
  93.                 Action.setVariable(context, options.variable, currentValue);
  94.             }
  96.             return context;
  97.         });
  98.     }
  99. }
  101. /**
  102.  * An action "increment" that increments a number property or variable
  103.  * @memberOf MathActions
  104.  * @example
  105.  * // Increment the property by 1
  106.  * {
  107.  *     "increment": {
  108.  *         "property": "myNumberProperty"
  109.  *     }
  110.  * }
  111.  *
  112.  * @example
  113.  * // Increment the property by 2
  114.  * {
  115.  *     "increment": {
  116.  *         "property": "myNumberProperty",
  117.  *         "by": 2
  118.  *     }
  119.  * }
  120.  *
  121.  * @example
  122.  * // Increment the property by 1, (Shorthand version)
  123.  * {
  124.  *     "increment": "myNumberProperty"
  125.  * }
  126.  *
  127.  * @example
  128.  * // Increment the variable by 2
  129.  * {
  130.  *     "increment": {
  131.  *         "variable": "myNumberVariable",
  132.  *         "by": 2
  133.  *     }
  134.  * }
  135.  */
  136. class IncrementAction extends IncrementDecrementAction {
  137.     static options() {
  138.         return {
  139.             "$inc": "enumValue[property,variable]",
  140.             "by": "number%1"
  141.         }
  142.     }
  144.     constructor(name, options, concept) {
  145.         super(name, false, options, concept);
  146.     }
  147. }
  148. Action.registerPrimitiveAction("increment", IncrementAction);
  149. window.IncrementAction = IncrementAction;
  151. /**
  152.  * An action "decrement" that decrements a number property or variable
  153.  * @memberOf MathActions
  154.  * @example
  155.  * // Decrement the property by 1
  156.  * {
  157.  *     "decrement": {
  158.  *         "property": "myNumberProperty"
  159.  *     }
  160.  * }
  161.  *
  162.  * @example
  163.  * // Decrement the property by 2
  164.  * {
  165.  *     "decrement": {
  166.  *         "property": "myNumberProperty",
  167.  *         "by": 2
  168.  *     }
  169.  * }
  170.  *
  171.  * @example
  172.  * // Decrement the property by 1, (Shorthand version)
  173.  * {
  174.  *     "decrement": "myNumberProperty"
  175.  * }
  176.  *
  177.  * @example
  178.  * // Decrement the variable by 2
  179.  * {
  180.  *     "decrement": {
  181.  *         "variable": "myNumberVariable",
  182.  *         "by": 2
  183.  *     }
  184.  * }
  185.  */
  186. class DecrementAction extends IncrementDecrementAction {
  187.     static options() {
  188.         return {
  189.             "$dec": "enumValue[property,variable]",
  190.             "by": "number%1"
  191.         }
  192.     }
  194.     constructor(name, options, concept) {
  195.         super(name, true, options, concept);
  196.     }
  197. }
  198. Action.registerPrimitiveAction("decrement", DecrementAction);
  199. window.DecrementAction = DecrementAction;
  201. /**
  202.  * An action 'calculate' that calculates a given math expression and sets a variable with the result
  203.  * @memberOf MathActions
  204.  * @example
  205.  * //Shorthand, calculates and sets result in variable 'calculate'
  206.  * {
  207.  *     "calculate": "42 + 60 + $myVariableName$
  208.  * }
  209.  *
  210.  * @example
  211.  * {
  212.  *     "calculate": {
  213.  *         "expression": "sqrt(2) * sqrt(2)",
  214.  *         "as": "myResultVariableName"
  215.  *     }
  216.  * }
  217.  */
  218. class CalculateAction extends Action {
  219.     static options() {
  220.         return {
  221.             "expression": "string",
  222.             "as": "@string"
  223.         }
  224.     }
  226.     constructor(name, options, concept) {
  227.         //Shorthand
  228.         if(typeof options === "string") {
  229.             options = {
  230.                 expression: options
  231.             }
  232.         }
  234.         if(Array.isArray((options))) {
  235.             options = {
  236.                 expression: options.join(";")
  237.             }
  238.         }
  240.         super(name, options, concept);
  241.     }
  243.     static evaluate(expression) {
  244.         let result = math.evaluate(expression);
  245.         if (typeof result === "object" && Array.isArray(result.entries) && result.entries.length>0){
  246.             // Collapse to single value if parser switched to multi-expression evaluation mode
  247.             result = result.entries[0];
  248.         }
  250.         return result;
  251.     }
  253.     async apply(contexts, actionArguments) {
  254.         const self = this;
  256.         return this.forEachContext(contexts, actionArguments, async (context, options)=>{
  258.             let resultName = Action.defaultVariableName(self);
  260.             if(options.as != null) {
  261.                 resultName = options.as;
  262.             }
  264.             let result = CalculateAction.evaluate(options.expression);
  266.             Action.setVariable(context, resultName, result);
  268.             return context;
  269.         });
  270.     }
  271. }
  272. Action.registerPrimitiveAction("calculate", CalculateAction);
  273. window.CalculateAction = CalculateAction;
  275. /**
  276.  * An action 'random' that generates a random number from within a range. Both minimum and maximum are inclusive
  277.  *
  278.  * If no range is specified. 0 - Number.MAX_SAFE_INTEGER (2^53 -1) is used as range.
  279.  * @memberOf MathActions
  280.  * @example
  281.  * //Shorthand, generates a random number between 0 and 10, saves the result in the variable named "random"
  282.  * {
  283.  *     "random": [0, 10]
  284.  * }
  285.  *
  286.  * @example
  287.  * //Generate a random integer between 0 and 10, and save the result in the variable "myResultVariableName"
  288.  * {
  289.  *     "random": {
  290.  *         "range": [0, 10],
  291.  *         "as": "myResultVariableName"
  292.  *     }
  293.  * }
  294.  *
  295.  * @example
  296.  * //Generate a random float number between 0 and 10, and save the result in the variable "myResultVariableName"
  297.  * {
  298.  *     "random": {
  299.  *         "range": [0, 10],
  300.  *         "float": true,
  301.  *         "as": "myResultVariableName"
  302.  *     }
  303.  * }
  304.  */
  305. class RandomAction extends Action {
  306.     static options() {
  307.         return {
  308.             "range": "range",
  309.             "float": "boolean%false",
  310.             "as": "@string"
  311.         }
  312.     }
  314.     constructor(name, options, concept) {
  315.         //Shorthand
  316.         if(Array.isArray(options)) {
  317.             options = {
  318.                 range: options
  319.             }
  320.         }
  322.         super(name, options, concept);
  323.     }
  325.     async apply(contexts, actionArguments) {
  326.         const self = this;
  328.         function getRandomInt(min, max) {
  329.             min = Math.ceil(min);
  330.             max = Math.floor(max);
  331.             return Math.floor(Math.random() * (max - min + 1) + min);
  332.         }
  334.         function getRandomArbitrary(min, max) {
  335.             if(max < Number.MAX_VALUE) {
  336.                 //Upper bound is off by the smallest possible value
  337.                 //make it inclusive by incrementing by the smallest value
  338.                 max += Number.MIN_VALUE;
  339.             }
  340.             return Math.random() * (max - min) + min;
  341.         }
  343.         return this.forEachContext(contexts, actionArguments, async (context, options)=>{
  344.             let range = options.range;
  346.             if(range == null) {
  347.                 range = [0, Number.MAX_SAFE_INTEGER]
  348.             }
  350.             let randomNumber = Number.NaN;
  352.             if(options.float) {
  353.                 randomNumber = getRandomArbitrary(range[0], range[1]);
  354.             } else {
  355.                 randomNumber = getRandomInt(range[0], range[1]);
  356.             }
  358.             let variableName = Action.defaultVariableName(this);
  360.             if(options.as != null) {
  361.                 variableName = options.as;
  362.             }
  364.             Action.setVariable(context, variableName, randomNumber);
  366.             return context;
  367.         });
  368.     }
  369. }
  370. Action.registerPrimitiveAction("random", RandomAction);
  371. window.RandomAction = RandomAction;