clara.rules.compiler — com.github.k13labs/clara-rules 0.9.0

This namespace is for internal use and may move in the future. This is the Clara rules compiler, translating raw data structures into compiled versions and functions. Most users should use only the clara.rules namespace.

*compile-ctx* clj

add-production-load-order clj

(add-production-load-order productions)

Adds ::rule-load-order to metadata of productions. Custom DSL's may need to use this if creating a session in Clojure without calling mk-session below.

alpha-roots-wrap clj

(alpha-roots-wrap fact-type roots)

analyze-condition clj

(analyze-condition condition)

Inputs: [condition :- schema/Condition] Returns: {:bound #{sc/Symbol}, :unbound #{sc/Symbol}, :condition schema/Condition, :is-accumulator sc/Bool}

BetaNode clj

These nodes exist in the beta network.

build-network clj

(build-network id-to-node
               beta-roots
               alpha-fns
               productions
               fact-type-fn
               ancestors-fn
               activation-group-sort-fn
               activation-group-fn
               expr-fn-lookup)

Inputs: [id-to-node :- #:sc{Int sc/Any} beta-roots alpha-fns productions fact-type-fn ancestors-fn activation-group-sort-fn activation-group-fn expr-fn-lookup]

Constructs the network from compiled beta tree and condition functions.

build-token-assignment clj

(build-token-assignment binding-key)

A helper function to build variable assignment forms for tokens.

clear-session-cache! clj

(clear-session-cache!)

Clears the cache of reusable Clara sessions, so any subsequent sessions will be re-compiled from the rule definitions. This is intended for use by tooling or specialized needs; most users can simply specify the :cache false option when creating sessions.

compile-accum clj

(compile-accum node-id node-type accum env)

Used to create accumulators that take the environment into account.

compile-action clj

(compile-action node-id binding-keys rhs env)

Compile the right-hand-side action of a rule, returning a function to execute it.

compile-alpha-nodes clj

(compile-alpha-nodes alpha-nodes expr-fn-lookup)

Inputs: [alpha-nodes :- [schema/AlphaNode] expr-fn-lookup :- schema/NodeFnLookup] Returns: [{:id sc/Int, :type sc/Any, :alpha-fn sc/Any, (sc/optional-key :env) #:sc{Keyword sc/Any}, :children [sc/Num]}]

compile-condition clj

(compile-condition type
                   node-id
                   destructured-fact
                   constraints
                   result-binding
                   env)

Returns a function definition that can be used in alpha nodes to test the condition.

compile-exprs clj

(compile-exprs key->expr partition-size)

Inputs: [key->expr :- schema/NodeExprLookup partition-size :- sc/Int] Returns: schema/NodeFnLookup

Takes a map in the form produced by extract-exprs and evaluates the values(expressions) of the map in a batched manner. This allows the eval calls to be more effecient, rather than evaluating each expression on its own. See #381 for more details.

compile-join-filter clj

(compile-join-filter node-id
                     node-type
                     {:keys [type constraints args] :as unification-condition}
                     ancestor-bindings
                     element-bindings
                     env)

Compiles to a predicate function that ensures the given items can be unified. Returns a ready-to-eval function that accepts the following:

• a token from the parent node
• the fact
• a map of bindings from the fact, which was typically computed on the alpha side
• an environment

The function created here returns truthy if the given fact satisfies the criteria.

compile-test clj

(compile-test node-id constraints env)

compile-test-handler clj

(compile-test-handler node-id constraints env)

condition-to-node clj

(condition-to-node condition env parent-bindings)

Inputs: [condition :- schema/Condition env :- (sc/maybe #:sc{Keyword sc/Any}) parent-bindings :- #{sc/Keyword}] Returns: schema/ConditionNode

Converts a condition to a node structure.

condition-type clj

(condition-type condition)

Returns the type of a single condition that has been transformed to disjunctive normal form. The types are: :negation, :accumulator, :test, :exists, and :join

effective-type clj

extract-exprs clj

(extract-exprs beta-graph alpha-graph)

Inputs: [beta-graph :- schema/BetaGraph alpha-graph :- [schema/AlphaNode]] Returns: schema/NodeExprLookup

Walks the Alpha and Beta graphs and extracts the expressions that will be used in the construction of the final network. The extracted expressions are stored by their key, [<node-id> <field-key>], this allows for the function to be retrieved after it has been compiled.

Note: The keys of the map returned carry the metadata that can be used during evaluation. This metadata will contain, if available, the compile context, file and ns. This metadata is not stored on the expression itself because it will contain forms that will fail to eval.

field-name->accessors-used clj

(field-name->accessors-used type constraints)

Returns a map of field name to accessors for any field names of type used in the constraints.

flatten-expression clj

(flatten-expression expression)

Flattens expression as clojure.core/flatten does, except will flatten anything that is a collection rather than specifically sequential.

forms-per-eval-default clj

The default max number of forms that will be evaluated together as a single batch. 5000 is chosen here due to the way that clojure will evaluate the vector of forms extracted from the nodes. The limiting factor here is the max java method size (64KiB), clojure will compile each form in the vector down into its own class file and generate another class file that will reference each of the other functions and wrap them in a vector inside a static method. For example,

(eval [(fn one [_] ...) (fn two [_] ...)]) would generate 3 classes.

some_namespace$eval1234 some_namespace$eval1234$one_1234 some_namespace$eval1234$two_1235

some_namespace$eval1234$one_1234 and some_namespace$eval1234$two_1235 contian the implementation of the functions, where some_namespace$eval1234 will contain two methods, invoke and invokeStatic. The invokeStatic method breaks down into something similar to a single create array call followed by 2 array set calls with new invocations on the 2 classes the method then returns a new vector created from the array.

5000 is lower than the absolute max to allow for modifications to how clojure compiles without needing to modify this. The current limit should be 5471, this is derived from the following opcode investigation:

Array creation: 5B Creating and populating the first 6 elements of the array: 60B Creating and populating the next 122 elements of the array: 1,342B Creating and populating the next 5343 elements of the array: 64,116B Creating the vector and the return statement: 4B

This sums to 65,527B just shy of the 65,536B method size limit.

get-fields clj

IRuleSource clj protocol

load-rules clj

(load-rules source)

map->Rulebase clj

(map->Rulebase m23322)

Factory function for class Rulebase, taking a map of keywords to field values, but not much slower than ->x like the clojure.core version. (performance is fixed in Clojure 1.7, so this should eventually be removed.)

mk-node-fn-name clj

(mk-node-fn-name node-type node-id fn-type)

A simple helper function to maintain a consistent pattern for naming anonymous functions in the rulebase.

node-type - expected to align with one of the types of nodes defined in clara.rules.engine, and node-type->abbreviated-type. node-id - expected to be an integer fn-type - an identifier for what the function means to the node

fn-type is required as some nodes might have multiple functions associated to them, ex. Accumulator nodes containing filter functions.

mk-session clj

(mk-session sources-and-options)

Creates a new session using the given rule source. The resulting session is immutable, and can be used with insert, retract, fire-rules, and query functions.

mk-session* clj

(mk-session* productions options)

Inputs: [productions :- #{schema/Production} options :- #:sc{Keyword sc/Any}]

Compile the rules into a rete network and return the given session.

omit-compile-ctx-default clj

During construction of the Session there is data maintained such that if the underlying expressions fail to compile then this data can be used to explain the failure and the constraints of the rule who's expression is being evaluated. The default behavior will be to discard this data, as there will be no use unless the session will be serialized and deserialized into a dissimilar environment, ie function or symbols might be unresolvable. In those sorts of scenarios it would be possible to construct the original Session with the omit-compile-ctx flag set to false, then the compile context should aid in debugging the compilation failure on deserialization.

production-load-order-comp clj

(production-load-order-comp a b)

safe-get clj

(safe-get m k)

A helper function for retrieving a given key from the provided map. If the key doesn't exist within the map this function will throw an exception.

sort-conditions clj

(sort-conditions conditions)

Inputs: [conditions :- [schema/Condition]] Returns: [schema/Condition]

Performs a topologic sort of conditions to ensure variables needed by child conditions are bound.

strict-map->Rulebase clj

(strict-map->Rulebase m23323 & [drop-extra-keys?__21400__auto__])

Factory function for class Rulebase, taking a map of keywords to field values. All keys are required, and no extra keys are allowed. Even faster than map->

to-alpha-graph clj

(to-alpha-graph beta-graph create-id-fn)

Inputs: [beta-graph :- schema/BetaGraph create-id-fn :- IFn] Returns: [schema/AlphaNode]

Returns a sequence of [condition-fn, [node-ids]] tuples to represent the alpha side of the network.

to-beta-graph clj

(to-beta-graph productions create-id-fn)

Inputs: [productions :- #{schema/Production} create-id-fn :- IFn] Returns: schema/BetaGraph

Produces a description of the beta network.

to-dnf clj

(to-dnf expression)

Convert a lhs expression to disjunctive normal form.

try-eval clj

(try-eval expr)

Evals the given expr. If an exception is thrown, it is caught and an ex-info exception is thrown with more details added. Uses compile-ctx for additional contextual info to add to the exception details.

validate-names-unique clj

(validate-names-unique productions)

Checks that all productions included in the session have unique names, throwing an exception if duplicates are found.

variables-as-keywords clj

(variables-as-keywords expression)

Returns a set of the symbols in the given s-expression that start with '?' as keywords