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.0`
date:
  `2018/5/28`

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 – 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 – 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 – 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 – 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 – 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 – 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 – 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 – 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 – 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 – 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 – 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 – number of proofs:
  `or_else_fail(--term) – zero_or_one`

## Protected interface

(none)

## Private predicates

(none)

## Operators

### (none)

## Remarks

### (none)

## See also

- expected