Specio::Library::Structured(3)
NAME
Specio::Library::Structured - Structured types for Specio (Dict, Map,
Tuple)
VERSION
version 0.47
SYNOPSIS
use Specio::Library::Builtins;
use Specio::Library::String;
use Specio::Library::Structured;
my $map = t(
'Map',
of => {
key => t('NonEmptyStr'),
value => t('Int'),
},
);
my $tuple = t(
'Tuple',
of => [ t('Str'), t('Num') ],
);
my $dict = t(
'Dict',
of => {
kv => {
name => t('Str'),
age => t('Int'),
},
},
);
DESCRIPTION
This particular library should be considered in an alpha state. The
syntax for defining structured types may change, as well as some of the
internals of its implementation.
This library provides a set of structured types for Specio, "Dict",
"Map", and "Tuple". This library also exports two helper subs used for
some types, "optional" and "slurpy".
All structured types are parameterized by calling "t( 'Type Name', of
=> ... )". The arguments passed after "of" vary for each type.
Dict
A "Dict" is a hashref with a well-defined set of keys and types for
those key.
The argument passed to "of" should be a single hashref. That hashref
must contain a "kv" key defining the expected keys and the types for
their values. This "kv" value is itself a hashref. If a key/value pair
is optional, use "optional" around the type for that key:
my $person = t(
'Dict',
of => {
kv => {
first => t('NonEmptyStr'),
middle => optional( t('NonEmptyStr') ),
last => t('NonEmptyStr'),
},
},
);
If a key is optional, then it can be omitted entirely, but if it passed
then it's type will be checked, so it cannot just be set to "undef".
You can also pass a "slurpy" key. If this is passed, then the "Dict"
will allow other, unknown keys, as long as they match the specified
type:
my $person = t(
'Dict',
of => {
kv => {
first => t('NonEmptyStr'),
middle => optional( t('NonEmptyStr') ),
last => t('NonEmptyStr'),
},
slurpy => t('Int'),
},
);
Map
A "Map" is a hashref with specified types for its keys and values, but
no well-defined key names.
The argument passed to "of" should be a single hashref with two keys,
"key" and "value". The type for the "key" will typically be some sort
of key, but if you're using a tied hash or an object with hash
overloading it could conceivably be any sort of value.
Tuple
A "Tuple" is an arrayref with a fixed set of members in a specific
order.
The argument passed to "of" should be a single arrayref consisting of
types. You can mark a slot in the "Tuple" as optional by wrapping the
type in a call to "optional":
my $record = t(
'Tuple',
of => [
t('PositiveInt'),
t('Str'),
optional( t('Num') ),
optional( t('Num') ),
],
);
You can have as many "optional" elements as you want, but they must
always come in sequence at the end of the tuple definition. You cannot
interleave required and optional elements.
You can also make the Tuple accept an arbitrary number of values by
wrapping the last type in a call to "slurpy":
my $record = t(
'Tuple',
of => [
t('PositiveInt'),
t('Str'),
slurpy( t('Num') ),
],
);
In this case, the "Tuple" will require the first two elements and then
allow any number (including zero) of "Num" elements.
You cannot mix "optional" and "slurpy" in a "Tuple" definition.
LIMITATIONS
Currently all structured types require that the types they are
structured with can be inlined. This may change in the future, but
inlining all your types is a really good idea, so you should do that
anyway.
SUPPORT
Bugs may be submitted at
<https://github.com/houseabsolute/Specio/issues>.
I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
SOURCE
The source code repository for Specio can be found at
<https://github.com/houseabsolute/Specio>.
AUTHOR
Dave Rolsky <autarch@urth.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2012 - 2021 by Dave Rolsky.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
The full text of the license can be found in the LICENSE file included
with this distribution.
perl v5.30.3 2021-01-29 Specio::Library::Structured(3)
specio 0.470.0 - Generated Mon Mar 1 18:56:38 CST 2021