protocol

# `options_protocol`

Options protocol.

Availability:
`logtalk_load(options(loader))`
Author: Paulo Moura
Version: 1:2:0
Date: 2022-01-03
Compilation flags:
`static`
Dependencies:
(none)
Remarks:
(none)
Inherited public predicates:
(none)

## Public predicates

### `check_option/1`

Succeeds if the option is valid. Throws an error otherwise.

Compilation flags:
`static`
Template:
`check_option(Option)`
Mode and number of proofs:
`check_option(@term)` - `one_or_error`
Exceptions:
`Option` is a variable:
`instantiation_error`
`Option` is neither a variable nor a compound term:
`type_error(compound,Option)`
`Option` is a compound term but not a valid option:
`domain_error(option,Option)`

### `check_options/1`

Succeeds if all the options in a list are valid. Throws an error otherwise.

Compilation flags:
`static`
Template:
`check_options(Options)`
Mode and number of proofs:
`check_options(@term)` - `one_or_error`
Exceptions:
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(option,Option)`

### `valid_option/1`

Succeeds if the option is valid.

Compilation flags:
`static`
Template:
`valid_option(Option)`
Mode and number of proofs:
`valid_option(@term)` - `zero_or_one`

### `valid_options/1`

Succeeds if all the options in a list are valid.

Compilation flags:
`static`
Template:
`valid_options(Options)`
Mode and number of proofs:
`valid_options(@term)` - `one`

### `default_option/1`

Enumerates, by backtracking, the default options.

Compilation flags:
`static`
Template:
`default_option(Option)`
Mode and number of proofs:
`default_option(?compound)` - `zero_or_more`

### `default_options/1`

Returns a list of the default options.

Compilation flags:
`static`
Template:
`default_options(Options)`
Mode and number of proofs:
`default_options(-list(compound))` - `one`

### `option/2`

True iff `Option` unifies with the first occurrence of the same option in the `Options` list.

Compilation flags:
`static`
Template:
`option(Option,Options)`
Mode and number of proofs:
`option(+compound,+list(compound))` - `zero_or_one`

### `option/3`

True iff `Option` unifies with the first occurrence of the same option in the `Options` list or, when that is not the case, if `Option` unifies with `Default`.

Compilation flags:
`static`
Template:
`option(Option,Options,Default)`
Mode and number of proofs:
`option(+compound,+list(compound),+compound)` - `zero_or_one`

## Protected predicates

### `merge_options/2`

Merges the user options with the default options, returning the final list of options. Calls the `fix_options/2` predicate to preprocess the options after merging. Callers must ensure, if required, that the user options are valid.

Compilation flags:
`static`
Template:
`merge_options(UserOptions,Options)`
Mode and number of proofs:
`merge_options(+list(compound),-list(compound))` - `one`

### `fix_options/2`

Fixes a list of options, returning the list of options.

Compilation flags:
`static`
Template:
`fix_options(Options,FixedOptions)`
Mode and number of proofs:
`fix_options(+list(compound),-list(compound))` - `one`

### `fix_option/2`

Fixes an option.

Compilation flags:
`static`
Template:
`fix_option(Option,FixedOption)`
Mode and number of proofs:
`fix_option(+compound,-compound)` - `zero_or_one`

## Private predicates

(none)

## Operators

(none)

See also

options