instantiation

tuprolog.solve.exception.error.instantiation

Instantiation errors: an argument is an unbound variable, where a value is needed.

ISO Prolog's instantiation_error error, thrown as error(instantiation_error, Extra), means that a predicate received an unbound variable where it needs a (more) instantiated term: e.g. X is Y + 1 cannot compute Y + 1, and atom_length(X, L) cannot measure X.

The error is an InstantiationError. Build errors with instantiation_error_for_argument (for primitives' arguments) or instantiation_error_for_goal.

Examples:

>>> from tuprolog.solve.prolog import prolog_solver
>>> prolog_solver().solve_once("catch(X is Y + 1, error(E, _), true)")["E"]
instantiation_error

See Also

tuprolog.solve.primitive, whose ensuring_* checks raise these errors; 2P-Kt's documentation on errors and exceptions.

InstantiationError module-attribute

InstantiationError = _errors.InstantiationError

The instantiation error, thrown as error(instantiation_error, _): a term is unbound.

The JVM class (also a Python ValueError and a tuprolog.errors.PrologInstantiationError). Members (snake_case aliases as well): culprit, the unbound variable; besides those of tuprolog.solve.exception.LogicError (e.g. type, error_struct, message).

instantiation_error_for_argument

instantiation_error_for_argument(
    context: ExecutionContext,
    procedure: Signature,
    variable: Var,
    index: int | None = None,
) -> InstantiationError

Creates the instantiation error for an unbound argument of a predicate.

Parameters:

Name	Type	Description	Default
context	ExecutionContext	the execution context in which the error occurs (e.g. a request's context).	required
procedure	Signature	the signature of the predicate raising the error (e.g. a request's signature).	required
variable	Var	the unbound variable.	required
index	int | None	the (0-based) position of the offending argument, if known (it only changes the message).	None

Returns:

Type	Description
InstantiationError	The error, thrown as error(instantiation_error, Message).

Examples:

>>> from tuprolog.solve import signature
>>> from tuprolog.solve.exception.error import *
>>> from tuprolog.solve.prolog import prolog_solver
>>> context = prolog_solver().current_context
>>> from tuprolog.core import var
>>> error = instantiation_error_for_argument(context, signature("foo", 2), var("X"), 0)
>>> error.type
instantiation_error
>>> error.message
'The 0-th argument `X` of foo/2 is unexpectedly not instantiated'

instantiation_error_for_goal

instantiation_error_for_goal(
    context: ExecutionContext,
    procedure: Signature,
    variable: Var,
) -> InstantiationError

Creates the instantiation error for an unbound sub-goal of a predicate (e.g. call(X)).

Parameters:

Name	Type	Description	Default
context	ExecutionContext	the execution context in which the error occurs (e.g. a request's context).	required
procedure	Signature	the signature of the predicate raising the error (e.g. a request's signature).	required
variable	Var	the unbound sub-goal.	required

Returns:

Type	Description
InstantiationError	The error, thrown as error(instantiation_error, Message).