Steven Haryanto > Data-Schema-0.136 > Data::Schema::Type::Hash

Download:
Data-Schema-0.136.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.136   Source  

NAME ^

Data::Schema::Type::Hash - Type handler for hash ('hash')

VERSION ^

version 0.136

SYNOPSIS ^

 use Data::Schema;

DESCRIPTION ^

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

TYPE ATTRIBUTES ^

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:

keys_match => REGEX

Aliases: allowed_keys_regex

Require that all hash keys match a regular expression.

keys_not_match => REGEX

Aliases: forbidden_keys_regex

This is the opposite of keys_match, forbidding all hash keys from matching a regular expression.

keys_one_of => [VALUE, ...]

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).

values_one_of => [VALUE, ...]

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]}]

required_keys => [KEY1, KEY2. ...]

Require that certain keys exist in the hash.

required_keys_regex => REGEX

Require that keys matching a regular expression exist in the hash

keys => {KEY=>SCHEMA1, KEY2=>SCHEMA2, ...}

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.

keys_of => SCHEMA

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.

of => SCHEMA

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.

some_of => [[KEY_SCHEMA, VALUE_SCHEMA, MIN, MAX], [KEY_SCHEMA2, VALUE_SCHEMA2, MIN2, MAX2], ...]

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.

keys_regex => {REGEX1=>SCHEMA1, REGEX2=>SCHEMA2, ...}

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

values_match => REGEX

Aliases: allowed_values_regex

Specifies that all values must be scalar and match regular expression.

values_not_match => REGEX

Aliases: forbidden_values_regex

The opposite of values_match, requires that all values not match regular expression (but must be a scalar).

key_deps => SCHEMA

Aliases: key_dep, element_deps, elem_deps, element_dep, elem_dep

Specify inter-element dependency. See Data::Schema::Type::HasElement for details.

allow_extra_keys => BOOL

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).

conflicting_keys => [[A, B], [C, D, E], ...]

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

conflicting_keys_regex => [[REGEX_A, REGEX_B], [REGEX_C, REGEX_D, REGEX_E], ...]

Just like conflicting_keys, but keys are expressed using regular expression.

codependent_keys => [[A, B], [C, D, E], ...]

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

codependent_keys_regex => [[REGEX_A, REGEX_B], [REGEX_C, REGEX_D, REGEX_E], ...]

Just like codependent_keys, but keys are expressed using regular expression.

AUTHOR ^

  Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE ^

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.

syntax highlighting: