sideffects
tuprolog.solve.sideffects
¶
Side effects: the changes primitives make to the state of solvers.
Primitives (predicates implemented in Python, see tuprolog.solve.primitive) never change the
state of the solver running them directly: the state they see (an
tuprolog.solve.ExecutionContext) is immutable. Instead, along with each response, they return
side effects, i.e. descriptions of changes, which the solver applies in order. This is how,
e.g., assertz/1 adds clauses to the dynamic knowledge base.
Each side effect changes one part of the state, either replacing it (reset) or adding to and removing from it:
- knowledge bases:
reset_static_kb,add_static_clauses,remove_static_clauses, and the same for the dynamic knowledge base; - flags:
set_flags,reset_flags,clear_flags; - libraries:
load_library,unload_libraries,update_library,add_libraries,reset_libraries; - operators:
set_operators,reset_operators,remove_operators; - channels:
open_input_channels,reset_input_channels,close_input_channels, and the same for output channels; - custom data (see
tuprolog.solve.data):set_persistent_data,reset_persistent_data, and the same for durable and ephemeral data.
These functions create instances of the SideEffect subclasses of the same names (e.g.
AddDynamicClauses); DEFAULT_SIDE_EFFECT_FACTORY and SideEffectsBuilder are 2P-Kt's own
factories of them.
Examples:
A primitive remember/1 adding a fact seen(X) to the dynamic knowledge base:
>>> from tuprolog.core import fact, struct
>>> from tuprolog.solve.library import library
>>> from tuprolog.solve.primitive import primitive
>>> from tuprolog.solve.prolog import prolog_solver
>>> @primitive
... def remember(request):
... seen = fact(struct("seen", request.arguments[0]))
... yield request.reply_success(None, add_dynamic_clauses(seen))
>>> solver = prolog_solver(libraries=library("my.lib", primitives={"remember/1": remember}))
>>> solver.solve_once("remember(a), remember(b)").is_yes
True
>>> list(solver.query("seen(X)"))
[{'X': 'a'}, {'X': 'b'}]
See Also
tuprolog.solve.primitive, for writing primitives.- 2P-Kt's primitives and functions.
SideEffect
module-attribute
¶
SideEffect = _sideffects.SideEffect
A change to the state of a solver, returned by a primitive along with a response.
The base class of all side effects, nested in it (e.g. SideEffect.AddDynamicClauses, also
re-exported by tuprolog.solve.sideffects). Its method apply_to(context) returns the
tuprolog.solve.ExecutionContext resulting from applying the side effect.
ResetStaticKb
module-attribute
¶
ResetStaticKb = SideEffect.ResetStaticKb
The side effect replacing the static knowledge base with clauses.
Created by reset_static_kb.
AddStaticClauses
module-attribute
¶
AddStaticClauses = SideEffect.AddStaticClauses
The side effect adding clauses to the static knowledge base, first if on_top.
Created by add_static_clauses.
RemoveStaticClauses
module-attribute
¶
RemoveStaticClauses = SideEffect.RemoveStaticClauses
The side effect removing clauses from the static knowledge base.
Created by remove_static_clauses.
ResetDynamicKb
module-attribute
¶
ResetDynamicKb = SideEffect.ResetDynamicKb
The side effect replacing the dynamic knowledge base with clauses.
Created by reset_dynamic_kb.
AddDynamicClauses
module-attribute
¶
AddDynamicClauses = SideEffect.AddDynamicClauses
The side effect adding clauses to the dynamic knowledge base, first if on_top.
Created by add_dynamic_clauses.
RemoveDynamicClauses
module-attribute
¶
RemoveDynamicClauses = SideEffect.RemoveDynamicClauses
The side effect removing clauses from the dynamic knowledge base.
Created by remove_dynamic_clauses.
SetFlags
module-attribute
¶
SetFlags = SideEffect.SetFlags
The side effect setting flags (a map from names to terms), keeping the other flags.
Created by set_flags.
ResetFlags
module-attribute
¶
ResetFlags = SideEffect.ResetFlags
The side effect replacing all the flags with flags.
Created by reset_flags.
ClearFlags
module-attribute
¶
ClearFlags = SideEffect.ClearFlags
The side effect removing the flags with the given names.
Created by clear_flags.
LoadLibrary
module-attribute
¶
LoadLibrary = SideEffect.LoadLibrary
The side effect loading library into the solver.
Created by load_library.
UnloadLibraries
module-attribute
¶
UnloadLibraries = SideEffect.UnloadLibraries
The side effect unloading the libraries with the given aliases.
Created by unload_libraries.
UpdateLibrary
module-attribute
¶
UpdateLibrary = SideEffect.UpdateLibrary
The side effect replacing the loaded library with the alias of library.
Created by update_library.
AddLibraries
module-attribute
¶
AddLibraries = SideEffect.AddLibraries
The side effect loading the libraries of a runtime into the solver.
Created by add_libraries.
ResetRuntime
module-attribute
¶
ResetRuntime = SideEffect.ResetRuntime
The side effect replacing all the loaded libraries with libraries.
Created by reset_libraries.
SetOperators
module-attribute
¶
SetOperators = SideEffect.SetOperators
The side effect adding operators, overriding those with the same symbol and notation.
Created by set_operators.
ResetOperators
module-attribute
¶
ResetOperators = SideEffect.ResetOperators
The side effect meant to replace all the operators with operators.
Created by reset_operators.
Note
In 2P-Kt 3.0, it adds operators to the existing ones instead, like SetOperators.
RemoveOperators
module-attribute
¶
RemoveOperators = SideEffect.RemoveOperators
The side effect removing operators.
Created by remove_operators.
OpenInputChannels
module-attribute
¶
OpenInputChannels = SideEffect.OpenInputChannels
The side effect adding input channels, by alias.
Created by open_input_channels.
ResetInputChannels
module-attribute
¶
ResetInputChannels = SideEffect.ResetInputChannels
The side effect replacing all the input channels.
Created by reset_input_channels.
CloseInputChannels
module-attribute
¶
CloseInputChannels = SideEffect.CloseInputChannels
The side effect closing and removing the input channels with the given names.
Created by close_input_channels.
OpenOutputChannels
module-attribute
¶
OpenOutputChannels = SideEffect.OpenOutputChannels
The side effect adding output channels, by alias.
Created by open_output_channels.
ResetOutputChannels
module-attribute
¶
ResetOutputChannels = SideEffect.ResetOutputChannels
The side effect replacing all the output channels.
Created by reset_output_channels.
CloseOutputChannels
module-attribute
¶
CloseOutputChannels = SideEffect.CloseOutputChannels
The side effect closing and removing the output channels with the given names.
Created by close_output_channels.
SetPersistentData
module-attribute
¶
SetPersistentData = SideEffect.SetPersistentData
The side effect adding data to the persistent custom data, or replacing it if reset.
Created by set_persistent_data.
SetDurableData
module-attribute
¶
SetDurableData = SideEffect.SetDurableData
The side effect adding data to the durable custom data, or replacing it if reset.
Created by set_durable_data.
SetEphemeralData
module-attribute
¶
SetEphemeralData = SideEffect.SetEphemeralData
The side effect adding data to the ephemeral custom data, or replacing it if reset.
Created by set_ephemeral_data.
SideEffectFactory
module-attribute
¶
SideEffectFactory = _sideffects.SideEffectFactory
2P-Kt's factory of side effects, with one method per side effect (e.g. add_dynamic_clauses).
The functions of tuprolog.solve.sideffects are a more Pythonic alternative.
DEFAULT_SIDE_EFFECT_FACTORY
module-attribute
¶
DEFAULT_SIDE_EFFECT_FACTORY = SideEffectFactory.getDefault()
2P-Kt's default SideEffectFactory.
SideEffectManager
module-attribute
¶
SideEffectManager = _sideffects.SideEffectManager
A manager of the changes primitives make to the flow of resolution, i.e. the effects of cuts.
Primitives may attach one to their responses, to make resolution behave as if a cut (!/0) had
been executed, i.e. discarding pending alternatives.
SideEffectsBuilder
module-attribute
¶
SideEffectsBuilder = _sideffects.SideEffectsBuilder
2P-Kt's builder of lists of side effects: a SideEffectFactory collecting what it creates.
Its build() method returns the side effects created so far, in order.
reset_static_kb
¶
reset_static_kb(
*clauses: Clause | Iterable[Clause],
) -> ResetStaticKb
Creates the side effect replacing the static knowledge base with the given clauses.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*clauses
|
Clause | Iterable[Clause]
|
The clauses ( |
()
|
Returns:
| Type | Description |
|---|---|
ResetStaticKb
|
The |
add_static_clauses
¶
add_static_clauses(
*clauses: Clause | Iterable[Clause],
on_top: bool = False,
) -> AddStaticClauses
Creates the side effect adding clauses to the static knowledge base.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*clauses
|
Clause | Iterable[Clause]
|
The clauses ( |
()
|
on_top
|
bool
|
Whether to add them before the existing clauses, rather than after. |
False
|
Returns:
| Type | Description |
|---|---|
AddStaticClauses
|
The |
remove_static_clauses
¶
remove_static_clauses(
*clauses: Clause | Iterable[Clause],
) -> RemoveStaticClauses
Creates the side effect removing clauses from the static knowledge base.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*clauses
|
Clause | Iterable[Clause]
|
The clauses ( |
()
|
Returns:
| Type | Description |
|---|---|
RemoveStaticClauses
|
The |
reset_dynamic_kb
¶
reset_dynamic_kb(
*clauses: Clause | Iterable[Clause],
) -> ResetDynamicKb
Creates the side effect replacing the dynamic knowledge base with the given clauses.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*clauses
|
Clause | Iterable[Clause]
|
The clauses ( |
()
|
Returns:
| Type | Description |
|---|---|
ResetDynamicKb
|
The |
add_dynamic_clauses
¶
add_dynamic_clauses(
*clauses: Clause | Iterable[Clause],
on_top: bool = False,
) -> AddDynamicClauses
Creates the side effect adding clauses to the dynamic knowledge base, as assertz/1 does.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*clauses
|
Clause | Iterable[Clause]
|
The clauses ( |
()
|
on_top
|
bool
|
Whether to add them before the existing clauses (as |
False
|
Returns:
| Type | Description |
|---|---|
AddDynamicClauses
|
The |
Examples:
>>> from tuprolog.core import atom, fact
>>> add_dynamic_clauses(fact(atom("a")), on_top=True)
AddDynamicClauses(clauses=[a :- true], onTop=true)
remove_dynamic_clauses
¶
remove_dynamic_clauses(
*clauses: Clause | Iterable[Clause],
) -> RemoveDynamicClauses
Creates the side effect removing clauses from the dynamic knowledge base.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*clauses
|
Clause | Iterable[Clause]
|
The clauses ( |
()
|
Returns:
| Type | Description |
|---|---|
RemoveDynamicClauses
|
The |
set_flags
¶
Creates the side effect setting flags, keeping the other ones.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
flags
|
Mapping[str, Term]
|
The flags' values (terms), by name. |
{}
|
**kwargs
|
Term
|
More flags' values, by name. |
{}
|
Returns:
| Type | Description |
|---|---|
SetFlags
|
The |
Examples:
>>> from tuprolog.core import atom
>>> set_flags(unknown=atom("fail"))
SetFlags(flags={unknown=fail})
reset_flags
¶
reset_flags(
flags: Mapping[str, Term] = {}, **kwargs: Term
) -> ResetFlags
Creates the side effect replacing all the flags with the given ones.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
flags
|
Mapping[str, Term]
|
The flags' values (terms), by name. |
{}
|
**kwargs
|
Term
|
More flags' values, by name. |
{}
|
Returns:
| Type | Description |
|---|---|
ResetFlags
|
The |
clear_flags
¶
clear_flags(*flag_names: str) -> ClearFlags
Creates the side effect removing the flags with the given names.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*flag_names
|
str
|
The names of the flags. |
()
|
Returns:
| Type | Description |
|---|---|
ClearFlags
|
The |
Examples:
>>> clear_flags("my_flag", "other_flag")
ClearFlags(names=[my_flag, other_flag])
load_library
¶
load_library(alias: str, library: Library) -> LoadLibrary
Creates the side effect loading a library, under the given alias.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
alias
|
str
|
The alias of the library, e.g. |
required |
library
|
Library
|
The library (see |
required |
Returns:
| Type | Description |
|---|---|
LoadLibrary
|
The |
unload_libraries
¶
unload_libraries(*aliases: str) -> UnloadLibraries
Creates the side effect unloading the libraries with the given aliases.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*aliases
|
str
|
The aliases of the libraries, as varargs or as a single iterable. |
()
|
Returns:
| Type | Description |
|---|---|
UnloadLibraries
|
The |
update_library
¶
update_library(
alias: str, library: Library
) -> UpdateLibrary
Creates the side effect replacing the loaded library with the given alias.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
alias
|
str
|
The alias of the library to replace. |
required |
library
|
Library
|
The new library, loaded under |
required |
Returns:
| Type | Description |
|---|---|
UpdateLibrary
|
The |
add_libraries
¶
add_libraries(*libraries: Library) -> AddLibraries
Creates the side effect loading the given libraries.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*libraries
|
Library
|
The libraries (see |
()
|
Returns:
| Type | Description |
|---|---|
AddLibraries
|
The |
reset_libraries
¶
reset_libraries(*libraries: Library) -> ResetRuntime
Creates the side effect replacing all the loaded libraries with the given ones.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*libraries
|
Library
|
The libraries (see |
()
|
Returns:
| Type | Description |
|---|---|
ResetRuntime
|
The |
set_operators
¶
set_operators(
*operators: Operator | Iterable[Operator],
) -> SetOperators
Creates the side effect adding operators, as op/3 does.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*operators
|
Operator | Iterable[Operator]
|
The operators ( |
()
|
Returns:
| Type | Description |
|---|---|
SetOperators
|
The |
reset_operators
¶
reset_operators(
*operators: Operator | Iterable[Operator],
) -> ResetOperators
Creates the side effect meant to replace all the operators with the given ones.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*operators
|
Operator | Iterable[Operator]
|
The operators ( |
()
|
Returns:
| Type | Description |
|---|---|
ResetOperators
|
The |
Note
In 2P-Kt 3.0, the side effect adds the operators to the existing ones instead.
remove_operators
¶
remove_operators(
*operators: Operator | Iterable[Operator],
) -> RemoveOperators
Creates the side effect removing operators.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*operators
|
Operator | Iterable[Operator]
|
The operators ( |
()
|
Returns:
| Type | Description |
|---|---|
RemoveOperators
|
The |
open_input_channels
¶
open_input_channels(
channels: Mapping[str, InputChannel] = {},
**kwargs: InputChannel,
) -> OpenInputChannels
Creates the side effect adding input channels.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channels
|
Mapping[str, InputChannel]
|
The input channels ( |
{}
|
**kwargs
|
InputChannel
|
More input channels, by alias. |
{}
|
Returns:
| Type | Description |
|---|---|
OpenInputChannels
|
The |
reset_input_channels
¶
reset_input_channels(
channels: Mapping[str, InputChannel] = {},
**kwargs: InputChannel,
) -> ResetInputChannels
Creates the side effect replacing all the input channels with the given ones.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channels
|
Mapping[str, InputChannel]
|
The input channels ( |
{}
|
**kwargs
|
InputChannel
|
More input channels, by alias. |
{}
|
Returns:
| Type | Description |
|---|---|
ResetInputChannels
|
The |
close_input_channels
¶
close_input_channels(
*names: str | Iterable[str],
) -> CloseInputChannels
Creates the side effect closing and removing the input channels with the given aliases.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*names
|
str | Iterable[str]
|
The aliases of the channels, as varargs or as a single iterable. |
()
|
Returns:
| Type | Description |
|---|---|
CloseInputChannels
|
The |
open_output_channels
¶
open_output_channels(
channels: Mapping[str, OutputChannel] = {},
**kwargs: OutputChannel,
) -> OpenOutputChannels
Creates the side effect adding output channels.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channels
|
Mapping[str, OutputChannel]
|
The output channels ( |
{}
|
**kwargs
|
OutputChannel
|
More output channels, by alias. |
{}
|
Returns:
| Type | Description |
|---|---|
OpenOutputChannels
|
The |
reset_output_channels
¶
reset_output_channels(
channels: Mapping[str, OutputChannel] = {},
**kwargs: OutputChannel,
) -> ResetOutputChannels
Creates the side effect replacing all the output channels with the given ones.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channels
|
Mapping[str, OutputChannel]
|
The output channels ( |
{}
|
**kwargs
|
OutputChannel
|
More output channels, by alias. |
{}
|
Returns:
| Type | Description |
|---|---|
ResetOutputChannels
|
The |
close_output_channels
¶
close_output_channels(
*names: str | Iterable[str],
) -> CloseOutputChannels
Creates the side effect closing and removing the output channels with the given aliases.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*names
|
str | Iterable[str]
|
The aliases of the channels, as varargs or as a single iterable. |
()
|
Returns:
| Type | Description |
|---|---|
CloseOutputChannels
|
The |
set_persistent_data
¶
set_persistent_data(
data: Mapping[str, Any] = {}, **kwargs: Any
) -> SetPersistentData
Creates the side effect adding values to the persistent custom data.
The persistent custom data lives as long as the solver (see tuprolog.solve.data); the given
values replace those with the same keys.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
Mapping[str, Any]
|
The values, by key. |
{}
|
**kwargs
|
Any
|
More values, by key. |
{}
|
Returns:
| Type | Description |
|---|---|
SetPersistentData
|
The |
reset_persistent_data
¶
reset_persistent_data(
data: Mapping[str, Any] = {}, **kwargs: Any
) -> SetPersistentData
Creates the side effect replacing the persistent custom data with the given values.
The persistent custom data lives as long as the solver (see tuprolog.solve.data).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
Mapping[str, Any]
|
The values, by key. |
{}
|
**kwargs
|
Any
|
More values, by key. |
{}
|
Returns:
| Type | Description |
|---|---|
SetPersistentData
|
The |
Examples:
>>> reset_persistent_data(counter=0)
SetPersistentData(data={counter=0}, reset=true)
set_durable_data
¶
set_durable_data(
data: Mapping[str, Any] = {}, **kwargs: Any
) -> SetDurableData
Creates the side effect adding values to the durable custom data.
The durable custom data lives during a query (see tuprolog.solve.data); the given
values replace those with the same keys.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
Mapping[str, Any]
|
The values, by key. |
{}
|
**kwargs
|
Any
|
More values, by key. |
{}
|
Returns:
| Type | Description |
|---|---|
SetDurableData
|
The |
reset_durable_data
¶
reset_durable_data(
data: Mapping[str, Any] = {}, **kwargs: Any
) -> SetDurableData
Creates the side effect replacing the durable custom data with the given values.
The durable custom data lives during a query (see tuprolog.solve.data).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
Mapping[str, Any]
|
The values, by key. |
{}
|
**kwargs
|
Any
|
More values, by key. |
{}
|
Returns:
| Type | Description |
|---|---|
SetDurableData
|
The |
set_ephemeral_data
¶
set_ephemeral_data(
data: Mapping[str, Any] = {}, **kwargs: Any
) -> SetEphemeralData
Creates the side effect adding values to the ephemeral custom data.
The ephemeral custom data is the first to be discarded (see tuprolog.solve.data); the given
values replace those with the same keys.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
Mapping[str, Any]
|
The values, by key. |
{}
|
**kwargs
|
Any
|
More values, by key. |
{}
|
Returns:
| Type | Description |
|---|---|
SetEphemeralData
|
The |
reset_ephemeral_data
¶
reset_ephemeral_data(
data: Mapping[str, Any] = {}, **kwargs: Any
) -> SetEphemeralData
Creates the side effect replacing the ephemeral custom data with the given values.
The ephemeral custom data is the first to be discarded (see tuprolog.solve.data).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
Mapping[str, Any]
|
The values, by key. |
{}
|
**kwargs
|
Any
|
More values, by key. |
{}
|
Returns:
| Type | Description |
|---|---|
SetEphemeralData
|
The |