The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Data-Schema-0.11
/ Data::Schema::Type::Hash

NAME

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

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 HasLength, 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

Require that all hash keys must match a regular expression.

keys_not_match => REGEX

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

keys_one_of => [VALUE, ...]

Specify that all hash keys must belong to a list of specified values.

Synonyms: allowed_keys

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, ...]

Specify that all hash values must belong to a list of specified values.

Synonyms: allowed_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

Specify a schema for all hash keys.

For example (in YAML):

 [hash, {keys_of: int}]

This specifies that all hash keys must be ints.

values_of => SCHEMA

Specify a schema for all hash values.

Synonyms: all_elements, all_elems, all_elem

For example (in YAML):

 [hash, {values_of: int}]

This specifies that all hash values must be ints.

of => [SCHEMA_FOR_KEYS, SCHEMA_FOR_VALUES]

Specify a pair of schemas for all keys and values.

For example (in YAML):

 [hash, {of: [int, int]}]

This specifies that all hash keys as well as 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.

values_match => REGEX

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

values_not_match => REGEX

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

AUTHOR

Steven Haryanto, <steven at masterweb.net>

COPYRIGHT & LICENSE

Copyright 2009 Steven Haryanto, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.