flags

tuprolog.solve.flags

Prolog flags: named settings configuring the behaviour of solvers.

A flag is a name bound to a term, e.g. unknown to warning, read and changed by Prolog programs via current_prolog_flag/2 and set_prolog_flag/2. Notable flags are the flags solvers know: their admissible values and defaults are known in advance (see NotableFlag). ISO Prolog defines some (unknown, double_quotes, max_arity), 2P-Kt others.

Main types, constants and functions:

• FlagStore: an immutable set of flags, by name; solvers have one (Solver.flags);
• Flag: a (name, value) pair;
• NotableFlag, and the notable flags Unknown, DoubleQuotes, MaxArity, LastCallOptimization, TrackVariables, UniqueSolutions, ShowWildCardVariablesInSolutions, GroundQueriesHaveBooleanSolution;
• DEFAULT_FLAG_STORE: the notable flags, with their default values; EMPTY_FLAG_STORE;
• flag and flag_store: create flags and flag stores.

Examples:

>>> from tuprolog.solve.prolog import prolog_solver
>>> solver = prolog_solver(flags=flag_store(DEFAULT_FLAG_STORE, unknown="fail"))
>>> solver.flags["unknown"]
fail
>>> solver.solve_once("undefined_predicate").is_no
True
>>> solver.solve_once("current_prolog_flag(max_arity, X)")["X"]
2147483647

See Also

• tuprolog.solve.sideffects.set_flags, for primitives changing flags.
• 2P-Kt's solver design.

FlagStore module-attribute

FlagStore = _flags.FlagStore

An immutable set of flags: a JVM map from flag names (strings) to values (terms).

Changes return new stores: set(name, value), plus(...) (a flag, a notable flag set to its default value, or another store), minus(...) (names). Python additions:

• len(store), name in store (also for notable flags), and the JVM map's keys(), values() and items();
• store[name] (also for notable flags) returns the value of a flag, raising KeyError if there is none;
• store + other merges a Flag, a NotableFlag, another store, or a dict from names to terms or Python values (later values override earlier ones); store - name removes a flag (also a notable one).

Create stores with flag_store, or start from DEFAULT_FLAG_STORE or EMPTY_FLAG_STORE.

Examples:

>>> store = EMPTY_FLAG_STORE + Unknown + {"my_flag": "on"}
>>> len(store), "unknown" in store, store[Unknown], store["my_flag"]
(2, True, warning, on)
>>> store["missing"]
Traceback (most recent call last):
    ...
KeyError: 'missing'
>>> store - "my_flag"
FlagStore(flags={unknown=warning})

NotableFlag module-attribute

NotableFlag = _flags.NotableFlag

A flag known to solvers, whose admissible values and default value are known in advance.

Members: name, default_value, admissible_values (a set of terms), is_admissible_value(term), is_editable (whether programs can change it), help (a description), to_pair() (the Flag setting it to its default value), and to(value) (the Flag setting it to value).

Examples:

>>> Unknown.name, Unknown.default_value
('unknown', warning)
>>> MaxArity.is_editable
False

Flag module-attribute

Flag = Pair

A flag: a (name, value) pair, i.e. 2P-Kt's kotlin.Pair of a string and a term.

Its members are first (the name) and second (the value); create flags with flag.

EMPTY_FLAG_STORE module-attribute

EMPTY_FLAG_STORE: FlagStore = FlagStore.EMPTY

The flag store with no flags.

DEFAULT_FLAG_STORE module-attribute

DEFAULT_FLAG_STORE: FlagStore = FlagStore.DEFAULT

The flag store with all the notable flags, set to their default values, which solvers use by default.

Examples:

>>> sorted(DEFAULT_FLAG_STORE.keys())
['double_quotes', 'ground_queries_have_boolean_solution', 'last_call_optimization',
 'max_arity', 'show_wildcard_variables_in_solutions', 'track_variables', 'unique_solutions',
 'unknown']

DoubleQuotes module-attribute

DoubleQuotes: NotableFlag = _flags.DoubleQuotes.INSTANCE

ISO Prolog's double_quotes flag: how double-quoted text is parsed.

2P-Kt only supports atom (its default): "some text" is read as an atom.

GroundQueriesHaveBooleanSolution module-attribute

GroundQueriesHaveBooleanSolution: NotableFlag = (
    _flags.GroundQueriesHaveBooleanSolution.INSTANCE
)

The ground_queries_have_boolean_solution flag: how yes solutions of ground queries are shown.

A query is ground if it has no variables. If on, solution formatters show its yes solutions as yes.; if off (the default), they also show the solved query. The solutions do not change.

LastCallOptimization module-attribute

LastCallOptimization: NotableFlag = (
    _flags.LastCallOptimization.INSTANCE
)

The last_call_optimization flag: whether solvers optimize tail calls (on, the default).

With the optimization, a goal calling a predicate as the last goal of a clause body does not grow the solver's stack, so deep recursions need constant memory.

MaxArity module-attribute

MaxArity: NotableFlag = _flags.MaxArity.INSTANCE

ISO Prolog's max_arity flag: the maximum arity of predicates and functions (read-only).

2P-Kt sets no practical limit: its value is the largest JVM integer, 2147483647.

ShowWildCardVariablesInSolutions module-attribute

ShowWildCardVariablesInSolutions: NotableFlag = (
    _flags.ShowWildCardVariablesInSolutions.INSTANCE
)

The show_wildcard_variables_in_solutions flag: whether solutions bind wildcard variables.

Wildcard variables are those whose name starts with _ (e.g. _X); if off, their bindings are left out of the substitutions of solutions; if on (the default), they are kept.

TrackVariables module-attribute

TrackVariables: NotableFlag = _flags.TrackVariables.INSTANCE

The track_variables flag: whether solvers keep additional information about variables.

off by default; ProbLog solvers turn it on, as they need it to compute probabilities.

UniqueSolutions module-attribute

UniqueSolutions: NotableFlag = (
    _flags.UniqueSolutions.INSTANCE
)

The unique_solutions flag: whether solvers drop duplicate yes solutions.

If on, only the first yes solution with a given solved query is kept (e.g. member(X, [1, 1]) has one solution); if off (the default), duplicates are kept, as in standard Prolog.

Unknown module-attribute

Unknown: NotableFlag = _flags.Unknown.INSTANCE

ISO Prolog's unknown flag: what happens when calling a predicate that does not exist.

Its values are error (resolution halts with an existence error), warning (the default: a warning is reported on the solver's warnings channel, and the call fails), and fail (the call silently fails).

Examples:

>>> from tuprolog.solve.flags import flag_store
>>> from tuprolog.solve.prolog import prolog_solver
>>> solution = prolog_solver(flags=flag_store(unknown="error")).solve_once("undefined")
>>> solution.is_halt
True

flag

flag(
    first: str | NotableFlag | Iterable,
    value: Term | str | float | None = None,
) -> Flag

Creates a flag, i.e. a (name, value) pair.

Accepted forms: flag(name, value), flag(notable_flag) (set to its default value), flag(notable_flag, value), flag((name, value)) (any 2-item iterable), and flag(flag).

Parameters:

Name	Type	Description	Default
first	str | NotableFlag | Iterable	The name of the flag, a notable flag, a (name, value) pair, or a flag.	required
value	Term | str | float | None	The value of the flag, a term or a Python value converted by tuprolog.core.to_term; omitted for pairs, flags, and notable flags set to their default value.	None

Returns:

Type	Description
Flag	The flag.

Raises:

Type	Description
ValueError	If value is missing for a name, or first is of none of the forms above.

Examples:

>>> from tuprolog.solve.flags import Unknown
>>> flag("unknown", "fail")
(unknown, fail)
>>> flag(Unknown)
(unknown, warning)
>>> flag(("my_flag", 1)).second
1

flag_store

flag_store(
    *flags: NotableFlag
    | Flag
    | Iterable
    | FlagStore
    | Mapping[str, Term],
    **kwargs: Term,
) -> FlagStore

Creates a flag store from flags, in argument order (later ones override earlier ones).

Parameters:

Name	Type	Description	Default
*flags	NotableFlag | Flag | Iterable | FlagStore | Mapping[str, Term]	Notable flags (set to their default values), flags, (name, value) pairs, flag stores, dicts from names to values, or iterables of any of them.	()
**kwargs	Term	More flags, by name, merged last.	{}

Values are terms, or Python values converted by tuprolog.core.to_term.

Returns:

Type	Description
FlagStore	The flag store.

Raises:

Type	Description
ValueError	If an argument is none of the above (e.g. a string or a term).

Examples:

>>> from tuprolog.solve.flags import Unknown
>>> flag_store(Unknown, ("my_flag", 1), {"unknown": "fail"}, other="x")
FlagStore(flags={unknown=fail, my_flag=1, other=x})