module(?Module)

Sets up Situation using Module. Establishes the dynamic predicate options for the temporary situation module used for persisting situation Now-At and Was-When tuples.

An important side effect occurs for ground Situation terms. The implementation creates the situation's temporary module and applies default options to its new dynamic predicates. The module(Module) term unifies with the newly-created or existing situation module.

The predicate's determinism collapses to semi-determinism for ground situations. Otherwise with variable Situation components, the predicate unifies with all matching situations, unifying with module(Module) non-deterministically.

now(+Now:any)

now(+Now:any, +At:number)

Makes some Situation become Now for time index At, at the next fixation. Effectively schedules a pending update one or more times; the next situation fix/0 fixes the pending situation changes at some future point. The now/1 form applies Now to Situation at the current Unix epoch time.

Uses apply_to_situation/2 when Situation is ground, but uses property_of_situation/2 otherwise. Asserts therefore for multiple situations if Situation comprises variables. You cannot therefore have non-ground situations.

fix

fix(+Now:any)

Fixating situations does three important things. First, it adds new Previous-When pairs to the situation history. They become was/2 dynamic facts (clauses without rules). Second, it adds, replaces or removes the most current Current-When pair. This allows detection of non-events, e.g. when something disappears. Some types of situation might require such event edges. Finally, fixating broadcasts situation-change messages.

The rule for fixing the Current-When pair goes like this: Is there a new now/2, at least one? The latest becomes the new current. Any others become Previous-When. If there is no now/2, then the current disappears. Messages broadcast accordingly. If there is more than one now/2, only the latest becomes current. Hence currently-previously only transitions once in-between fixations.

Term fix/1 is a shortcut for now(Now, At) and fix where At becomes the current Unix epoch time. Fixes but does not retract history terms.

retract(+When:number)

retract(?When:number, +Delay:number)

Retracts all was/2 clauses for all matching Situation terms. Term retract(_, Delay) retracts all was/2 history terms using the last term's latest time stamp. In this way, you can retract situations without knowing their absolute time. For example, you can retract everything older than 60 seconds from the last known history term when you retract(_, 60).

The second argument Apply can be a list of terms to apply, including nested lists of terms. All terms apply in order first to last, and depth first.

Arguments:

Now	- is the state of a Situation at some point in time. The Now term must be non-variable but not necessarily ground. Dictionaries with unbound tags can exist within the situation calculus.

module(?Module)

Marries situation terms with universally-unique modules, one for one. All dynamic situations link a situation term with a module. This design addresses performance. Retracts take a long time, relatively, especially for dynamic predicates with very many clauses; upwards of 10,000 clauses for example. Note, you can never delete the situation-module association, but you can retract all the dynamic clauses belonging to a situation.

defined

Situation is defined whenever a unique situation module already exists for the given Situation. Amounts to the same as asking for module(_) property.

currently(?Current:any)

currently(?Current:any, ?When:number)

currently(Current:any,for(Seconds:number))

Unifies with Current for Situation and When it happened. Unifies with the one and only Current state for all the matching Situation terms. Unifies non-deterministically for all Situation solutions, but semi-deterministically for Current state. Thus allows for multiple matching situations but only one Current solution.

You can replace the When term with for(Seconds) in order to measure elapsed interval since fixing Situation. Same applies to previously/2 except that the current situation time stamp serves as the baseline time, else defaults to the current time.

previously(?Previous:any)

previously(?Previous:any, ?When:number)

previously(Previous:any,for(Seconds:number))

Finds Previous state of Situation, non-deterministically resolving zero or more matching Situation terms. Fails if no previous Situation condition.

history(?History:list(compound))

Unifies History with all current and previous situation conditions, including their time stamps. History is a sequence of compounds of the form was(Was, When) where Situation is effectively a primitive condition coordinate, Was is a sensing outcome and When marks the moment that the outcome transpired.