.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Specio::Library::Structured 3pm"
.TH Specio::Library::Structured 3pm "2021-01-31" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Specio::Library::Structured \- Structured types for Specio (Dict, Map, Tuple)
.SH "VERSION"
.IX Header "VERSION"
version 0.47
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use Specio::Library::Builtins;
\&    use Specio::Library::String;
\&    use Specio::Library::Structured;
\&
\&    my $map = t(
\&        \*(AqMap\*(Aq,
\&        of => {
\&            key   => t(\*(AqNonEmptyStr\*(Aq),
\&            value => t(\*(AqInt\*(Aq),
\&        },
\&    );
\&    my $tuple = t(
\&        \*(AqTuple\*(Aq,
\&        of => [ t(\*(AqStr\*(Aq), t(\*(AqNum\*(Aq) ],
\&    );
\&    my $dict = t(
\&        \*(AqDict\*(Aq,
\&        of => {
\&            kv => {
\&                name => t(\*(AqStr\*(Aq),
\&                age  => t(\*(AqInt\*(Aq),
\&            },
\&        },
\&    );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBThis 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.\fR
.PP
This library provides a set of structured types for Specio, \f(CW\*(C`Dict\*(C'\fR, \f(CW\*(C`Map\*(C'\fR,
and \f(CW\*(C`Tuple\*(C'\fR. This library also exports two helper subs used for some types,
\&\f(CW\*(C`optional\*(C'\fR and \f(CW\*(C`slurpy\*(C'\fR.
.PP
All structured types are parameterized by calling \f(CW\*(C`t( \*(AqType Name\*(Aq, of => ...
)\*(C'\fR. The arguments passed after \f(CW\*(C`of\*(C'\fR vary for each type.
.SS "Dict"
.IX Subsection "Dict"
A \f(CW\*(C`Dict\*(C'\fR is a hashref with a well-defined set of keys and types for those key.
.PP
The argument passed to \f(CW\*(C`of\*(C'\fR should be a single hashref. That hashref must
contain a \f(CW\*(C`kv\*(C'\fR key defining the expected keys and the types for their values.
This \f(CW\*(C`kv\*(C'\fR value is itself a hashref. If a key/value pair is optional, use
\&\f(CW\*(C`optional\*(C'\fR around the \fItype\fR for that key:
.PP
.Vb 10
\&    my $person = t(
\&        \*(AqDict\*(Aq,
\&        of => {
\&            kv => {
\&                first  => t(\*(AqNonEmptyStr\*(Aq),
\&                middle => optional( t(\*(AqNonEmptyStr\*(Aq) ),
\&                last   => t(\*(AqNonEmptyStr\*(Aq),
\&            },
\&        },
\&    );
.Ve
.PP
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 \f(CW\*(C`undef\*(C'\fR.
.PP
You can also pass a \f(CW\*(C`slurpy\*(C'\fR key. If this is passed, then the \f(CW\*(C`Dict\*(C'\fR will
allow other, unknown keys, as long as they match the specified type:
.PP
.Vb 11
\&    my $person = t(
\&        \*(AqDict\*(Aq,
\&        of => {
\&            kv => {
\&                first  => t(\*(AqNonEmptyStr\*(Aq),
\&                middle => optional( t(\*(AqNonEmptyStr\*(Aq) ),
\&                last   => t(\*(AqNonEmptyStr\*(Aq),
\&            },
\&            slurpy => t(\*(AqInt\*(Aq),
\&        },
\&    );
.Ve
.SS "Map"
.IX Subsection "Map"
A \f(CW\*(C`Map\*(C'\fR is a hashref with specified types for its keys and values, but no
well-defined key names.
.PP
The argument passed to \f(CW\*(C`of\*(C'\fR should be a single hashref with two keys, \f(CW\*(C`key\*(C'\fR
and \f(CW\*(C`value\*(C'\fR. The type for the \f(CW\*(C`key\*(C'\fR 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.
.SS "Tuple"
.IX Subsection "Tuple"
A \f(CW\*(C`Tuple\*(C'\fR is an arrayref with a fixed set of members in a specific order.
.PP
The argument passed to \f(CW\*(C`of\*(C'\fR should be a single arrayref consisting of types.
You can mark a slot in the \f(CW\*(C`Tuple\*(C'\fR as optional by wrapping the type in a call
to \f(CW\*(C`optional\*(C'\fR:
.PP
.Vb 9
\&    my $record = t(
\&        \*(AqTuple\*(Aq,
\&        of => [
\&            t(\*(AqPositiveInt\*(Aq),
\&            t(\*(AqStr\*(Aq),
\&            optional( t(\*(AqNum\*(Aq) ),
\&            optional( t(\*(AqNum\*(Aq) ),
\&        ],
\&    );
.Ve
.PP
You can have as many \f(CW\*(C`optional\*(C'\fR 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.
.PP
You can also make the Tuple accept an arbitrary number of values by wrapping
the last type in a call to \f(CW\*(C`slurpy\*(C'\fR:
.PP
.Vb 8
\&    my $record = t(
\&        \*(AqTuple\*(Aq,
\&        of => [
\&            t(\*(AqPositiveInt\*(Aq),
\&            t(\*(AqStr\*(Aq),
\&            slurpy( t(\*(AqNum\*(Aq) ),
\&        ],
\&    );
.Ve
.PP
In this case, the \f(CW\*(C`Tuple\*(C'\fR will require the first two elements and then allow
any number (including zero) of \f(CW\*(C`Num\*(C'\fR elements.
.PP
You cannot mix \f(CW\*(C`optional\*(C'\fR and \f(CW\*(C`slurpy\*(C'\fR in a \f(CW\*(C`Tuple\*(C'\fR definition.
.SH "LIMITATIONS"
.IX Header "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.
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs may be submitted at <https://github.com/houseabsolute/Specio/issues>.
.PP
I am also usually active on \s-1IRC\s0 as 'autarch' on \f(CW\*(C`irc://irc.perl.org\*(C'\fR.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for Specio can be found at <https://github.com/houseabsolute/Specio>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky <autarch@urth.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2012 \- 2021 by Dave Rolsky.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Artistic License 2.0 (GPL Compatible)
.Ve
.PP
The full text of the license can be found in the
\&\fI\s-1LICENSE\s0\fR file included with this distribution.