NAME

VERSION

DESCRIPTION

TYPE: undef

This type does not have any clauses. The only value it knows is the undefined value (like undef in Perl, or null in PHP).

ROLE: BaseType

This is the base type role, all Sah types (except undef) must implement this role.

Clauses

The list below is ordered by priority, from highest to lowest.

defhash_v : FLOAT

Priority: 0 (checked first before everything else).

Category: metadata.

From DefHash. Normally there is no need to set this.

v : FLOAT (default: 1)

Priority: 0 (checked first before everything else).

Category: metadata.

From DefHash. Specify Sah version. Should be 1 at the moment.

schema_v : FLOAT (default: 1)

Priority: 0 (checked first before everything else).

Category: metadata.

Specify schema version. By default assumed to be 1 if not set.

base_v : FLOAT (default: 1)

Priority: 0 (checked first before everything else).

Category: metadata.

Specify base schema version. By default assumed to be 1 if not set. Using a base schema with a different value will fail. Can be used to force child schemas to update whenever we change our schema. For example:

then vocal will break. To force consonant to fail (so its author can update it):

// the new vocal
["str", {"schema_v": 2, "match": "\\A[aeiou]\\z"}]

Since vocal's schema_v is now 2, it is not the same as 1 (which is implied by consonant, having the default value of base_v). consonant's author might then update its own implementation to match vocal:

summary : STR

Priority: 2 (very high), after default.

Category: metadata.

From DefHash. A one-line text (about 72 characters maximum, without any formatting) to describe the schema. This is useful, e.g. for manually describe a schema instead of using the human compiler. It can also be used in form field labels.

req : BOOL

If set to 1, require that data be defined. Otherwise, allow data to be undef (the default behaviour).

By default, undef will pass even elaborate schema, e.g. ["int", {"min": 0, "max": 10, "div_by": 3}] will still pass an undef. However, undef will not pass ["int": {"req": 1}].

This behaviour is much like NULLs in SQL: we *can't* (in)validate something that is unknown/unset.

See also: forbidden

forbidden : BOOL

Priority: 3 (very high), executed after default.

Category: constraint.

This is the opposite of req, requiring that data be not defined (i.e. undef).

Given schema ["int", {"forbidden": 1}], a non-undef value will fail. Another example: the schema ["int", {"req": 1, "forbidden": 1}] will always fail due to conflicting clauses.

See also: req

prefilters : [EXPR, ...]

Priority: 10 (high). Run after default and req/forbidden.

Category: filter.

Run expression(s), usually to preprocess data before further checking. Data is referred to in expression by variable $_. Prefiltered value should persist until the end of all other clauses (until the end of clause set), after which the old value can be restored.

Specific attributes: perm. If set to true, then prefiltered value will persist.

ok : ANY -> true

Priority: 50 (normal)

Return value: true (always succeeds).

Category: constraint.

Will do nothing. This clause is just a convenience if you want to do nothing (or perhaps just use the attributes of this clause to do things). It is the default in the else section of the if_clause clause.

To force failure, you can use "!ok": 1.

cset : HASH -> INT

Evaluate a clause set. Note that return value adds 1 to the number of successful clauses to avoid returning 0 (evaluates to false). And it will only be returned if clause is successful. Otherwise false (0) will be returned.

check : EXPR -> ANY

Priority: 50 (normal)

Return value: result of evaluated expression

Category: constraint.

Evaluate expression, which must evaluate to a true value for this clause to succeed. Examples:

// require that string is a palindrome, using a Sah function
["str", "check", "is_palindrome($_)"]
// require that the *length of* string is a prime number
["str", "check", "is_prime(len($_))"]

if : HASH -> ANY

Priority: 50 (normal)

Return value: if condition is true, then the then_* result, otherwise the else_* result.

Category: constraint.

A generic condition clause.

To use this clause, first specify one of the condition keys in the argument: expr (evaluate expression, value should the expression), clause (evaluate data against clause, value should be an array [CLAUSE_NAME, CLAUSE_ARG]), schema (validate data against schema, value should be the schema), prop (evaluate property against a schema, value is [PROP, SCHEMA] where PROP is the property name, or if property has arguments, [PROP_NAME, PROP_ARGS]).

Then specify one of the then keys and one of the else keys: {then,else}{_prop,_expr,schema,clause}. The default then key is "then": 1. The default else is "else": 1, unless "then": some-true-value is specified, in which case the default else is "else": 0. Examples:

// forbid the string to be lowercase
"if": {"clause": ["match", "^[a-z]$"], "then": 0}
// if string is lowercase, it must be a palindrome
"if": {"clause": ["match", "^[a-z]$"], "then_expr": "is_palindrome($_)"}
// if string is lowercase, it must be a palindrome, otherwise it must be longer
// than 3 characters.
"if": {"clause": ["match", "^[a-z]$"],
"then_expr": "is_palindrome($_)",
"else_expr": "len($_) > 3"}
// require the length of the string to be an even number
"if": {"prop": ["len", ["int", "div_by", 2]], "then": 1}
// if string is a palindrome, then require it to have length > 5
"if": {"expr": "is_palindrome($_)", "then_prop": ["len", ["int", "xmin": 5]]}
"if": {"expr": "is_palindrome($_)", "then_expr": "len($_) > 5"}

postfilters : [EXPR, ...]

Priority: 90 (very low). Run after all other clauses.

Category: filter.

Run expression(s), usually to postprocess data. Data is referred to in expression by variable $_. From here on, the data will be permanently set to the postfiltered value.

ROLE: Comparable

This is the comparable type role. All types which have comparable values must implement this role. Most types implement this role, including str, all number types, etc.

elems => ARRAY_OF_SCHEMA

The above schema validates result envelope, which is an array (see Rinci::function). The first element (the status) must be a 3-digit integer. The second element (the error message) is a string. The third element (the actual result) can be anything. The fourth element (result metadata) is a hash containing extra data. Examples of valid data including:

The above schema specifies a hash with definition for the value of its a, b, and c keys. But other keys like d are allowed since the keys clause is set to not restrict keys.

re_keys : HASH

Attributes: restrict (bool, default: 1)

Just like keys, but specifies schemas for keys which match regexes. Example:

["hash", "re_keys", {"^[A-Za-z]": "str", "^[0-9]": "int"}]

The above schema specifies that for keys which begin with a letter the values must be strings, and for keys which begin with a digit the values must be integers. These hashes validate: {}, {"a": "x", "b": 1, "1": 1}. These hashes do not validate: {"1": "x"}, {"#": "x"} (key does not match any keys in re_keys).

req_keys : ARRAY

Specify which keys are required to be present. Note that the values for those keys are not required to be defined (use keys for that). Example:

["hash", "req_keys", ["a", "b"]]

The above schema specifies that hash needs to have some keys, but the value can be null. This hash will validate: {"a": 1, "b": null}. However, given this schema:

["hash", "req_keys", ["a", "b"], "keys", {"a": "int", "b": "int*"}]

the previous hash will not validate since the value for b is required.

allowed_keys : ARRAY

Specify which keys are allowed.

allowed_keys_re : RE

Like allowed_keys but using regular expression.

each_key : SCHEMA

Alias to each_index.

each_value : SCHEMA

Alias to each_elem.

check_each_key : EXPR

Alias to check_each_index.

check_each_value : EXPR

Alias to check_each_elem.

TYPE: any

A type to specify alternate schemas.

Clauses

of : [SCHEMA, ...]

Specify the schema(s) where the value will need to be valid to at least one of them.

TYPE: all

A type to specify co-schemas (all schemas that must be validated to value).

Clauses

of : [SCHEMA, ...]

Specify the schema(s) where the value will need to be valid to all of them.