object

# `validation(Validation)`

Validation term predicates. Requires passing a validation term (constructed using the `validation` object predicates) as a parameter.

Availability:
`logtalk_load(validations(loader))`
Author: Paulo Moura
Version: 0:2:0
Date: 2026-02-21
Compilation flags:
`static, context_switching_calls`
Uses:
list
Remarks:
(none)
Inherited public predicates:
(none)

## Public predicates

### `is_valid/0`

True if the validation term holds a valid value.

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

### `is_invalid/0`

True if the validation term holds one or more errors.

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

### `if_valid/1`

Applies a closure when the validation term holds a valid value using the value as argument. Succeeds otherwise.

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

### `if_invalid/1`

Applies a closure when the validation term holds errors using the errors list as argument. Succeeds otherwise.

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

### `if_valid_or_else/2`

Applies either `ValidClosure` or `InvalidClosure` depending on the validation term holding a value or errors.

Compilation flags:
`static`
Template:
`if_valid_or_else(ValidClosure,InvalidClosure)`
Meta-predicate template:
`if_valid_or_else(1,1)`
Mode and number of proofs:
`if_valid_or_else(+callable,+callable)` - `zero_or_more`

### `valid/1`

Returns the value hold by the validation term. Throws an error otherwise.

Compilation flags:
`static`
Template:
`valid(Value)`
Mode and number of proofs:
`valid(--term)` - `one_or_error`
Exceptions:
Validation term holds errors:
`existence_error(valid_value,Validation)`

### `invalid/1`

Returns the errors hold by the validation term. Throws an error otherwise.

Compilation flags:
`static`
Template:
`invalid(Errors)`
Mode and number of proofs:
`invalid(--list)` - `one_or_error`
Exceptions:
Validation term holds a valid value:
`existence_error(validation_errors,Validation)`

### `filter/3`

When the validation term holds a value and the value satisfies the closure, returns the same validation term. When the validation term holds a value that does not satisfy the closure, returns an invalid term with the given error. When the validation term holds errors, returns the same validation term.

Compilation flags:
`static`
Template:
`filter(Closure,Error,NewValidation)`
Meta-predicate template:
`filter(1,*,*)`
Mode and number of proofs:
`filter(+callable,@term,--nonvar)` - `one`

### `map/2`

When the validation term holds a valid value and mapping a closure with the value and the new value as additional arguments succeeds, returns a new valid term. Otherwise returns the same validation term.

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

### `flat_map/2`

When the validation term holds a valid value, applies a closure with the value and the new validation term as additional arguments. Returns the new validation term on success. When the validation term holds errors, short-circuits by returning the same validation term without calling the closure. This is the monadic escape hatch for dependent steps; use `zip/3`, `sequence/2`, or `traverse/3` for error accumulation on independent steps.

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

### `map_or_else/3`

When the validation term holds a value and mapping a closure with the value and the new value as additional arguments is successful, returns the new value. Otherwise returns the given default value.

Compilation flags:
`static`
Template:
`map_or_else(Closure,Default,Value)`
Meta-predicate template:
`map_or_else(2,*,*)`
Mode and number of proofs:
`map_or_else(+callable,@term,--term)` - `one`

### `map_catching/2`

When the validation term holds a value, applies a closure to it. Returns a valid term with the new value if the closure succeeds. Returns an invalid term with the error if the closure throws an error. Returns an invalid term with the atom `fail` as error if the closure fails. When the validation term holds errors, returns the same validation term.

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

### `map_invalid/2`

When the validation term holds errors and mapping a closure with the errors list and the new errors list as additional arguments succeeds, returns a new invalid term. Otherwise returns the same validation term.

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

### `map_both/3`

When the validation term holds a value and mapping `ValidClosure` with the value is successful, returns a valid term with the new value. When the validation term holds errors and mapping `InvalidClosure` with the errors list is successful, returns an invalid term with the new errors. Otherwise returns the same validation term.

Compilation flags:
`static`
Template:
`map_both(ValidClosure,InvalidClosure,NewValidation)`
Meta-predicate template:
`map_both(2,2,*)`
Mode and number of proofs:
`map_both(+callable,+callable,--nonvar)` - `one`

### `swap/1`

Swaps the valid and invalid terms. If the validation term holds a value, returns an invalid term with a singleton list containing that value. If the validation term holds errors, returns a valid term with the errors list.

Compilation flags:
`static`
Template:
`swap(NewValidation)`
Mode and number of proofs:
`swap(--nonvar)` - `one`

### `or/2`

Returns the same validation term if it holds a value. Otherwise calls closure to generate a new validation term. Fails if the validation term holds errors and calling the closure fails or throws an error.

Compilation flags:
`static`
Template:
`or(NewValidation,Closure)`
Meta-predicate template:
`or(*,1)`
Mode and number of proofs:
`or(--term,@callable)` - `zero_or_one`

### `or_else/2`

Returns the valid value if present or the default value otherwise.

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

### `or_else_get/2`

Returns the value hold by the validation term if valid. Otherwise applies a closure to compute the value. Throws an error when the validation term holds errors and a value cannot be computed.

Compilation flags:
`static`
Template:
`or_else_get(Value,Closure)`
Meta-predicate template:
`or_else_get(*,1)`
Mode and number of proofs:
`or_else_get(--term,+callable)` - `one_or_error`
Exceptions:
Validation term holds errors and a value cannot be computed:
`existence_error(valid_value,Validation)`

### `or_else_call/2`

Returns the value hold by the validation term if valid. Calls a goal deterministically otherwise.

Compilation flags:
`static`
Template:
`or_else_call(Value,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 valid value if present. Fails otherwise.

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

### `or_else_throw/1`

Returns the value hold by the validation term if valid. Throws the errors list hold by the validation term as an exception otherwise.

Compilation flags:
`static`
Template:
`or_else_throw(Value)`
Mode and number of proofs:
`or_else_throw(--term)` - `one_or_error`

### `or_else_throw/2`

Returns the value hold by the validation term if valid. Throws the given error otherwise, ignoring any errors hold by the validation term.

Compilation flags:
`static`
Template:
`or_else_throw(Value,Error)`
Mode and number of proofs:
`or_else_throw(--term,@nonvar)` - `one_or_error`

### `zip/3`

When both this validation and the other validation hold values and applying a closure with both values and the new value as additional arguments is successful, returns a valid term with the new value. When both hold errors, returns an invalid term with all errors accumulated. Otherwise returns the first invalid term.

Compilation flags:
`static`
Template:
`zip(Closure,OtherValidation,NewValidation)`
Meta-predicate template:
`zip(3,*,*)`
Mode and number of proofs:
`zip(+callable,+nonvar,--nonvar)` - `one`

### `flatten/1`

Flattens a nested validation term. When the validation term holds a value that is itself a validation term, returns the inner validation term. When the validation term holds a non-validation value, returns the same validation term. When the validation term holds errors, returns the same validation term.

Compilation flags:
`static`
Template:
`flatten(NewValidation)`
Mode and number of proofs:
`flatten(--nonvar)` - `one`

### `to_optional/1`

Converts the validation term to an optional term. Returns a non-empty optional term holding the value if the validation term holds a value. Returns an empty optional term if the validation term holds errors.

Compilation flags:
`static`
Template:
`to_optional(Optional)`
Mode and number of proofs:
`to_optional(--nonvar)` - `one`

### `to_expected/1`

Converts the validation term to an expected term. Returns an expected term holding the value if the validation term holds a value. Returns an expected term with the errors list as the unexpected error otherwise.

Compilation flags:
`static`
Template:
`to_expected(Expected)`
Mode and number of proofs:
`to_expected(--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

validation, validated