1Specio::Library::StructUusreerd(C3o)ntributed Perl DocumSepnetcaitoi:o:nLibrary::Structured(3)
2
3
4

NAME

6       Specio::Library::Structured - Structured types for Specio (Dict, Map,
7       Tuple)
8

VERSION

10       version 0.48
11

SYNOPSIS

13           use Specio::Library::Builtins;
14           use Specio::Library::String;
15           use Specio::Library::Structured;
16
17           my $map = t(
18               'Map',
19               of => {
20                   key   => t('NonEmptyStr'),
21                   value => t('Int'),
22               },
23           );
24           my $tuple = t(
25               'Tuple',
26               of => [ t('Str'), t('Num') ],
27           );
28           my $dict = t(
29               'Dict',
30               of => {
31                   kv => {
32                       name => t('Str'),
33                       age  => t('Int'),
34                   },
35               },
36           );
37

DESCRIPTION

39       This particular library should be considered in an alpha state. The
40       syntax for defining structured types may change, as well as some of the
41       internals of its implementation.
42
43       This library provides a set of structured types for Specio, "Dict",
44       "Map", and "Tuple". This library also exports two helper subs used for
45       some types, "optional" and "slurpy".
46
47       All structured types are parameterized by calling "t( 'Type Name', of
48       => ...  )". The arguments passed after "of" vary for each type.
49
50   Dict
51       A "Dict" is a hashref with a well-defined set of keys and types for
52       those key.
53
54       The argument passed to "of" should be a single hashref. That hashref
55       must contain a "kv" key defining the expected keys and the types for
56       their values.  This "kv" value is itself a hashref. If a key/value pair
57       is optional, use "optional" around the type for that key:
58
59           my $person = t(
60               'Dict',
61               of => {
62                   kv => {
63                       first  => t('NonEmptyStr'),
64                       middle => optional( t('NonEmptyStr') ),
65                       last   => t('NonEmptyStr'),
66                   },
67               },
68           );
69
70       If a key is optional, then it can be omitted entirely, but if it passed
71       then it's type will be checked, so it cannot just be set to "undef".
72
73       You can also pass a "slurpy" key. If this is passed, then the "Dict"
74       will allow other, unknown keys, as long as they match the specified
75       type:
76
77           my $person = t(
78               'Dict',
79               of => {
80                   kv => {
81                       first  => t('NonEmptyStr'),
82                       middle => optional( t('NonEmptyStr') ),
83                       last   => t('NonEmptyStr'),
84                   },
85                   slurpy => t('Int'),
86               },
87           );
88
89   Map
90       A "Map" is a hashref with specified types for its keys and values, but
91       no well-defined key names.
92
93       The argument passed to "of" should be a single hashref with two keys,
94       "key" and "value". The type for the "key" will typically be some sort
95       of key, but if you're using a tied hash or an object with hash
96       overloading it could conceivably be any sort of value.
97
98   Tuple
99       A "Tuple" is an arrayref with a fixed set of members in a specific
100       order.
101
102       The argument passed to "of" should be a single arrayref consisting of
103       types.  You can mark a slot in the "Tuple" as optional by wrapping the
104       type in a call to "optional":
105
106           my $record = t(
107               'Tuple',
108               of => [
109                   t('PositiveInt'),
110                   t('Str'),
111                   optional( t('Num') ),
112                   optional( t('Num') ),
113               ],
114           );
115
116       You can have as many "optional" elements as you want, but they must
117       always come in sequence at the end of the tuple definition. You cannot
118       interleave required and optional elements.
119
120       You can also make the Tuple accept an arbitrary number of values by
121       wrapping the last type in a call to "slurpy":
122
123           my $record = t(
124               'Tuple',
125               of => [
126                   t('PositiveInt'),
127                   t('Str'),
128                   slurpy( t('Num') ),
129               ],
130           );
131
132       In this case, the "Tuple" will require the first two elements and then
133       allow any number (including zero) of "Num" elements.
134
135       You cannot mix "optional" and "slurpy" in a "Tuple" definition.
136

LIMITATIONS

138       Currently all structured types require that the types they are
139       structured with can be inlined. This may change in the future, but
140       inlining all your types is a really good idea, so you should do that
141       anyway.
142

SUPPORT

144       Bugs may be submitted at
145       <https://github.com/houseabsolute/Specio/issues>.
146

SOURCE

148       The source code repository for Specio can be found at
149       <https://github.com/houseabsolute/Specio>.
150

AUTHOR

152       Dave Rolsky <autarch@urth.org>
153

155       This software is Copyright (c) 2012 - 2022 by Dave Rolsky.
156
157       This is free software, licensed under:
158
159         The Artistic License 2.0 (GPL Compatible)
160
161       The full text of the license can be found in the LICENSE file included
162       with this distribution.
163
164
165
166perl v5.38.0                      2023-07-21    Specio::Library::Structured(3)
Impressum