Data::Sah::Type::BaseType - Specification for base type
version 0.02
This is the specification for the 'BaseType' role. All Sah types directly or indirectly consume this role.
Unless mentioned explicitly, priority is 50 (default).
Supply a default value.
Priority: 1 (very high). This is processed before all other clauses.
Example: Given schema [int => {req=>1}] an undef data is invalid, but given schema [int => {req=>1, default=>3}] an undef data is valid because it will be given default value first.
This is a "hidden" clause that cannot be specified in schemas (due to uppercase spelling), but compilers use them to add checks.
Priority: 50 (default), but due to its spelling, by sorting, it will be processed before all other normal clauses.
This is a "hidden" clause that cannot be specified in schemas (due to uppercase spelling), but compilers use them to preprocess data before further checking (for example, Perl compiler for the datetime type can convert string data to DateTime object).
datetime
Priority: 5 (very high), executed after default and req/forbidden.
If set to 1, require that data be defined. Otherwise, allow data to be undef (the default behaviour).
Priority: 3 (very high), executed after default.
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
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
NOT YET IMPLEMENTED.
Run expression(s), usually to preprocess data before further checking. Data is referred to in expression by variable $_. Prefiltered value will persist until the end of all other clauses, and after that will be restored by the POSTPROCESS clause.
$_
Priority: 10 (high). Run after default and req/forbidden (and PREPROCESS).
Specific attributes: permanent. If set to true, then prefiltered value will persist and won't be restored by POSTPROCESS.
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.
Priority: 90 (very low). Run after all other clauses, before POSTPROCESS.
This is a "hidden" clause that cannot be specified in schemas (due to uppercase spelling), compilers use them to restore value temporarily changed by prefilters (unless the prefilter is set to be permanent, or between schemas in deps, see the deps clause).
Priority: 95 (very low). Run after all the other clauses.
Set language for this schema.
Priority: 2 (very high)
A short short (usually single-word, without any formatting) to name the schema, useful for identifying the schema when used as a type for human compiler.
To store translations, you can use the alt.lang.* clause attributes.
Example:
[int => { 'name:alt.lang.en_US' => 'pos_int', 'name:alt.lang.id_ID' => 'bil_pos', min=>0, }]
See also: summary, description, comment, tags.
A one-line text (about 70-80 character max, 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.
# definition for 'single_dice_throw' schema/type [int => { req => 1, 'summary:alt.lang.en_US' => 'A number representing result of single dice throw (1-6)', 'summary:alt.lang.id_ID' => 'Bilangan yang menyatakan hasil lempar sebuah dadu (1-6)', between => [1, 6], }]
Using the human compiler, the above schema will be output as the standard, more boring 'Integer, value between 1 and 6.'
See also: name, description, comment, tags.
A longer text (a paragraph or more) to describe the schema, useful e.g. for help/usage text. Text should be in Org format.
[array => { name => 'http_headers', description => <<EOT, HTTP headers should be specified as an array of 2-element arrays (pairs). Each pair should contain header name in the first element (all lowercase, *-* written as *_*) and header value in the second element. Example: : [[content_type => 'text/html'], [accept => 'text/html'], [accept => '*/*']] EOT req => 1, of => 'http_header', }, { def => { http_header => ['array*', len=>2], }, }]
See also: name, summary, comment, tags.
Can contain any kind of text (format unspecified), will be ignored during validation. Meant to store internal comment (for schema authors/developers).
See also: name, summary, description, tags.
A list of tags, can be used to categorize schemas.
See also: name, summary, description, comment.
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).
If set to 1, validation of this clause always fails. This is just a convenience to force failure.
This is similar to deps, but instead of using schemas as arguments, clauses are used. The first form (4-argument) states that if CLAUSE1 succeeds, then CLAUSE2 must also succeed. The second form (2-argument) operates on a clause set (hash) or clause sets (array of hashes).
# leap year [int => {div_by=>4, if => [div_by => 100, div_by => 400]]
The "if" clause states that if input number is divisible by 100, it must also divisible by 400. Otherwise, the clause fails.
[str => {min_len=>1, max_len=>10, if => [ {min_len=>4, max_len=>6}, {is_palindrome=>1} ]}]
The above says that if a string has length between 4 and 6 then it must be a palindrome. Otherwise it doesn't have to be one. But nevertheless, all input must be between 1 and 10 characters long.
Evaluate expression, which must evaluate to a true value for this clause to succeed.
This clause specifies the required minimum number of check clauses that must succeed in order for the whole clause set to be considered a success. By default this is not defined. You can use this clause to only require certain number of (instead of all) checks.
Note that the {min,max}_{ok,nok} themselves are not counted into number of successes/failures, as they are not considered as constraint clauses.
Priority: 2 (very high, evaluated after default clause).
[str => {min_ok=>1, min_len=>8, match=>qr/\W/}]
The above schema requires a string to be at least 8 characters long, or contains a non-word character. Strings that would validate include: abcdefgh or $ or $abcdefg. Strings that would not validate include: abcd (fails both min_len and match clauses).
abcdefgh
$
$abcdefg
abcd
min_len
match
See also: max_ok, min_nok, max_nok.
This clause specifies the maximum number of check clauses that succeed in order for the whole clause set to be considered a success. By default this is not defined. You can use this clause to require a number of failures in the checks.
[str => {min_ok=>1, max_ok=>1, min_len=>8, match=>qr/\W/}]
The above schema states that string must either be longer than 8 characters or contains a non-word character, but not both. Strings that would validate include: abcdefgh or $. Strings that would not validate include: $abcdefg (match both clauses, so max_ok is not satisfied).
This clause specifies the required minimum number of check clauses that must fail in order for the whole clause set to be considered a success. By default this is not defined. You can use this clause to require a certain number of failures.
[str => {min_nok=>1, min_len=>8, match=>qr/\W/}]
The above schema requires a string to be shorter than 8 characters or devoid of non-word characters. Strings that would validate include: abcdefghi (fails the match clause), $abcd (fails min_len clause), or a (fails both clauses). Strings that would not validate include: $abcdefg.
abcdefghi
$abcd
a
This clause specifies the maximum number of check failures that succeed in order for the whole clause set to be considered a success. By default this is not defined (but when none of the {min,max}_{ok,nok} is defined, the default behavior is to require all clauses to succeed, in other words, as if max_nok were 0). You can use this clause to allow a certain number of failures in the checks.
max_nok
[str => {max_nok=>1, min_len=>8, match=>qr/\W/}]
The above schema states that string must either be longer than 8 characters or contains two non-word characters, or both. Strings that would validate include: abcdefgh, $$, $abcdefgh. Strings that would not validate include: abcd (fails both min_len and match clauses).
$$
$abcdefgh
Steven Haryanto <stevenharyanto@gmail.com>
This software is copyright (c) 2012 by Steven Haryanto.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Data::Sah, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::Sah
CPAN shell
perl -MCPAN -e shell install Data::Sah
For more information on module installation, please visit the detailed CPAN module installation guide.