Data::Schema::Type::Hash - Type handler for hash ('hash')
version 0.136
use Data::Schema;
This is the type handler for type 'hash'.
Example schema (in YAML syntax):
- hash
- required_keys: [name, age]
allowed_keys: [name, age, note]
keys:
name: str
age: [int, {min: 0}]
Example valid data:
{name: Lisa, age: 14, note: "Bart's sister"}
Example invalid data:
[] # not a hash
{name: Lisa} # doesn't have the required key: age
{name: Lisa, age: -1} # age must be positive integer
{name: Lisa, age: 14, sex: F} # sex is not in list of allowed keys
Hashes are Comparable and HasElement, so you might want to consult the docs of those roles to see what type attributes are available.
Aside from those, hash also has these type attributes:
Aliases: allowed_keys_regex
Require that all hash keys match a regular expression.
Aliases: forbidden_keys_regex
This is the opposite of keys_match, forbidding all hash keys from matching a regular expression.
Aliases: allowed_keys
Specify that all hash keys must belong to a list of specified values.
For example (in YAML):
[hash, {allowed_keys: [name, age, address]}]
This specifies that only keys 'name', 'age', 'address' are allowed (but none are required).
Aliases: allowed_values
Specify that all hash values must belong to a list of specified values.
For example (in YAML):
[hash, {allowed_values: [1, 2, 3, 4, 5]}]
Require that certain keys exist in the hash.
Require that keys matching a regular expression exist in the hash
Specify schema for hash keys (hash values, actually).
For example (in YAML):
[hash, {keys: { name: str, age: [int, {min: 0}] } }]
This specifies that the value for key 'name' must be a string, and the value for key 'age' must be a positive integer.
Aliases: all_keys
Specify a schema for all hash keys.
For example (in YAML):
[hash, {keys_of: int}]
This specifies that all hash keys must be ints.
Aliases: all_values, values_of, all_elements, all_elems, all_elem
Specify a schema for all hash values.
For example (in YAML):
[hash, {of: int}]
This specifies that all hash values must be ints.
Requires that some elements be of certain type. TYPE is the name of the type, MIN and MAX are numbers, -1 means unlimited.
Example (in YAML):
[hash, {some_of: [[
[str, {one_of: [userid, username, email]}],
[str, {required: Yes}],
1, 1
]]}]
The above requires that the hash has *either* userid, username, or email key specified but not both or three of them. In other words, the hash has to choose to specify only one of the three.
Similar to keys but instead of specifying schema for each key, we specify schema for each set of keys using regular expression.
For example:
[hash=>{keys_regex=>{ '\d'=>"int", '^\D+$'=>"str" }}]
This specifies that for all keys which contain a digit, the values must be int, while for all non-digit-containing keys, the values must be str. Example: { a=>"a", a1=>1, a2=>-3, b=>1 }. Note: b=>1 is valid because 1 is a valid str.
This attribute also obeys allow_extra_hash_keys setting, like keys.
Example:
my $sch = [hash=>{keys_regex=>{'^\w+$'=>[str=>{match=>'^\w+$'}]}}];
my $ds1 = Data::Schema->new(config=>{allow_extra_hash_keys=>1});
$ds1->validate({"contain space" => "contain space"}, $sch); # valid
my $ds2 = Data::Schema->new(); # default allow_extra_hash_keys is 0
$ds2->validate({"contain space" => "contain space"}, $sch); # invalid, no keys matches keys_regex
Aliases: allowed_values_regex
Specifies that all values must be scalar and match regular expression.
Aliases: forbidden_values_regex
The opposite of values_match, requires that all values not match regular expression (but must be a scalar).
Aliases: key_dep, element_deps, elem_deps, element_dep, elem_dep
Specify inter-element dependency. See Data::Schema::Type::HasElement for details.
Overrides allow_extra_hash_keys config. Useful in subschemas, example (in YAML):
# in schemadir/address.yaml
- hash
- allowed_keys: [line1, line2, city, province, country, postcode]
keys:
line1: [str, {required: 1}]
line2: str
city: [str, {required: 1}]
province: [str, {required: 1}]
country: [str, {match: '^[A-Z]{2}$', required: 1}]
postcode: str
# in schemadir/us_address.yaml
- us_address
- allow_extra_keys: 1
- keys:
country: [str, {is: US}]
Without allow_extra_keys, us_address will only allow key 'country' (due to 'keys' limiting allowed hash keys to only those specified in it).
State that A and B are conflicting keys and cannot exist together. And so are C, D, E.
Example:
ds_validate({C=>1 }, [hash=>{conflicting_keys=>[["C", "D", "E"]]}]); # valid
ds_validate({C=>1, D=>1}, [hash=>{conflicting_keys=>[["C", "D", "E"]]}]); # invalid
Just like conflicting_keys, but keys are expressed using regular expression.
State that A and B are codependent keys and must exist together. And so are C, D, E.
Example:
ds_validate({C=>1, D=>1 }, [hash=>{codependent_keys=>[["C", "D", "E"]]}]); # invalid
ds_validate({C=>1, D=>1, E=>1}, [hash=>{codependent_keys=>[["C", "D", "E"]]}]); # valid
Just like codependent_keys, but keys are expressed using regular expression.
Steven Haryanto <stevenharyanto@gmail.com>
This software is copyright (c) 2009 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.
