{"type":"doc","content":[{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"Any KRL ruleset can function as a module if it contains the ","type":"text"},{"text":"provides","type":"text","marks":[{"type":"code"}]},{"text":" pragma in the ","type":"text"},{"text":"meta","type":"text","marks":[{"type":"code"}]},{"text":" section of the ruleset. KRL modules are parameterized and can be included more than once with different parameters. A module may include, and use, other modules.","type":"text"}]},{"type":"paragraph","content":[{"text":"When defined as a module, any of the global definitions may be provided to rulesets that use the module. Rules cannot be shared.","type":"text"}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"maxLevel":{"value":"1"}},"macroMetadata":{"macroId":{"value":"16f4355d-4e2c-407e-bd4e-669647aa6328"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}}}},{"type":"heading","attrs":{"level":1},"content":[{"text":"Using a Module","type":"text"}]},{"type":"paragraph","content":[{"text":"A ruleset uses another ruleset as a module with the ","type":"text"},{"text":"use module","type":"text","marks":[{"type":"code"}]},{"text":" pragma. The syntax is:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"meta {\n ...\n use module \n [alias ]\n [with = [ = ]*]\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" is the name of the ruleset to use as a module. Note that this is the RID that the ruleset manager knows the ruleset by, not the name declared in the ","type":"text"},{"text":"meta","type":"text","marks":[{"type":"code"}]},{"text":" section of the ruleset.","type":"text"}]},{"type":"paragraph","content":[{"text":"Any global definitions in that ruleset that have been declared in the ","type":"text"},{"text":"provides","type":"text","marks":[{"type":"code"}]},{"text":" pragma of the module will be available in the using ruleset. You can reference these declarations in the using ruleset by namespacing the variable name from the module with the module's name (i.e. its ruleset name).","type":"text"}]},{"type":"paragraph","content":[{"text":"For example, if ruleset with RID ","type":"text"},{"text":"com.windley.krl.blast","type":"text","marks":[{"type":"code"}]},{"text":" provides ","type":"text"},{"text":"flip","type":"text","marks":[{"type":"code"}]},{"text":" then it can be referenced in a ruleset using ","type":"text"},{"text":"com.windley.krl.blast","type":"text","marks":[{"type":"code"}]},{"text":" as follows:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"global {\n x = com.windley.krl.blast:flip * 3;\n}","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Code doesn't compile","type":"text"}]},{"type":"paragraph","content":[{"text":"The above code doesn't compile. The syntax of a ruleset identifier (RID) allows it to contain periods and hyphens. But those are not allowed in identifiers, so the string preceding the colon above is ","type":"text"},{"text":"not","type":"text","marks":[{"type":"em"}]},{"text":" an identifier. The next section shows how to work around this.","type":"text"}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Aliasing","type":"text"}]},{"type":"paragraph","content":[{"text":"The optional ","type":"text"},{"text":"alias","type":"text","marks":[{"type":"code"}]},{"text":" keyword declares an alias for the ruleset name. So if ","type":"text"},{"text":"com.windley.krl.blast","type":"text","marks":[{"type":"code"}]},{"text":" ruleset is used as follows:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"use module com.windley.krl.blast alias please","type":"text"}]},{"type":"paragraph","content":[{"text":"then, the preceding example would look like this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"global {\n x = please:flip * 3;\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Note:","type":"text","marks":[{"type":"strong"}]},{"text":" the following are reserved for the Node engine and should not be used as module aliases:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"app","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"csv","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"engine","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"ent","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"event","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"ical","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"keys","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"http","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"indy","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"math","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"meta","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"random","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"rss","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"schedule","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"time","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"uri","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"wrangler","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"The optional ","type":"text"},{"text":"with","type":"text","marks":[{"type":"code"}]},{"text":" clause declares configuration values for the used module. The expressions on the righthand side of the ","type":"text"},{"text":"with","type":"text","marks":[{"type":"code"}]},{"text":" clause must be evaluable before anything in the ruleset has been evaluated. That means that the righthand side is limited to expressions that use:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"literals","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"keys","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"event attributes","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"environment values","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"See below for more information on module configuration.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Declaring a Module","type":"text"}]},{"type":"paragraph","content":[{"text":"Strictly speaking, any ruleset can be used as a module but only rulesets that contain the ","type":"text"},{"text":"provides","type":"text","marks":[{"type":"code"}]},{"text":" pragma in their ","type":"text"},{"text":"meta","type":"text","marks":[{"type":"code"}]},{"text":" section will be useful since only global definitions explicitly marked for export in the ","type":"text"},{"text":"provides","type":"text","marks":[{"type":"code"}]},{"text":" pragma will be available in the using ruleset. If the ruleset contains no ","type":"text"},{"text":"provides","type":"text","marks":[{"type":"code"}]},{"text":" pragma or one that is empty or names values not declared in the module, nothing will be usable in the using ruleset.","type":"text"}]},{"type":"paragraph","content":[{"text":"The syntax for provides is","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"provides [,]*","type":"text"}]},{"type":"paragraph","content":[{"text":"The list of provided declaration is given as a comma separated list of names.","type":"text"}]},{"type":"paragraph","content":[{"text":"Often it's useful to know whether or not a ruleset is running as a module. The ","type":"text"},{"text":"meta library","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/docs/pages/1189924"}}]},{"text":" provides functions (not yet implemented) that give information about the running ruleset, including whether it's running as a module or not. ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Configuring a Module","type":"text"}]},{"type":"paragraph","content":[{"text":"When a module is used, the ","type":"text"},{"text":"with","type":"text","marks":[{"type":"code"}]},{"text":" clause allows the module to be configured. This provides for module parameterization. The configuration is declared using the ","type":"text"},{"text":"configure","type":"text","marks":[{"type":"code"}]},{"text":" pragma in the ","type":"text"},{"text":"meta","type":"text","marks":[{"type":"code"}]},{"text":" section of the module. The syntax is as follows:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"configure using = [ = ]*","type":"text"}]},{"type":"paragraph","content":[{"text":"Only variables declared in the ","type":"text"},{"text":"configure","type":"text","marks":[{"type":"code"}]},{"text":" pragma will be configurable from the using ruleset. The ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" gives a default value for the configuration parameter. If the ","type":"text"},{"text":"with","type":"text","marks":[{"type":"code"}]},{"text":" clause is used to declare configuration values when the module is used, then those values will override any defaults in the configuration of the module.","type":"text"}]},{"type":"paragraph","content":[{"text":"Variables declared in the configuration are available as regular variables throughout the module. A typical use of the module configuration is to pass in user keys from a ruleset's ","type":"text"},{"text":"keys","type":"text","marks":[{"type":"code"},{"type":"link","attrs":{"href":"https://picolabs.atlassian.net/wiki/spaces/docs/pages/1189582"}}]},{"text":" declaration so that the module can use them.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Example","type":"text"}]},{"type":"paragraph","content":[{"text":"Consider the following ruleset that is intended for use as a module (note the ","type":"text"},{"text":"provides","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"configure","type":"text","marks":[{"type":"code"}]},{"text":" pragmas):","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"ruleset com.windley.krl.blast {\n meta {\n name \"cs_module\"\n description <<\nFor testing modules\nSystem tests depend on this ruleset. \n>>\n configure using c = \"Hello\"\n provides a, f, g\n }\n global {\n a = 5;\n b = 6; \n f = function(x){x + b}; \n g = function(){ent:c} \n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Suppose that we used this module as follows:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"ruleset foobar {\n meta {\n use module com.windley.krl.blast alias blast\n }\n global {\n x = blast:a + 4;\n y = blast:f(4);\n }\n ...\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"When rules in ruleset ","type":"text"},{"text":"foobar","type":"text","marks":[{"type":"code"}]},{"text":" execute, ","type":"text"},{"text":"x","type":"text","marks":[{"type":"code"}]},{"text":" will have the value 9 and ","type":"text"},{"text":"y","type":"text","marks":[{"type":"code"}]},{"text":" will have the value 10. Note that if we had referenced ","type":"text"},{"text":"blast:b","type":"text","marks":[{"type":"code"}]},{"text":" it would be undefined since ","type":"text"},{"text":"b","type":"text","marks":[{"type":"code"}]},{"text":" is not in the ","type":"text"},{"text":"provides","type":"text","marks":[{"type":"code"}]},{"text":" pragma in the module. ","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Module Configuration and Aliasing","type":"text"}]},{"type":"paragraph","content":[{"text":"The following example shows how module configuration and aliasing can be used effectively. ","type":"text"}]},{"type":"paragraph","content":[{"text":"The following ruleset defines a module that defines a function and two actions to interact with a data service called ","type":"text"},{"text":"StringBin","type":"text","marks":[{"type":"code"}]},{"text":" (a simple cloud-based key-value pair storage system). StringBin requires a developer pin.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"ruleset com.windley.krl.stringbin {\n meta {\n name \"StringBin Module\"\n provide read, write, destroy\n configure using pin = \"nopin\"\n }\n global {\n write = defaction (k, v) {\n http:post(\"http://api.stringbin.com/1/write\", params =\n { \"pin\": pin,\n \"key\": k,\n \"value\": v\n } \n }\n destroy = defaction (k) {\n http:post(\"http://api.stringbin.com/1/write\", params =\n { \"pin\": pin,\n \"key\": k,\n \"value\": \"\"\n }\n }\n read = function(k) {\n http:get(\"http://api.stringbin.com/1/read\", params =\n { \"pin\": pin,\n \"key\": k\n }\n }\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Two important things to note in this module definition are the ","type":"text"},{"text":"provide","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"configure","type":"text","marks":[{"type":"code"}]},{"text":" pragmas. The ","type":"text"},{"text":"provide","type":"text","marks":[{"type":"code"}]},{"text":" pragma is followed by a list of names that will be available outside the module. Note that the ","type":"text"},{"text":"datasource","type":"text","marks":[{"type":"code"}]},{"text":" declaration ","type":"text"},{"text":"sb_data","type":"text","marks":[{"type":"code"}]},{"text":" is not provided to rulesets using the module and thus the implementation details are hidden. The only way to reach the datasource is using the provided function named read.","type":"text"}]},{"type":"paragraph","content":[{"text":"The configure keyword indicates the module parameters and their default values. In this case there is one parameter, the value of the developer pin. Any ruleset using this module must supply a pin or it won’t work since the default value is “nopin.”","type":"text"}]},{"type":"paragraph","content":[{"text":"We use a module by declaring its use in the meta section, giving any configuration parameters using a with clause. The use module pragma requires a ruleset name and an optional alias (StringBin in this case)","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"meta {\n use module com.windley.krl.stringbin alias StringBin \n with pin = \"X9ooUUsrR180MkpxZ2N1M\"\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Later we can use one of the module’s actions in a rule like so:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"rule write_to_stringbin {\n select when web pageview\n StringBin:write(\"yellow\", \"mellow\")\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"This rule writes the value “mellow” to the StringBin store using the key “yellow.” Note that when we declared the module’s use we gave it an alias and the alias is used to namespace the action (","type":"text"},{"text":"StringBin:write()","type":"text","marks":[{"type":"code"}]},{"text":" in this case)","type":"text"}]},{"type":"paragraph","content":[{"text":"Because modules are parameterized and can be aliased, you can use a given module multiple times in a single ruleset with different parameters. For example, suppose we had two StringBins and we wanted to copy a value out of one into the other. First, we declare the module’s use twice with different aliases and configurations:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"meta {\n use module com.windley.krl.stringbin alias BinA \n with pin = \"X9ooUUsrR180MkpxZ2N1M\"\n use module com.windley.krl.stringbin alias BinB \n with pin = \"ada98u0ada0kkdad0a0da\"\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Because we give each use of the StringBin module a different pin, they will reference different string bins. ","type":"text"}]},{"type":"paragraph","content":[{"text":"We can use the aliased modules to write a rule that copies data from BinA into BinB:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"rule copy_stringbin {\n select when web pageview\n pre {\n stuffToCopy = BinA:read(\"yellow\");\n }\n BinB:write(\"yellow\", stuffToCopy);\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"In this rule, we’ve read data from ","type":"text"},{"text":"BinA","type":"text","marks":[{"type":"code"}]},{"text":" and then written it to ","type":"text"},{"text":"BinB","type":"text","marks":[{"type":"code"}]},{"text":". Of course, in a real rule to accomplish this, the key (“yellow”) would likely be computed from event parameters in some way.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Modules are Closures","type":"text"}]},{"type":"paragraph","content":[{"text":"Rulesets form closures over the value defined in them. This is true when the ruleset is used as a module as well. All variables are scoped statically, not dynamically, whether in the global variable bindings or inside rules. This applies to persistent variables as well. ","type":"text"}]},{"type":"paragraph","content":[{"text":"This has important implications for how rulesets that are also modules behave. Here’s a detailed look at what this means. Suppose we defined the following ruleset:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"ruleset foo {\n meta {\n provides get_item\n }\n global { \n get_item = function (k) {\n ent:elements{k};\n };\n }\n\n rule add_item {\n select when pds new_data_available\n noop();\n always {\n ent:elements{event:attr(\"key\")} := event:attr(\"value\");\n raise pds event \"new_item_added\";\n }\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"provides","type":"text","marks":[{"type":"code"}]},{"text":" pragma in the ","type":"text"},{"text":"meta","type":"text","marks":[{"type":"code"}]},{"text":" section indicates that this ruleset is intended to be used as a module. Note that ","type":"text"},{"text":"get_item()","type":"text","marks":[{"type":"code"}]},{"text":" references an entity variable (","type":"text"},{"text":"ent:elements","type":"text","marks":[{"type":"code"},{"type":"link","attrs":{"href":"http://entelements"}}]},{"text":"). An entity variable with the same name is mutated in the rule ","type":"text"},{"text":"add_item","type":"text","marks":[{"type":"code"}]},{"text":". Because this ruleset will function as a closure over the value in ","type":"text"},{"text":"ent:elements","type":"text","marks":[{"type":"code"}]},{"text":", the value of ","type":"text"},{"text":"ent:elements","type":"text","marks":[{"type":"code"}]},{"text":" retrieved by ","type":"text"},{"text":"get_item()","type":"text","marks":[{"type":"code"}]},{"text":" is the same as the one mutated in the rule.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Module Caching","type":"text"}]},{"type":"paragraph","content":[{"text":"When a module is evaluated, a variable environment is created based on the declarations in the module and the module configuration. The environment is cached for performance reasons when possible. The performance benefits of module caching are substantial. ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Cachability","type":"text"}]},{"type":"paragraph","content":[{"text":"In general, as long as the global declarations in your module fall into the following categories, your module will be cachable:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"function definitions","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"action definitions","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"literals","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"simple variables","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"expressions involving the preceding items","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Any expression involving a ","type":"text"},{"text":"persistent variable","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/docs/pages/1189855"}}]},{"text":" will not be cachable unless the persistent variable is wrapped in a function or action definition. Also, some specific built-in functions that have dynamic values cannot be cached. If your module cannot be cached, it will still work, but may perform poorly. Developers should work to ensure their modules are cachable. ","type":"text"}]},{"type":"panel","attrs":{"panelType":"error"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Don't Try to Fool the Caching Algorithm","type":"text"}]},{"type":"paragraph","content":[{"text":"You can wrap something that isn't cachable (such as a persistent variable) in a function to make it cachable and then immediately call the function, providing the result from the module (see the examples below). While the system will determine that your module is cachable, the result provided will be stale if the wrapped persistent variable is updated, since that will not invalidate the cache.","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Examples","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"global {\n // the following declarations are cachable\n a = 5;\n b = x + 5;\n get_item = function (k) {\n ent:elements{k};\n };\n \n // the following declarations are not cachable\n a = ent:elements{\"name\"};\n b = meta:callingRID();\n \n // the following is cachable, but will lead to stale results\n q = get_item(\"name\") \n \n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Is My Module Being Cached","type":"text"}]},{"type":"paragraph","content":[{"text":"If you turn logging on for a ruleset including your module, you'll be able to see whether or not your module is being cached in the debug information. ","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}],"version":1}

Browser not supported