# phpman > perldoc > Specio::Library::Structured

## NAME
    [Specio::Library::Structured](https://www.chedong.com/phpMan.php/perldoc/Specio%3A%3ALibrary%3A%3AStructured/markdown) - Structured types for Specio (Dict, Map, Tuple)

## VERSION
    version 0.47

## SYNOPSIS
        use [Specio::Library::Builtins](https://www.chedong.com/phpMan.php/perldoc/Specio%3A%3ALibrary%3A%3ABuiltins/markdown);
        use [Specio::Library::String](https://www.chedong.com/phpMan.php/perldoc/Specio%3A%3ALibrary%3A%3AString/markdown);
        use [Specio::Library::Structured](https://www.chedong.com/phpMan.php/perldoc/Specio%3A%3ALibrary%3A%3AStructured/markdown);

        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.