Add alpha implementation of structured types

The syntax for defininig these types and the guts may change in the future,
but this is a good enough start to release for others to look at.

Author: autarch

.stopwords

@@ -47,5 +47,7 @@ parameterization
 parameterized
 reimplementation
 sigils
+slurpy
+structurable
 subtype
 subtypes

lib/Specio/Constraint/Structurable.pm

@@ -0,0 +1,232 @@
+package Specio::Constraint::Structurable;
+
+use strict;
+use warnings;
+
+our $VERSION = '0.34';
+
+use Carp qw( confess );
+use Role::Tiny::With;
+use Scalar::Util qw( blessed );
+use Specio::DeclaredAt;
+use Specio::OO;
+use Specio::Constraint::Structured;
+use Specio::TypeChecks qw( does_role isa_class );
+
+use Specio::Constraint::Role::Interface;
+with 'Specio::Constraint::Role::Interface';
+
+{
+    ## no critic (Subroutines::ProtectPrivateSubs)
+    my $role_attrs = Specio::Constraint::Role::Interface::_attrs();
+    ## use critic
+
+    my $attrs = {
+        %{$role_attrs},
+        _parameterization_args_builder => {
+            isa      => 'CodeRef',
+            init_arg => 'parameterization_args_builder',
+            required => 1,
+        },
+        _name_builder => {
+            isa      => 'CodeRef',
+            init_arg => 'name_builder',
+            required => 1,
+        },
+        _structured_constraint_generator => {
+            isa       => 'CodeRef',
+            init_arg  => 'structured_constraint_generator',
+            predicate => '_has_structured_constraint_generator',
+        },
+        _structured_inline_generator => {
+            isa       => 'CodeRef',
+            init_arg  => 'structured_inline_generator',
+            predicate => '_has_structured_inline_generator',
+        },
+    };
+
+    ## no critic (Subroutines::ProhibitUnusedPrivateSubroutines)
+    sub _attrs {
+        return $attrs;
+    }
+}
+
+sub BUILD {
+    my $self = shift;
+
+    if ( $self->_has_constraint ) {
+        die
+            'A structurable constraint with a constraint parameter must also have a structured_constraint_generator'
+            unless $self->_has_structured_constraint_generator;
+    }
+
+    if ( $self->_has_inline_generator ) {
+        die
+            'A structurable constraint with an inline_generator parameter must also have a structured_inline_generator'
+            unless $self->_has_structured_inline_generator;
+    }
+
+    return;
+}
+
+sub parameterize {
+    my $self = shift;
+    my %args = @_;
+
+    my $declared_at = $args{declared_at};
+
+    if ($declared_at) {
+        isa_class( $declared_at, 'Specio::DeclaredAt' )
+            or confess
+            q{The "declared_at" parameter passed to ->parameterize must be a Specio::DeclaredAt object};
+    }
+
+    my %parameters
+        = $self->_parameterization_args_builder->( $self, $args{of} );
+
+    $declared_at = Specio::DeclaredAt->new_from_caller(1)
+        unless defined $declared_at;
+
+    my %new_p = (
+        parent      => $self,
+        parameters  => \%parameters,
+        declared_at => $declared_at,
+        name        => $self->_name_builder->( $self, \%parameters ),
+    );
+
+    if ( $self->_has_structured_constraint_generator ) {
+        $new_p{constraint}
+            = $self->_structured_constraint_generator->(%parameters);
+    }
+    else {
+        for my $p (
+            grep {
+                       blessed($_)
+                    && does_role('Specio::Constraint::Role::Interface')
+            } values %parameters
+            ) {
+
+            confess
+                q{Any type objects passed to ->parameterize must be inlinable constraints if the structurable type has an inline_generator}
+                unless $p->can_be_inlined;
+        }
+
+        my $ig = $self->_structured_inline_generator;
+        $new_p{inline_generator}
+            = sub { $ig->( shift, shift, %parameters, @_ ) };
+    }
+
+    return Specio::Constraint::Structured->new(%new_p);
+}
+
+## no critic (Subroutines::ProhibitUnusedPrivateSubroutines)
+sub _name_or_anon {
+    return $_[1]->_has_name ? $_[1]->name : 'ANON';
+}
+## use critic
+
+__PACKAGE__->_ooify;
+
+1;
+
+# ABSTRACT: A class which represents structurable constraints
+
+__END__
+
+=pod
+
+=for Pod::Coverage BUILD
+
+=head1 SYNOPSIS
+
+    my $tuple = t('Tuple');
+
+    my $tuple_of_str_int = $tuple->parameterize( of => [ t('Str'), t('Int') ] );
+
+=head1 DESCRIPTION
+
+This class implements the API for structurable types like C<Dict>, C<Map>< and
+C<Tuple>.
+
+=head1 API
+
+This class implements the same API as L<Specio::Constraint::Simple>, with a few
+additions.
+
+=head2 Specio::Constraint::Structurable->new(...)
+
+This class's constructor accepts two additional parameters:
+
+=over 4
+
+=item * parameterization_args_builder
+
+This is a subroutine that takes the values passed to C<of> and returns a hash
+of named arguments. These arguments will then be passed into the
+C<structured_constraint_generator> or C<structured_inline_generator>.
+
+This should also do argument checking to make sure that the argument passed
+are valid. For example, the C<Tuple> type turns the arrayref passed to C<of>
+into a hash, along the way checking that the caller did not do things like
+interleave optional and required elements or mix optional and slurpy together
+in the definition.
+
+This parameter is required.
+
+=item * name_builder
+
+This is a subroutine that is called to generate a name for the structured type
+when it is created. This will be called as a method on the
+C<Specio::Constraint::Structurable> object. It will be passed the hash of
+arguments returned by the C<parameterization_args_builder>.
+
+This parameter is required.
+
+=item * structured_constraint_generator
+
+This is a subroutine that generates a new constraint subroutine when the type
+is structured.
+
+It will be called as a method on the type and will be passed the hash of
+arguments returned by the C<parameterization_args_builder>.
+
+This parameter is mutually exclusive with the C<structured_inline_generator>
+parameter.
+
+This parameter or the C<structured_inline_generator> parameter is required.
+
+=item * structured_inline_generator
+
+This is a subroutine that generates a new inline generator subroutine when the
+type is structured.
+
+It will be called as a method on the L<Specio::Constraint::Structured> object
+when that object needs to generate an inline constraint. It will receive the
+type parameter as the first argument and the variable name as a string as the
+second.
+
+The remaining arguments will be the parameter hash returned by the
+C<parameterization_args_builder>.
+
+This probably seems fairly confusing, so looking at the examples in the
+L<Specio::Library::Structured::*> code may be helpful.
+
+This parameter is mutually exclusive with the
+C<structured_constraint_generator> parameter.
+
+This parameter or the C<structured_constraint_generator> parameter is
+required.
+
+=back
+
+=head2 $type->parameterize(...)
+
+This method takes two arguments. The C<of> argument should be an object which
+does the L<Specio::Constraint::Role::Interface> role, and is required.
+
+The other argument, C<declared_at>, is optional. If it is not given, then a
+new L<Specio::DeclaredAt> object is creating using a call stack depth of 1.
+
+This method returns a new L<Specio::Constraint::Structured> object.
+
+=cut

lib/Specio/Constraint/Structured.pm

@@ -0,0 +1,99 @@
+package Specio::Constraint::Structured;
+
+use strict;
+use warnings;
+
+our $VERSION = '0.34';
+
+use List::Util qw( all );
+use Role::Tiny::With;
+use Specio::OO;
+use Specio::TypeChecks qw( does_role );
+use Storable qw( dclone );
+
+use Specio::Constraint::Role::Interface;
+with 'Specio::Constraint::Role::Interface';
+
+{
+    ## no critic (Subroutines::ProtectPrivateSubs)
+    my $attrs = dclone( Specio::Constraint::Role::Interface::_attrs() );
+    ## use critic
+
+    $attrs->{parent}{isa}      = 'Specio::Constraint::Structurable';
+    $attrs->{parent}{required} = 1;
+
+    $attrs->{parameters} = {
+        isa      => 'HashRef',
+        required => 1,
+    };
+
+    ## no critic (Subroutines::ProhibitUnusedPrivateSubroutines)
+    sub _attrs {
+        return $attrs;
+    }
+}
+
+sub can_be_inlined {
+    my $self = shift;
+    return $self->_has_inline_generator;
+}
+
+__PACKAGE__->_ooify;
+
+1;
+
+# ABSTRACT: A class which represents structured constraints
+
+__END__
+
+=pod
+
+=for Pod::Coverage can_be_inlined type_parameter
+
+=head1 SYNOPSIS
+
+    my $tuple = t('Tuple');
+
+    my $tuple_of_str_int = $tuple->parameterize( of => [ t('Str'), t('Int') ] );
+
+    my $parent = $tuple_of_str_int->parent; # returns Tuple
+    my $parameters = $arrayref_of_int->parameters; # returns { of => [ t('Str'), t('Int') ] }
+
+=head1 DESCRIPTION
+
+This class implements the API for structured types.
+
+=head1 API
+
+This class implements the same API as L<Specio::Constraint::Simple>, with a few
+additions.
+
+=head2 Specio::Constraint::Structured->new(...)
+
+This class's constructor accepts two additional parameters:
+
+=over 4
+
+=item * parent
+
+This should be the L<Specio::Constraint::Structurable> object from which this
+object was created.
+
+This parameter is required.
+
+=item * parameters
+
+This is the hashref of parameters for the structured type. These are the
+parameters returned by the C<Structurable> type's
+C<parameterization_args_builder>. The exact form of this hashref will vary for
+each structured type.
+
+This parameter is required.
+
+=back
+
+=head2 $type->parameters
+
+Returns the hashref that was passed to the constructor.
+
+=cut