object

# `expected`

Constructors for expected terms. An expected term contains either a value or an error. Expected terms should be regarded as opaque terms and always used with the `expected/1` object by passing the expected term as a parameter.

Availability:
`logtalk_load(expecteds(loader))`
Author: Paulo Moura
Version: 2:2:0
Date: 2026-02-21
Compilation flags:
`static, context_switching_calls`
Provides:
type::type/1
type::check/2
Remarks:

> - Type-checking support: This object also defines a type `expected` for use with the `type` library object.

Inherited public predicates:
(none)

## Public predicates

### `of_unexpected/2`

Constructs an expected term from an error that represent that the expected value is missing.

Compilation flags:
`static`
Template:
`of_unexpected(Error,Expected)`
Mode and number of proofs:
`of_unexpected(@term,--nonvar)` - `one`

### `of_expected/2`

Constructs an expected term from an expected value.

Compilation flags:
`static`
Template:
`of_expected(Value,Expected)`
Mode and number of proofs:
`of_expected(@term,--nonvar)` - `one`

### `from_goal/4`

Constructs an expected term holding a value bound by calling the given goal. Otherwise returns an expected term with the unexpected goal error or failure represented by the `Error` argument.

Compilation flags:
`static`
Template:
`from_goal(Goal,Value,Error,Expected)`
Meta-predicate template:
`from_goal(0,*,*,*)`
Mode and number of proofs:
`from_goal(+callable,--term,@term,--nonvar)` - `one`

### `from_goal/3`

Constructs an expected term holding a value bound by calling the given goal. Otherwise returns an expected term with the unexpected goal error or the atom `fail` representing the unexpected failure.

Compilation flags:
`static`
Template:
`from_goal(Goal,Value,Expected)`
Meta-predicate template:
`from_goal(0,*,*)`
Mode and number of proofs:
`from_goal(+callable,--term,--nonvar)` - `one`

### `from_goal/2`

Constructs an expected term holding a value bound by calling the given closure. Otherwise returns an expected term holding the unexpected closure error or the atom `fail` representing the unexpected failure.

Compilation flags:
`static`
Template:
`from_goal(Closure,Expected)`
Meta-predicate template:
`from_goal(1,*)`
Mode and number of proofs:
`from_goal(+callable,--nonvar)` - `one`

### `from_generator/4`

Constructs expected terms with the values generated by calling the given goal. On goal error or failure, returns an expected term with the unexpected goal error or failure represented by the `Error` argument.

Compilation flags:
`static`
Template:
`from_generator(Goal,Value,Error,Expected)`
Meta-predicate template:
`from_generator(0,*,*,*)`
Mode and number of proofs:
`from_generator(+callable,--term,@term,--nonvar)` - `one_or_more`

### `from_generator/3`

Constructs expected terms with the values generated by calling the given goal. On goal error or failure, returns an expected term with, respectively, the unexpected goal error or the atom `fail` representing the unexpected goal failure.

Compilation flags:
`static`
Template:
`from_generator(Goal,Value,Expected)`
Meta-predicate template:
`from_generator(0,*,*)`
Mode and number of proofs:
`from_generator(+callable,--term,--nonvar)` - `one_or_more`

### `from_generator/2`

Constructs expected terms with the values generated by calling the given closure. On closure error or failure, returns an expected term with, respectively, the unexpected closure error or the atom `fail` representing the unexpected closure failure.

Compilation flags:
`static`
Template:
`from_generator(Closure,Expected)`
Meta-predicate template:
`from_generator(1,*)`
Mode and number of proofs:
`from_generator(+callable,--nonvar)` - `one_or_more`

### `from_optional/3`

Converts an optional term to an expected term. Returns an expected term holding the value if the optional term is not empty. Returns an expected term with the given error otherwise.

Compilation flags:
`static`
Template:
`from_optional(Optional,Error,Expected)`
Mode and number of proofs:
`from_optional(+nonvar,@term,--nonvar)` - `one`

## Protected predicates

(no local declarations; see entity ancestors if any)

## Private predicates

(no local declarations; see entity ancestors if any)

## Operators

(none)

See also

expected(Expected), type