core/Action.js

  1. /**
  2.  *  Action - The super class for all Actions
  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.  * A context in Varv
  31.  * @typedef {object} VarvContext
  32.  * @property {string} [target] - The UUID of the target this context refers to
  33.  * @property {object} [variables] - The variables currently set to any value
  34.  */
  36. /**
  37.  * Base class for all actions
  38.  */
  39. class Action {
  40.     /**
  41.      * Crate a new Action
  42.      * @param {string} name - The name of the action
  43.      * @param {object} options - The options of the action
  44.      * @param {Concept} concept - The owning concept
  45.      */
  46.     constructor(name, options, concept) {
  47.         this.name = name;
  48.         this.options = options;
  49.         this.concept = concept;
  51.         if(this.options == null) {
  52.             this.options = {};
  53.         }
  54.     }
  56.     /**
  57.      * Applies this Action to the given contexts, returning some resulting contexts
  58.      * @param {VarvContext[]} contexts
  59.      * @param {object} arguments
  60.      * @returns {Promise<VarvContext[]>}
  61.      */
  62.     async apply(contexts, actionArguments = {}) {
  63.         console.warn("Always override Action.apply in subclass!");
  64.         return contexts;
  65.     }
  67.     /**
  68.      * @callback forEachCallback
  69.      * @param {VarvContext} context - The context currently being looked at
  70.      * @param {object} options - The current options with variables and arguments substituted
  71.      * @param {number} index - The index of the current context in the context array
  72.      * @returns {VarvContext|VarvContext[]}
  73.      */
  75.     /**
  76.      * Loops through the given contexts, and calls the given callback for each, complete with substituted options and the index of the context
  77.      * @param {VarvContext[]} contexts - The contexts to handle
  78.      * @param {object} actionArguments - The arguments to use for this action
  79.      * @param {forEachCallback} callback - The callback to call for each context
  80.      * @returns {Promise<VarvContext[]>}
  81.      */
  82.     async forEachContext(contexts, actionArguments={}, callback) {
  83.         if(arguments.length < 2) {
  84.             throw new Error("forEachContext can be called either as (contexts, actionArguments, callback) or (contexts, callback)");
  85.         }
  87.         //If called with 2 arguments options is the callback
  88.         if(arguments.length === 2) {
  89.             if(typeof actionArguments !== "function") {
  90.                 throw new Error("forEachContext can be called either as (contexts, actionArguments, callback) or (contexts, callback)");
  91.             }
  93.             // noinspection JSValidateTypes
  94.             callback = actionArguments;
  95.             actionArguments = {};
  96.         }
  98.         let results = [];
  100.         let index = 0;
  102.         let options = await Action.lookupArguments(this.options, actionArguments);
  104.         for (let context of contexts) {
  105.             //Make sure to clone context, since we change it directly, thus variables might be a shared object if not.
  106.             let clonedContext = Action.cloneContext(context);
  108.             let optionsWithVariables = await Action.lookupVariables(options, clonedContext);
  110.             let result = await callback(clonedContext, optionsWithVariables, index);
  112.             if (result != null) {
  113.                 if (Array.isArray(result)) {
  114.                     result.forEach((entry) => {
  115.                         results.push(entry);
  116.                     });
  117.                 } else {
  118.                     results.push(result);
  119.                 }
  120.             }
  122.             index++;
  123.         }
  125.         return results;
  126.     }
  128.     /**
  129.      * Get the default variable name, for when no variable name is supplied
  130.      * @param {Action} - The action asking, the name of the action is used.
  131.      * @returns {string} - The default variable name
  132.      */
  133.     static defaultVariableName(action) {
  134.         if(action == null) {
  135.             return "result";
  136.         }
  138.         return action.name;
  139.     }
  141.     /**
  142.      * Sets the given variable to the given value, in the given context
  143.      * @param {VarvContext} context - The context to set the variable inside
  144.      * @param {string} name - The name of the variable to set
  145.      * @param {any} value - The value to set
  146.      */
  147.     static setVariable(context, name, value) {
  148.         if(context.variables == null) {
  149.             context.variables = {}
  150.         }
  152.         if(name === "target") {
  153.             console.warn("Unable to set variable target!");
  154.             return;
  155.         }
  157.         context.variables[name] = value;
  158.     }
  160.     /**
  161.      * Retrieve the value of the given variable from the given context
  162.      * @param {VarvContext} context
  163.      * @param {string} name
  164.      * @returns {any}
  165.      */
  166.     static getVariable(context, name) {
  167.         if(name === "target" && context.target != null) {
  168.             //If context.target exists use that, if not, check variables as getCommonVariables might have saved a common target
  169.             return context.target;
  170.         }
  172.         if(name === "lastTarget" && context.lastTarget != null) {
  173.             //If context.lastTarget exists use that
  174.             return context.lastTarget;
  175.         }
  177.         if(context.variables == null) {
  178.             context.variables = {}
  179.         }
  181.         if(!context.variables.hasOwnProperty(name)) {
  182.             if(name === "target") {
  183.                 throw new Error("Context did not contain target, and no variable target existed either!");
  184.             }
  186.             throw new Error("No named variable ["+name+"]");
  187.         }
  189.         return context.variables[name];
  190.     }
  192.     /**
  193.      * Extract all the variables that have the same value across all contexts
  194.      * @param contexts
  195.      * @returns {{}}
  196.      */
  197.     static getCommonVariables(contexts) {
  198.         let common = {};
  200.         let mark = VarvPerformance.start();
  202.         if(contexts.length > 0) {
  203.             let testContext = contexts[0];
  205.             if(testContext.variables != null) {
  206.                 Object.keys(testContext.variables).forEach((variableName)=>{
  207.                     let variableValue = testContext.variables[variableName];
  208.                     let keep = true;
  210.                     for(let otherContext of contexts) {
  211.                         if(otherContext.variables != null) {
  212.                             let otherValue = otherContext.variables[variableName];
  214.                             if(otherValue != null && otherValue === variableValue) {
  215.                                 continue;
  216.                             }
  218.                             if(Array.isArray(otherValue) && Array.isArray(variableValue)) {
  219.                                 if(otherValue.length === variableValue.length) {
  220.                                     let arrayEqual = true;
  221.                                     for(let i = 0; i<otherValue.length; i++) {
  222.                                         arrayEqual = arrayEqual && otherValue[i] === variableValue[i];
  223.                                     }
  225.                                     if(arrayEqual) {
  226.                                         continue;
  227.                                     }
  228.                                 }
  229.                             }
  230.                         }
  232.                         keep = false;
  233.                         break;
  234.                     }
  236.                     if(keep) {
  237.                         common[variableName] = variableValue;
  238.                     }
  239.                 });
  240.             }
  242.             if(testContext.target != null) {
  243.                 let keep = true;
  244.                 for(let otherContext of contexts) {
  245.                     if (otherContext.target != testContext.target) {
  246.                         keep = false;
  247.                         break;
  248.                     }
  249.                 }
  251.                 if(keep) {
  252.                     common["target"] = testContext.target;
  253.                 }
  254.             }
  255.         } else {
  256.             if(contexts.savedVariables) {
  257.                 return contexts.savedVariables;
  258.             }
  259.         }
  261.         VarvPerformance.stop("Action.getCommonVariables", mark, "#contexts "+contexts.length);
  263.         return common;
  264.     }
  266.     static getCommonTarget(contexts) {
  267.         let commonTarget = -1;
  268.         contexts.forEach((context)=>{
  269.             if(commonTarget === -1) {
  270.                 commonTarget = context.target;
  271.             } else {
  272.                 if(commonTarget !== context.target) {
  273.                     commonTarget = null;
  274.                 }
  275.             }
  276.         });
  277.         return commonTarget;
  278.     }
  280.     /**
  281.      * Looks up any options that are set to an argument replacement value "@myArgumentName" and replaces it with that arguments value
  282.      * @param {object} options - The options to do the replacement on
  283.      * @param {object} actionArguments - The arguments to replace into the options
  284.      * @returns {object} A clone of the options argument, with all replacement values replaced
  285.      */
  286.     static async lookupArguments(options, actionArguments) {
  287.         let mark = VarvPerformance.start();
  289.         const optionsClone = Action.clone(options);
  291.         let regex = /@(\S+?)(?:@|\s|$)/gm;
  293.         for(let parameter in optionsClone) {
  294.             if(!Object.hasOwn(optionsClone, parameter)) {
  295.                 continue;
  296.             }
  298.             let value = optionsClone[parameter];
  300.             optionsClone[parameter] = await Action.subParam(value, (value)=>{
  301.                 if(!value.includes("@")) {
  302.                     return value;
  303.                 }
  305.                 //Substitute any @argumentName with the value of the argument
  306.                 for(let match of value.matchAll(regex)) {
  307.                     let search = match[0].trim();
  308.                     let variableName = match[1];
  310.                     let variableValue = actionArguments[variableName];
  312.                     if(Action.DEBUG) {
  313.                         console.log("Replaced argument:", search, variableValue, actionArguments, variableName);
  314.                     }
  316.                     if(value === search) {
  317.                         //Single value, set it directly
  318.                         value = variableValue;
  319.                     } else {
  320.                         //Replace into value
  321.                         value = value.replace(search, variableValue);
  322.                     }
  323.                 }
  325.                 return value;
  326.             });
  328.         }
  330.         VarvPerformance.stop("Action.lookupArguments", mark, {options});
  332.         return optionsClone;
  333.     }
  335.     static async subParam(value, lookupCallback) {
  336.         if (Array.isArray(value)) {
  337.             for (let i = 0; i < value.length; i++) {
  338.                 value[i] = await Action.subParam(value[i], lookupCallback);
  339.             }
  340.             return value;
  341.         } else if (typeof value === "object" && value != null && Object.getPrototypeOf(value) === Object.prototype) {
  342.             for(let key in value) {
  343.                 if(Object.hasOwn(value, key)) {
  344.                     value[key] = await Action.subParam(value[key], lookupCallback);
  345.                 }
  346.             }
  347.             return value;
  348.         } else if (typeof value === "string") {
  349.             return lookupCallback(value);
  350.         } else {
  351.             return value;
  352.         }
  353.     }
  355.     static clone(obj) {
  356.         if(Array.isArray(obj)) {
  357.             return obj.map((arrayValue)=>{
  358.                 return Action.clone(arrayValue);
  359.             });
  360.         } else if(typeof obj === "object" && obj != null && Object.getPrototypeOf(obj) === Object.prototype) {
  362.             let clone = {};
  364.             for (let key in obj) {
  365.                 if (!Object.hasOwn(obj, key)) {
  366.                     continue;
  367.                 }
  369.                 clone[key] = Action.clone(obj[key]);
  370.             }
  372.             return clone;
  373.         }
  375.         return obj;
  376.     }
  379.     /**
  380.      * Look up any options that have a variable replacement value "$myVariable" and replaces it with the value of that variable.
  381.      * @param {object} options
  382.      * @param {VarvContext} context
  383.      * @returns {object} - Returns a clone of the given options, with all replacement values replaced.
  384.      */
  385.     static async lookupVariables(options, context) {
  386.         if(Action.DEBUG) {
  387.             console.group("Looking up variables from context:", options, context);
  388.         }
  390.         let mark = VarvPerformance.start();
  392.         const optionsClone = Action.clone(options);
  394.         async function doLookup(context, variableName) {
  395.             let variableValue = null;
  397.             if(variableName.indexOf(".") !== -1) {
  398.                 let split = variableName.split(".");
  400.                 //concept.property lookup, not really variable
  401.                 let conceptName = split[0];
  402.                 let propertyName = split[1];
  404.                 let result = null;
  406.                 if(conceptName === "lastTarget") {
  407.                     result = await VarvEngine.lookupProperty(context.lastTarget, null, propertyName);
  408.                 } else if(conceptName === "target") {
  409.                     result = await VarvEngine.lookupProperty(context.target, null, propertyName);
  410.                 } else {
  411.                     result = await VarvEngine.lookupProperty(context.target, null, variableName);
  412.                 }
  414.                 if (result != null && result.target != null) {
  415.                     variableValue = await result.property.getValue(result.target);
  416.                 }
  417.             } else {
  418.                 variableValue = Action.getVariable(context, variableName);
  419.             }
  421.             return variableValue;
  422.         }
  424.         let regex = /\$(\S+?)(?:\$|\s|$)/gm;
  426.         for(let key of Object.keys(optionsClone)) {
  427.             optionsClone[key] = await Action.subParam(optionsClone[key], async (value)=>{
  428.                 if(!value.includes("$")) {
  429.                     return value;
  430.                 }
  432.                 //Substitute any $VariableName with the value of the variable
  433.                 for(let match of value.matchAll(regex)) {
  434.                     let search = match[0].trim();
  435.                     let variableName = match[1];
  437.                     let variableValue = await doLookup(context, variableName);
  439.                     if(Action.DEBUG) {
  440.                         console.log("Replaced variable:", search, variableValue);
  441.                     }
  443.                     if(value === search) {
  444.                         //Single value, set it directly
  445.                         value = variableValue;
  446.                     } else {
  447.                         //Replace into value
  448.                         value = value.replace(search, variableValue);
  449.                     }
  450.                 }
  452.                 return value;
  453.             });
  454.         }
  456.         if(Action.DEBUG) {
  457.             console.groupEnd();
  458.         }
  460.         VarvPerformance.stop("Action.lookupVariables", mark, {context, options});
  462.         //Handle special stuff here
  463.         Action.substituteEvery(optionsClone, "calculate", (value)=>{
  464.             return CalculateAction.evaluate(value);
  465.         });
  467.         return optionsClone;
  468.     }
  470.     static substituteEvery(input, nameToSubstitute, callback) {
  471.         if(Array.isArray(input)) {
  472.             for(let i = 0; i< input.length; i++) {
  473.                 input[i] = Action.substituteEvery(input[i], nameToSubstitute, callback);
  474.             }
  475.         } else if(typeof input === "object") {
  476.             for(let key in input) {
  477.                 if(input.hasOwnProperty(key)) {
  478.                     if(key === nameToSubstitute) {
  479.                         if(Object.keys(input).length > 1) {
  480.                             console.warn("Substituting on something with more than 1 entry (Stuff will be lost):", input, nameToSubstitute);
  481.                         }
  483.                         let origValue = input[key];
  484.                         return callback(origValue);
  485.                     } else {
  486.                         input[key] = Action.substituteEvery(input[key], nameToSubstitute, callback);
  487.                     }
  488.                 }
  489.             }
  490.         }
  492.         return input;
  493.     }
  495.     /**
  496.      * Registers the given action as a primitive action with the given name
  497.      * @param {string} name
  498.      * @param {Action} action
  499.      */
  500.     static registerPrimitiveAction(name, action) {
  501.         if(Action.DEBUG) {
  502.             console.log("Registering primitive action:", name, action);
  503.         }
  505.         if (Action.primitiveActions.has(name)) {
  506.             console.warn("Overriding primitive action: ", name);
  507.         }
  509.         Action.primitiveActions.set(name, action);
  510.     }
  512.     /**
  513.      * Gets an instance of the primitive action with the given name, using the given options
  514.      * @param {string} name
  515.      * @param {object} options
  516.      * @returns {Action}
  517.      */
  518.     static getPrimitiveAction(name, options, concept) {
  519.         let actionClass = Action.primitiveActions.get(name);
  521.         if (actionClass == null) {
  522.             throw new Error("Unknown primitive action [" + name + "]");
  523.         }
  525.         let action = new actionClass(name, options, concept);
  527.         action.isPrimitive = true;
  529.         return action;
  530.     }
  532.     /**
  533.      * Checks if a primitive action with the given name exists
  534.      * @param {string} name
  535.      * @returns {boolean}
  536.      */
  537.     static hasPrimitiveAction(name) {
  538.         return Action.primitiveActions.has(name);
  539.     }
  541.     /**
  542.      * Clones the given context. (Any non JSON serializable values in the context, will be lost)
  543.      * @param {VarvContext} context
  544.      * @returns {VarvContext} - The cloned context
  545.      */
  546.     static cloneContext(context) {
  547.         let mark = VarvPerformance.start();
  549.         let result = null;
  550.         if(Array.isArray(context)) {
  551.             result = context.map(Action.cloneContextInternal);
  552.         } else {
  553.             result = Action.cloneContextInternal(context);
  554.         }
  556.         VarvPerformance.stop("Action.cloneContext", mark);
  558.         return result;
  559.     }
  561.     static cloneContextInternal(context) {
  562.         //Move over allowed properties
  563.         let preCloneObject = {};
  564.         preCloneObject.variables = context.variables;
  565.         preCloneObject.target = context.target;
  567.         if(Action.DEBUG) {
  568.             console.log("Cloning context:", context, preCloneObject);
  569.         }
  570.         return Action.clone(preCloneObject);
  571.     }
  572. }
  573. Action.DEBUG = false;
  574. Action.primitiveActions = new Map();
  575. window.Action = Action;
  577. class ActionChain extends Action {
  578.     constructor(name, options, concept) {
  579.         super(name, options, concept);
  581.         this.actions = [];
  582.     }
  584.     addAction(action) {
  585.         const self = this;
  587.         if(Array.isArray(action)) {
  588.             action.forEach((actionElm)=>{
  589.                 self.actions.push(actionElm);
  590.             })
  591.         } else {
  592.             this.actions.push(action);
  593.         }
  594.     }
  596.     async apply(contexts, actionArguments = {}) {
  597.         let currentContexts = contexts;
  599.         for (let action of this.actions) {
  600.             let commonVariablesBefore = Action.getCommonVariables(currentContexts);
  602.             await ActionTrigger.before(action, currentContexts);
  603.             let mark = VarvPerformance.start();
  604.             currentContexts = await action.apply(currentContexts, actionArguments);
  605.             if(action.isPrimitive) {
  606.                 VarvPerformance.stop("PrimitiveAction-"+action.name, mark);
  607.             } else {
  608.                 VarvPerformance.stop("CustomAction-"+action.name, mark);
  609.             }
  610.             await ActionTrigger.after(action, currentContexts);
  612.             if(currentContexts == null) {
  613.                 currentContexts = [];
  614.             }
  616.             if(currentContexts.length === 0) {
  617.                 currentContexts.savedVariables = commonVariablesBefore;
  618.             }
  619.         }
  621.         return currentContexts;
  622.     }
  623. }
  625. window.ActionChain = ActionChain;
  627. class LookupActionAction extends Action {
  628.     constructor(name, options, concept) {
  629.         super(name, options, concept);
  630.     }
  632.     async apply(contexts, actionArguments = {}) {
  633.         const self = this;
  635.         let optionsWithArguments = await Action.lookupArguments(this.options, actionArguments);
  637.         if(optionsWithArguments.lookupActionName == null) {
  638.             throw new Error("[LookupActionAction] Missing option 'lookupActionName'");
  639.         }
  641.         //TODO: We assume that all concepts are of the same type, when/if polymorphism is introduced this breaks
  642.         let contextConcept = null;
  643.         if(contexts.length > 0) {
  644.             contextConcept = await VarvEngine.getConceptFromUUID(contexts[0].target);
  645.         }
  647.         let action = VarvEngine.lookupAction(optionsWithArguments.lookupActionName, [contextConcept, self.concept], optionsWithArguments.lookupActionArguments);
  649.         if(action != null) {
  650.             await ActionTrigger.before(action, contexts);
  651.             let mark = VarvPerformance.start();
  652.             let lookupActionResult = await action.apply(contexts, action.isPrimitive?{}:optionsWithArguments.lookupActionArguments);
  653.             if(action.isPrimitive) {
  654.                 VarvPerformance.stop("PrimitiveAction-"+action.name, mark);
  655.             } else {
  656.                 VarvPerformance.stop("CustomAction-"+action.name, mark);
  657.             }
  658.             await ActionTrigger.after(action, lookupActionResult);
  659.             return lookupActionResult;
  660.         }
  662.         return null;
  663.     }
  664. }
  666. window.LookupActionAction = LookupActionAction;
  668. class StopError extends Error {
  669.     constructor(msg) {
  670.         super(msg);
  671.     }
  672. }
  673. window.StopError = StopError;