object

# `expected(Reference)`

Expected term reference predicates. Requires passing an expected reference constructed using the “expected” object as a parameter.

Author: Paulo Moura
Version: 1.1
Date: 2018/7/11
Compilation flags:
`static, context_switching_calls`

(no dependencies on other entities)

## Public interface

### `is_unexpected/0`

True if the expected reference holds an unexpected term. Avoid whenever possible by using instead the if_unexpected/1 predicate.

Compilation flags:
`static`
Mode and number of proofs:
`is_unexpected` - `zero_or_one`

### `is_expected/0`

True if the expected reference holds an expected term. Avoid whenever possible by using instead the if_expected/1 predicate.

Compilation flags:
`static`
Mode and number of proofs:
`is_expected` - `zero_or_one`

### `if_unexpected/1`

Applies a closure, with the expected reference term as additional argument, if it holds an unexpected term. Succeeds otherwise.

Compilation flags:
`static`
Template:
`if_unexpected(Closure)`
Meta-predicate template:
`if_unexpected(1)`
Mode and number of proofs:
`if_unexpected(+callable)` - `zero_or_more`

### `if_expected/1`

Applies a closure, with the expected reference term as additional argument, if it does not hold an unexpected term. Succeeds otherwise.

Compilation flags:
`static`
Template:
`if_expected(Closure)`
Meta-predicate template:
`if_expected(1)`
Mode and number of proofs:
`if_expected(+callable)` - `zero_or_more`

### `unexpected/1`

Returns the unexpected reference term if not an expected term. Throws an error otherwise.

Compilation flags:
`static`
Template:
`unexpected(Unexpected)`
Mode and number of proofs:
`unexpected(--term)` - `one`
Exceptions:
Expected reference holds an expected term:
`existence_error(unexpected_term,Reference)`

### `expected/1`

Returns the expected reference term if not an unexpected term. Throws an error otherwise.

Compilation flags:
`static`
Template:
`expected(Expected)`
Mode and number of proofs:
`expected(--term)` - `one`
Exceptions:
Expected reference holds an unexpected term:
`existence_error(expected_term,Reference)`

### `map/2`

When the expected reference does not hold an unexpected term and mapping a closure with the expected reference term and the new term as additional arguments is successful, returns an expected reference with the new value. Otherwise returns the expected reference.

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

### `flat_map/2`

When the expected reference does not hold an unexpected term and mapping a closure with the expected reference value and the new expected reference as additional arguments is successful, returns the new expected reference. Otherwise returns the expected reference.

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

### `or_else/2`

Returns the expected reference term if it does not hold an unexpected term or the given default term if the expected reference holds an unexpected term.

Compilation flags:
`static`
Template:
`or_else(Term,Default)`
Mode and number of proofs:
`or_else(--term,@term)` - `one`

### `or_else_get/2`

Returns the expected reference term if it does not hold an unexpected term or applies a closure to compute the term if the expected holds an unexpected term. Throws an error when the expected reference holds an unexpected term and a term cannot be computed using the given closure.

Compilation flags:
`static`
Template:
`or_else_get(Term,Closure)`
Meta-predicate template:
`or_else_get(*,1)`
Mode and number of proofs:
`or_else_get(--term,+callable)` - `one`
Exceptions:
Expected reference holds an unexpected term and a term cannot be computed:
`existence_error(expected_term,Reference)`

### `or_else_call/2`

Returns the expected reference term if it does not hold an unexpected term or calls a goal deterministically if the expected reference holds an unexpected term. Can be used e.g. to throw the exception hold by the expected reference.

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

### `or_else_fail/1`

Returns the expected reference term if it does not hold an unexpected term. Fails otherwise. Usually called to skip over empty expected reference holding unexpected terms.

Compilation flags:
`static`
Template:
`or_else_fail(Expected)`
Mode and number of proofs:
`or_else_fail(--term)` - `zero_or_one`

## Protected interface

(none)

## Private predicates

(none)

## Operators

(none)

## Remarks

(none)

See also

expected