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

compile-profiles->fsms clj/s

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

Take profiles, a collection of Profiles, and returns a map of the following form:

{
  profile-version {
    pattern-id {
      :id ...
      :dfa ...
      :nfa ...
    }
  }
}

where profile-version is the Profile version ID and pattern-id is the ID of a primary Pattern in that Profile. The FSM map keys are as follows:

FSM Map Key	Description
: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 keyword arguments:

Keyword Argument	Description
: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.
:validate-not-empty?	If true, asserts that at least one Pattern FSM map is present after compilation in general and for each Profile. Default true.
:compile-nfa?	If true compiles an additional NFA that is used for composing detailed error traces. Default false.
:selected-profiles	Coll that, 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	Coll that, 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? validate-not-empty?
          selected-profiles selected-templates]
   :or {validate-profiles? true validate-not-empty? 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:

Keyword Argument	Description
: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.
:validate-not-empty?	Whether to assert that compilation produced at least one Template validator; 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 present in the coll.

If there are no Templates after selected-templates filtering, or if no Templates exist in profiles, this throws an ::no-templates exn.

compile-templates->validators clj/s

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

Takes a templates coll and returns a coll of maps:

Validator Map Key	Description
: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:

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

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

Argument Map Key	Description
:get-template-fn	A function or map that takes a Template ID and returns the Template, or nil if not found. See also: template.statement-ref/profile->id-template-map.
:get-statement-fn	A function or map that takes a Statement ID and returns the Statement, or nil if not found.

If there are no Templates after selected-templates filtering, or if an empty templates is provided in the first place, this throws an ::no-templates exception.

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 with the following keys:

Map Key	Description
:accepts	A vector of [registration-key pattern-id] key paths for accepted state infos (where :accepted? is true).
:rejects	A vecotr of [registration-key pattern-id] for rejected state infos (where they are empty sets).
:states-map	A map of the form {registration-key {pattern-id state-info}}}

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 keys:

Map Key	Description
: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, this function returns the map

{
  :error {
    :type error-kw
    :statement {...}
  }
}

where error-kw is one of the following:

Pattern Match Error Keyword	Description
::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 (instead of a single Statement) 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:

Keyword Argument	Description
: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 a map from Template IDs to error data for every Template the Statement is invalid against, nil if any Template is valid for statement.
: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 (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.