com.yetanalytics.persephone — com.yetanalytics/project-persephone 0.8.2

compile-profiles->fsms clj/s

(compile-profiles->fsms profiles
                        &
                        {:keys [statement-ref-fns validate-profiles?
                                compile-nfa? selected-profiles
                                selected-patterns]
                         :or {validate-profiles? true compile-nfa? false}})

Take profiles, a collection of JSON-LD profiles (or equivalent EDN data) and returns a map of the following form:

{ profile-version { pattern-id {:id ... :dfa ... :nfa ...} } } Where profile-version is the latest profile version ID in the Profile and pattern-id is the ID of a primary Pattern in that Profile. The leaf values include the following:

:id The pattern ID. :dfa The DFA used for general pattern matching. :nfa The NFA with pattern metadata used for reconstructing the pattern path. This is an optional property that is only produced when :compile-nfa? is true. :nfa-meta The NFA metadata; assoc-ed here in case meta is lost from the :nfa value. Only present if :nfa is. The following are optional arguments:

:statement-ref-fns takes the key-value pairs described in template->validator. :validate-profiles? if true checks that all Profiles conform to the xAPI Profile spec and that all Profile, Template, and Pattern IDs do not clash. Throws exception if validation fails. Default true. :compile-nfa? if true compiles an additional NFA that is used for composing detailed error traces. Default false. :selected-profiles if present filters out any profiles whose IDs are not in the coll. (Note that these should be profile IDs, not profile version IDs.) :selected-patterns if present filters out any primary patterns whose IDs are not in the coll.

compile-profiles->validators clj/s

(compile-profiles->validators profiles
                              &
                              {:keys [statement-ref-fns validate-profiles?
                                      selected-profiles selected-templates]
                               :or {validate-profiles? true}})

Takes a profiles coll and returns a coll of maps of :id, :validator-fn, and :predicate-fn, just like with compile-templates->validators. Takes the following kwargs:

:statement-ref-fns Same as in compile-templates->validators. :validate-profiles? Whether to validate against the Profile spec and check for ID clashes before compilation; default true. :selected-profiles if present filters out any Profiles whose IDs are not in the coll. (Note that these should be profile IDs, not version IDs.) :selected-templates if present filters out any Templates whose IDs are not in the coll.

compile-templates->validators clj/s

(compile-templates->validators templates
                               &
                               {:keys [statement-ref-fns validate-templates?
                                       selected-templates]
                                :or {validate-templates? true}})

Takes a templates coll and returns a coll of maps of:

:id The Statement Template ID :validator-fn A function that returns error data if a Statement is invalid against the Template, else nil. :predicate-fn A function that returns true if a Statement is valid against the Template, else false.

compile-templates->validators takes the following kwargs:

:statement-ref-fns A map with two fields: :get-template-fn and get-statement-fn. If not present, then any Template's StatementRef props are ignored. :validate-template? Whether to validate against the Template spec and check for ID clashes before compilation; default true. :selected-profiles if present filters out any Profiles whose IDs are not in the coll. (Note that these should be profile IDs, not version IDs.) :selected-templates if present filters out any Templates whose IDs are not in the coll.

The following are the fields of the :statement-ref-fns map:

:get-template-fn Function that takes a Statement Template ID and returns the corresponding Template. Can be created using profile->id-template-map. Must return nil if the Template isn't found. :get-statement-fn Function that takes a Statement ID and returns the corresponding Statement. Must return nil if the Statement is not found.

compiled-profiles-spec clj/s

A compiled profiles spec: a map from profile IDs to another map of pattern IDs (from that profile) to a map of compiled FSMs.

compiled-template-spec clj/s

Spec for a compiled template: a map of the template :id, a :validator-fn, and a :predicate-fn.

compiled-templates-spec clj/s

Spec for a coll of compiled template maps.

match-statement clj/s

(match-statement compiled-profiles
                 state-info-map
                 statement
                 &
                 {:keys [print?] :or {print? false}})

Takes compiled-profiles, state-info-map, and statement, where compiled-profiles is a return value of compile-profiles->fsms. Matches statement to against compiled-profiles and returns an updated value of state-info-map.

state-info-map is a map of the form:

{:accepts [[registration-key pattern-id] ...] :rejects [[registration-key pattern-id] ...] :states-map {registration-key {pattern-id state-info}}} where

:accepts is a coll of identifiers for accepted state infos (where :accepted? is true). :rejects is a coll of identifiers for rejected state infos (where they are empty sets). :states-map is a doubly-nested map that associates registration keys and pattern IDs to state info maps.

registration-key can either be a registration UUID or a pair of registration and subregistration UUIDs. Statements without registrations will be assigned a default :no-registration key.

state-info is a map of the following:

:state The current state in the FSM, i.e. where is the current location in the Pattern? :accepted? If that state is an accept state, i.e. did the inputs fully match the Pattern? :visited The vec of visited Statement Templates; this is only present if compiled-profiles was compiled with compile-nfa? set to true.

On error, returns the map

{:error {:type error-kw :statement {...}}} where error-kw is one of the following:

::missing-profile-reference if statement does not have a Profile ID from compiled-profiles as a category context activity. ::invalid-subreg-no-registration if a sub-registration is present without a registration. ::invalid-subreg-nonconformant if the sub-registration extension value is invalid.

match-statement takes in an optional :print? kwarg; if true, then prints any error or match failure.

match-statement-batch clj/s

(match-statement-batch compiled-profiles
                       state-info-map
                       statement-batch
                       &
                       {:keys [print?] :or {print? false}})

Similar to match-statement, except takes a batch of statements and sorts them by timestamp before matching. Short-circuits if an error (e.g. missing Profile ID reference) is detected.

registration-key-spec clj/s

Spec for a registration key - either a single registration UUID string or a vector pair of a registration and subregistration UUID.

state-info-map-spec clj/s

Spec for an individual state info map.

state-info-meta-spec clj/s

Spec for failure metadata: a nilable map of ::pattern.failure/failure.

state-info-spec clj/s

Spec for state info + failure metadata.

statement-error-spec clj/s

Spec for a statement error (e.g. during match error).

stmt-error-spec clj/s deprecated

validate-statement clj/s

(validate-statement
  compiled-templates
  statement
  &
  {:keys [fn-type all-valid? short-circuit?]
   :or {fn-type :predicate all-valid? false short-circuit? false}})

Takes compiled-templates and statement where compiled-templates is the result of compile-profiles->validators, and validates statement against the Statement Templates in the Profile.

Takes a :fn-type kwarg, which sets the return value and side effects of validate-statement. Has the following options:

:predicate Returns true if statement is valid for any Statement Template, else false. Default. :filter Returns statement if it is valid against any Template, else nil. :errors Returns validation error data on every Template the Statement is invalid against, nil if any Template is valid for statement. The error data is a map from Template ID to error data. :templates Returns the IDs of the Templates that statement is valid against. :printer Prints the error data for all Templates the Statement fails validation against, if every Template is invalid for statement :assertion Throws an exception upon validation failure (where (-> e ex-data :errors) returns all error data) if every Template is invalid for statement, else returnsnil.

Note that the above descriptions are only for when the kwargs :all-valid? and :short-circuit? are false (the default).

If :all-valid? is true, then the validation is not considered true unless all Templates are valid against statement. If :short-circuit? is true, then only the error data for the first invalid Template is returned.

validate-statement-assert clj/s

(validate-statement-assert compiled-templates
                           statement
                           &
                           {:keys [all-valid? short-circuit?]
                            :or {all-valid? false short-circuit? false}})

Throw an ExceptionInfo exception when statement is invalid against Templates in compiled-templates, returns nil otherwise. :all-valid? and :short-circuit? are the same as in the validate-statement-errors function.

validate-statement-errors clj/s

(validate-statement-errors compiled-templates
                           statement
                           &
                           {:keys [all-valid? short-circuit?]
                            :or {all-valid? false short-circuit? false}})

Returns map from Template IDs to error data maps for each Template that statement is invalid against. Takes the :all-valid? and :short-circuit? kwargs; the former denotes whether to return nil if any (default) or all Templates are valid against statement; the latter determines whether to return the first error (if true) or all errors (if false, default).

validate-statement-filter clj/s

(validate-statement-filter compiled-templates
                           statement
                           &
                           {:keys [all-valid?] :or {all-valid? false}})

Returns statement if it is valid against any Template (if :all-valid? is true, default) or all Templates (if it is false) in compiled-templates, nil otherwise.

validate-statement-print clj/s

(validate-statement-print compiled-templates
                          statement
                          &
                          {:keys [all-valid? short-circuit?]
                           :or {all-valid? false short-circuit? false}})

Prints errors for each Template that statement is invalid against. :all-valid? and :short-circuit? are the same as in the validate-statement-errors function.

validate-statement-template-ids clj/s

(validate-statement-template-ids compiled-templates statement)

Returns a vector of all the Template IDs that statement is valid against.

validated-statement? clj/s

(validated-statement? compiled-templates
                      statement
                      &
                      {:keys [all-valid?] :or {all-valid? false}})

Returns true if statement is valid against any Template (if :all-valid? is false, default) or all Templates (if it is true) in compiled-templates, false otherwise.

validation-error-map-spec clj/s

Spec for validation error: a map from the template ID to a validation result map containing :stmt, :temp, :pred, :vals, and either :prop or :sref.