Home / Docs / Language guide / Errors

checked and the escape budget

Release v0.4.0Edition 0.1 and laterU2013U2014U2016U3009U4002U7003

What it does

checked(v, p) else fail V tests the predicate p (a condition on it that is true or false) at run time, with it bound to v:

This is how a value obtains an opaque fact, one the solver (the program that una check asks to prove each fact) cannot prove. checked replaces a proof made before the program runs with a test while it runs, so it is an escape hatch. Each module may use it only as many times as its package's escape budget (a count set in una.toml) allows, and every use is listed in the build report (what una report prints about a build).

Learn more: When no proof can decide: checked and opaque predicates.

una.tomltoml
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"

[escape_budget]
checked_per_module = 1
src/shop.unauna
module shop

pub kind Phone = Text where valid_phone(it)

pub kind PhoneError = | Malformed

pub predicate opaque valid_phone(t: Text) -> Bool = t.len == 11 and is_digits(t)

pub parse_phone(raw: Text) -> Phone
  fails PhoneError
=
  checked(raw, valid_phone(it)) else fail Malformed

Forms

In the grammar below, each rule gives a name, =, what the name stands for and ;, quoted words are written as shown, NEWLINE, INDENT and DEDENT stand for a line break and for one more or one less level of indentation, [ ] marks an optional part, { } a part that may repeat, | separates alternatives, ( ) groups them, and (* *) holds a comment.

ebnf
checked_expr    = "checked" "(" line_expr "," line_expr ")" "else" "fail" variant_expr ;

The budget is the key checked_per_module of the [escape_budget] table of una.toml, an integer of at least 0 that defaults to 0.

Examples

A predicate in the refinement language refines a plain value. Here Shelf's refinement holds for the result because the test established it:

una.tomltoml
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"

[escape_budget]
checked_per_module = 1
src/shop.unauna
module shop

pub kind Shelf = Int in 0..9

pub kind ShelfError = | NoSuchShelf

pub shelf(n: Int) -> Shelf
  fails ShelfError
=
  checked(n, it >= 0 and it <= 9) else fail NoSuchShelf

Without a budget, checked is rejected. The default is 0, and a file checked on its own has the default:

una
-- fails with U7003
module shop

pub kind Phone = Text where valid_phone(it)

pub kind PhoneError = | Malformed

pub predicate opaque valid_phone(t: Text) -> Bool = t.len == 11 and is_digits(t)

pub parse_phone(raw: Text) -> Phone
  fails PhoneError
=
  checked(raw, valid_phone(it)) else fail Malformed

Edge cases

The predicate must run. A call of a function that is not a predicate is outside the refinement language:

una.tomltoml
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"

[escape_budget]
checked_per_module = 1
src/shop.unauna
-- fails with U2014
module shop

pub kind SkuError = | NotDigits

pub digits_only(sku: Text) -> Text
  fails SkuError
=
  checked(sku, is_digits(it)) else fail NotDigits

Opaque predicates are called only in checked, and in the bodies of other opaque predicates. A call anywhere else would establish the fact without counting against the budget:

una
-- fails with U2016
module shop

pub predicate opaque valid_phone(t: Text) -> Bool = t.len == 11 and is_digits(t)

pub looks_valid(raw: Text) -> Bool = valid_phone(raw)

The variant belongs to the function's error kind:

una.tomltoml
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"

[escape_budget]
checked_per_module = 1
src/shop.unauna
-- fails with U3009
module shop

pub kind StockError = | Negative

pub kind PaymentError = | Declined

pub stock_level(units: Int) -> Int
  fails StockError
=
  checked(units, it >= 0) else fail Declined

No test that depends on labeled data (data marked with a label above public, such as internal or secret). A failure of checked reveals whether the predicate holds. So checked is U4002 on a labeled value, on a predicate that reads a labeled value, or under a raised Branches and failures: implicit flows (the label of the conditions that decided whether this line runs):

una.tomltoml
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"

[escape_budget]
checked_per_module = 1
src/shop.unauna
-- fails with U4002
module shop

pub kind CreditError = | Negative

pub balance(cents: secret Int) -> secret Int
  fails CreditError
=
  checked(cents, it >= 0) else fail Negative

The same holds when the operand is public but the predicate reads labeled data, here an internal bound:

una.tomltoml
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"

[escape_budget]
checked_per_module = 1
src/shop.unauna
-- fails with U4002
module shop

pub kind LimitError = | OverLimit

pub within_limit(cents: Int, limit: internal Int) -> Int
  fails LimitError
=
  checked(cents, it < limit) else fail OverLimit

Further rules:

Diagnostics

Edition

checked and the escape budget are the same in editions 0.1 and 0.2. Edition 0.2 keeps them and adds fixed-width integers, whose narrowing conversions may go through checked.

Normative source