Liking cljdoc? Tell your friends :D

clara.tools.inspect

Tooling to inspect a rule session. The two major methods here are:

  • inspect, which returns a data structure describing the session that can be used by tooling.
  • explain-activations, which uses inspect and prints a human-readable description covering why each rule activation or query match occurred.
Tooling to inspect a rule session. The two major methods here are:

* inspect, which returns a data structure describing the session that can be used by tooling.
* explain-activations, which uses inspect and prints a human-readable description covering
why each rule activation or query match occurred.
raw docstring

ConditionMatchclj

A structure associating a condition with the facts that matched them. The fields are: :fact - A fact propagated from this condition in a rule or query. For non-accumulator conditions, this will be the fact matched by the condition. For accumulator conditions, it will be the result of the accumulation. So, for example, if we have a condition like

[?cold <- Cold]

a ConditionMatch for this condition will have a Cold fact in its :fact field. If we have a condition like

[?min-cold <- (acc/min :temperature) :from [Cold]]

the value of :fact will be the minimum temperature returned by the accumulator.

:condition - A structure representing this condition. This is the same structure used inside the structures defining rules and queries.

:facts-accumulated (nullable) : When the condition is an accumulator condition, this will contain the individual facts over which the accumulator ran. For example, in the case above with the condition

[?min-cold <- (acc/min :temperature) :from [Cold]]

this will contain the individual Cold facts over which we accumulated, while the :fact field will contain the result of the accumulation.

A structure associating a condition with the facts that matched them.  The fields are:
:fact - A fact propagated from this condition in a rule or query.  For non-accumulator conditions,
this will be the fact matched by the condition.  For accumulator conditions, it will be the result
of the accumulation.  So, for example, if we have a condition like

[?cold <- Cold]

a ConditionMatch for this condition will have a Cold fact in its :fact field.  If we have a condition like

[?min-cold <- (acc/min :temperature) :from [Cold]]

the value of :fact will be the minimum temperature returned by the accumulator.

:condition - A structure representing this condition.  This is the same structure used inside the structures defining
rules and queries.

:facts-accumulated (nullable) : When the condition is an accumulator condition, this will contain the individual facts over 
which the accumulator ran.  For example, in the case above with the condition

[?min-cold <- (acc/min :temperature) :from [Cold]]

this will contain the individual Cold facts over which we accumulated, while the :fact field
will contain the result of the accumulation.
sourceraw docstring

explain-activationsclj

(explain-activations session & {:keys [rule-filter-fn] :as options})

Prints a human-friendly explanation of why rules and queries matched in the given session. A caller my optionally pass a :rule-filter-fn, which is a predicate

(clara.tools.inspect/explain-activations session :rule-filter-fn (fn [rule] (re-find my-rule-regex (:name rule))))

Prints a human-friendly explanation of why rules and queries matched in the given session.
A caller my optionally pass a :rule-filter-fn, which is a predicate

(clara.tools.inspect/explain-activations session
                                         :rule-filter-fn (fn [rule] (re-find my-rule-regex (:name rule))))
sourceraw docstring

inspectclj

(inspect session)

Inputs: [session]

Returns a representation of the given rule session useful to understand the state of the underlying rules.

The returned structure always includes the following keys:

  • :rule-matches -- a map of rule structures to their matching explanations. Note that this only includes rule matches with corresponding logical insertions after the rules finished firing.
  • :query-matches -- a map of query structures to their matching explanations.
  • :condition-matches -- a map of conditions pulled from each rule to facts they match.
  • :insertions -- a map of rules to a sequence of {:explanation E, :fact F} records to allow inspection of why a given fact was inserted.
  • :fact->explanations -- a map of facts inserted to a sequence of maps of the form {:rule rule-structure :explanation explanation}, where each such map justifies a single insertion of the fact.

And additionally includes the following keys for operations performed after a with-full-logging call on the session:

  • :unfiltered-rule-matches: A map of rule structures to their matching explanations. This includes all rule activations, regardless of whether they led to insertions or if they were ultimately retracted. This should be considered low-level information primarily useful for debugging purposes rather than application control logic, although legitimate use-cases for the latter do exist if care is taken. Patterns of insertion and retraction prior to returning to the caller are internal implementation details of Clara unless explicitly controlled by the user.

Users may inspect the entire structure for troubleshooting or explore it for specific cases. For instance, the following code snippet could look at all matches for some example rule:

(defrule example-rule ... )

...

(get-in (inspect example-session) [:rule-matches example-rule])

...

The above segment will return matches for the rule in question.

Inputs: [session]

 Returns a representation of the given rule session useful to understand the
state of the underlying rules.

The returned structure always includes the following keys:

* :rule-matches -- a map of rule structures to their matching explanations.
Note that this only includes rule matches with corresponding logical 
insertions after the rules finished firing.
* :query-matches -- a map of query structures to their matching explanations.
* :condition-matches -- a map of conditions pulled from each rule to facts they match.
* :insertions -- a map of rules to a sequence of {:explanation E, :fact F} records
to allow inspection of why a given fact was inserted.
* :fact->explanations -- a map of facts inserted to a sequence 
of maps of the form {:rule rule-structure :explanation explanation}, 
where each such map justifies a single insertion of the fact.

And additionally includes the following keys for operations 
performed after a with-full-logging call on the session:

* :unfiltered-rule-matches: A map of rule structures to their matching explanations.
This includes all rule activations, regardless of whether they led to insertions or if
they were ultimately retracted.  This should be considered low-level information primarily
useful for debugging purposes rather than application control logic, although legitimate use-cases
for the latter do exist if care is taken.  Patterns of insertion and retraction prior to returning to
the caller are internal implementation details of Clara unless explicitly controlled by the user.

Users may inspect the entire structure for troubleshooting or explore it
for specific cases. For instance, the following code snippet could look
at all matches for some example rule:

(defrule example-rule ... )

...

(get-in (inspect example-session) [:rule-matches example-rule])

...

The above segment will return matches for the rule in question.
sourceraw docstring

InspectionSchemaclj

source

map->Explanationclj

(map->Explanation m26379)

Factory function for class Explanation, 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.)

Factory function for class Explanation, 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.)
sourceraw docstring

node-fn-name->production-nameclj

(node-fn-name->production-name session node-fn)

A helper function for retrieving the name or names of rules that a generated function belongs to.

'session' - a LocalSession from which a function was retrieved 'node-fn' - supports the following types:

  1. String - expected to be in the format '<namespace>/<Node abbreviation><NodeId><Function abbreviation>'. Expected use-case for string would be in the event that a user copy pasted this function identifier from an external tool, ex. a jvm profiler
  2. Symbol - expected to be in the format '<namespace>/<Node abbreviation><NodeId><Function abbreviation>. Has the same use-case as string, just adds flexibility to the type.
  3. Function - expected to be the actual function from the Session This covers a use-case where the user can capture the function being used and programmatically trace it back to the rules being executed.
A helper function for retrieving the name or names of rules that a generated function belongs to.

'session' - a LocalSession from which a function was retrieved
'node-fn' - supports the following types:
1. String   - expected to be in the format '<namespace>/<Node abbreviation>_<NodeId>_<Function abbreviation>'.
Expected use-case for string would be in the event that a user copy pasted this function identifier
from an external tool, ex. a jvm profiler
2. Symbol   - expected to be in the format '<namespace>/<Node abbreviation>_<NodeId>_<Function abbreviation>.
Has the same use-case as string, just adds flexibility to the type.
3. Function - expected to be the actual function from the Session
This covers a use-case where the user can capture the function being used and programmatically
trace it back to the rules being executed.
sourceraw docstring

strict-map->Explanationclj

(strict-map->Explanation m26380 & [drop-extra-keys?__21346__auto__])

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

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

with-full-loggingclj

Return a new session on which information will be gathered for optional inspection keys. This can significantly increase memory consumption since retracted facts cannot be garbage collected as normally.

Return a new session on which information will be gathered for optional inspection keys.
This can significantly increase memory consumption since retracted facts
cannot be garbage collected as normally.
sourceraw docstring

without-full-loggingclj

Return a new session without information gathering on this session for optional inspection keys. This new session will not retain references to any such information previously gathered.

Return a new session without information gathering on this session for optional inspection keys.
This new session will not retain references to any such information previously gathered.
sourceraw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close