View Source Bond.Predicates (Bond v0.17.4)
Predicate functions and operators that are useful in assertions and contract specifications.
This module is automatically imported for all assertion expressions, specifically in
preconditions defined with @pre, postconditions defined with @post, and in uses of
Bond.check/1.
To use the infix operator versions of the predicates in other contexts, this module must be imported in the using module.
Operator precedence
~> (implication) and <~ (pattern match) share the same precedence and
left-associate. This matters when both appear in a single assertion. The
natural-language reading "if x > 0 then the result matches {:ok, _}"
# WRONG — fails to compile
@post (x > 0) ~> {:ok, _} <~ resultparses as ((x > 0) ~> {:ok, _}) <~ result, where the LHS of <~ is an
arbitrary expression containing _. _ isn't a valid value position, so
compilation fails with a cryptic error.
Add explicit parens around the inner operator to get the intended grouping:
# Right
@post (x > 0) ~> ({:ok, _} <~ result)Rule of thumb: any time you nest <~ inside ~> (or vice versa),
parenthesize the inner expression.
Summary
Functions
Pattern matching operator: equivalent to match?(pattern, expression).
Logical implication: does p imply q?
Logical exclusive or: is either p or q true, but not both?
Logical exclusive or operator: p ||| q means xor(p, q).
Logical implication operator: p ~> q is equivalent to not p or q, with
short-circuit evaluation — q is only evaluated when p is truthy.
Functions
Pattern matching operator: equivalent to match?(pattern, expression).
Examples
iex> {:ok, %Date{}} <~ Date.new(1974, 6, 6)
true
iex> {:error, _} <~ Date.new(-1, -1, -1)
true@spec implies?(as_boolean(term()), as_boolean(term())) :: boolean()
Logical implication: does p imply q?
For an infix operator version of logical implication see ~>/2.
Examples
iex> implies?(true, true)
true
iex> implies?(true, false)
false
iex> implies?(false, true)
true
iex> implies?(false, false)
true@spec xor(as_boolean(term()), as_boolean(term())) :: boolean()
Logical exclusive or: is either p or q true, but not both?
For an infix operator version of exclusive or see |||/2.
Examples
iex> xor(true, true)
false
iex> xor(true, false)
true
iex> xor(false, true)
true
iex> xor(false, false)
falseLogical exclusive or operator: p ||| q means xor(p, q).
Note that the ||| operator has higher precedence than many other operators and it may be
necessary to parenthesize the expressions on either side of the operator to get the
expected result.
Examples
iex> true ||| true
false
iex> true ||| false
true
iex> false ||| true
true
iex> false ||| false
false
iex> x = 2
2
iex> y = 4
4
iex> (x - y < 0) ||| (y <= x)
trueLogical implication operator: p ~> q is equivalent to not p or q, with
short-circuit evaluation — q is only evaluated when p is truthy.
This makes ~> safe for shape-dependent assertions where the consequent
would otherwise raise on certain inputs to the antecedent. For example:
@pre is_binary(x) ~> String.length(x) > 0reads "if x is a binary, then its length is positive." With the
short-circuit, String.length(x) is never called when x isn't a binary
(which would raise FunctionClauseError). This pattern is the canonical
way to express clause-specific assertions on multi-clause functions where
contracts must apply uniformly to every clause.
Note that the ~> operator has higher precedence than many other operators
and it may be necessary to parenthesize the expressions on either side of
the operator to get the expected result. See the
"Operator precedence" section above.
Examples
iex> true ~> true
true
iex> true ~> false
false
iex> false ~> true
true
iex> false ~> false
true
iex> x = 2
2
iex> y = 4
4
iex> (x - y < 0) ~> (y > x)
true
iex> false ~> raise("not evaluated — antecedent is false")
true