NAME

VERSION

SYNOPSIS

    package MyApp::Type::Library;

    use Specio::Declare;
    use Specio::Library::Builtins;

    declare(
        'PositiveInt',
        parent => t('Int'),
        inline => sub {
            $_[0]->parent->inline_check( $_[1] )
                . ' && ( '
                . $_[1]
                . ' > 0 )';
        },
    );

    # or ...

    declare(
        'PositiveInt',
        parent => t('Int'),
        where  => sub { $_[0] > 0 },
    );

    declare(
        'ArrayRefOfPositiveInt',
        parent => t(
            'ArrayRef',
            of => t('PositiveInt'),
        ),
    );

    coerce(
        'ArrayRefOfPositiveInt',
        from  => t('PositiveInt'),
        using => sub { [ $_[0] ] },
    );

    any_can_type(
        'Duck',
        methods => [ 'duck_walk', 'quack' ],
    );

    object_isa_type('MyApp::Person');

DESCRIPTION

Note that this is not a proper type system for Perl. Nothing in this distribution will magically make the Perl interpreter start checking a value's type on assignment to a variable. In fact, there's no built-in way to apply a type to a variable at all.

Instead, you can explicitly check a value against a type, and optionally coerce values to that type.

My long-term goal is to replace Moose's built-in types and MooseX::Types with this module.

WHAT IS A TYPE?

Types can be named or anonymous, and each type can have a parent type. A type's constraint is optional because sometimes you may want to create a named subtype of some existing type without adding additional constraints.

Constraints can be expressed either in terms of a simple subroutine reference or in terms of an inline generator subroutine reference. The former is easier to write but the latter is preferred because it allow for better optimization.

A type can also have an optional message generator subroutine reference. You can use this to provide a more intelligent error message when a value does not pass the constraint, though the default message should suffice for most cases.

Finally, you can associate a set of coercions with a type. A coercion is a subroutine reference (or inline generator, like constraints), that takes a value of one type and turns it into a value that matches the type the coercion belongs to.

BUILTIN TYPES

  Item
      Bool
      Maybe (of `a)
      Undef
      Defined
          Value
              Str
                  Num
                      Int
                  ClassName
          Ref
              ScalarRef (of `a)
              ArrayRef (of `a)
              HashRef (of `a)
              CodeRef
              RegexpRef
              GlobRef
              FileHandle
              Object

The "Item" type accepts anything and everything.

The "Bool" type only accepts "undef", 0, or 1.

The "Undef" type only accepts "undef".

The "Defined" type accepts anything except "undef".

The "Num" and "Int" types are stricter about numbers than Perl is. Specifically, they do not allow any sort of space in the number, nor do they accept "Nan", "Inf", or "Infinity".

The "ClassName" type constraint checks that the name is valid and that the class is loaded.

The "FileHandle" type accepts either a glob, a scalar filehandle, or anything that isa IO::Handle.

All types accept overloaded objects that support the required operation. See below for details.

PARAMETERIZABLE TYPES

When they are parameterized, the "ScalarRef" and "ArrayRef" types check that the value(s) they refer to match the type parameter. For the "HashRef" type, the parameter applies to the values (keys are never checked).

REGISTRIES AND IMPORTING

This means that a type named "Foo" in one package may not be the same as "Foo" in another package. This has potential for confusion, but it also avoids the magic action at a distance pollution that comes with a global type naming system.

The registry is managed internally by the Specio distribution's modules, and is not exposed to your code. To access a type, you always call "t('TypeName')".

This returns the named type or dies if no such type exists.

Because types are always copied on import, it's safe to create coercions on any type. Your coercion from "Str" to "Int" will not be seen by any other package, unless that package explicitly imports your "Int" type.

When you import types, you import every type defined in the package you import from. However, you can overwrite an imported type with your own type definition. You cannot define the same type twice internally.

CREATING A TYPE LIBRARY

  package MyApp::Type::Library;

  use parent 'Specio::Exporter';

  use Specio::Declare;
  use Specio::Library::Builtins;

  declare(
      'Foo',
      parent => t('Str'),
      where  => sub { $_[0] =~ /foo/i },
  );

Now the MyApp::Type::Library package will export a single type named "Foo". It does not re-export the types provided by Specio::Library::Builtins.

If you want to make your library re-export some other libraries types, you can ask for this explicitly:

  package MyApp::Type::Library;

  use parent 'Specio::Exporter';

  use Specio::Declare;
  use Specio::Library::Builtins -reexport;

  declare( 'Foo, ... );

Now MyApp::Types::Library exports any types it defines, as well as all the types defined in Specio::Library::Builtins.

DECLARING TYPES

USING SPECIO WITH Moose

USING SPECIO WITH Moo

    package Foo;

    use Specio::Declare;
    use Specio::Library::Builtins;
    use Moo;

    my $str_type = t('Str');
    has string => (
       is  => 'ro',
       isa => $str_type,
    );

    my $ucstr = declare(
        'UCStr',
        parent => t('Str'),
        where  => sub { $_[0] =~ /^[A-Z]+$/ },
    );

    coerce(
        $ucstr,
        from  => t('Str'),
        using => sub { return uc $_[0] },
    );

    has ucstr => (
        is     => 'ro',
        isa    => $ucstr,
        coerce => $ucstr->coercion_sub,
    );

The subs returned by Specio use Sub::Quote internally and are suitable for inlining.

USING SPECIO WITH OTHER THINGS

Moose, MooseX::Types, and Specio

Here are some of the salient differences:

• Types names are strings, but they're not global

  Unlike Moose and MooseX::Types, type names are always local to the current package. There is no possibility of name collision between different modules, so you can safely use short type names.

  Unlike MooseX::Types, types are strings, so there is no possibility of colliding with existing class or subroutine names.

• No type auto-creation

  Types are always retrieved using the "t()" subroutine. If you pass an unknown name to this subroutine it dies. This is different from Moose and MooseX::Types, which assume that unknown names are class names.

• Anon types are explicit

  With Moose and MooseX::Types, you use the same subroutine, "subtype()", to declare both named and anonymous types. With Specio, you use "declare()" for named types and "anon()" for anonymous types.

• Class and object types are separate

  Moose and MooseX::Types have "class_type" and "duck_type". The former type requires an object, while the latter accepts a class name or object.

  With Specio, the distinction between accepting an object versus object or class is explicit. There are six declaration helpers, "object_can_type", "object_does_type", "object_isa_type", "any_can_type", "any_does_type", and "any_isa_type".

• Overloading support is baked in

  Perl's overloading is quite broken but ignoring it makes Moose's type system frustrating to use in many cases.

• Types can either have a constraint or inline generator, not both

  Moose and MooseX::Types types can be defined with a subroutine reference as the constraint, an inline generator subroutine, or both. This is purely for backwards compatibility, and it makes the internals more complicated than they need to be.

  With Specio, a constraint can have either a subroutine reference or an inline generator, not both.

• Coercions can be inlined

  I simply never got around to implementing this in Moose.

• No crazy coercion features

  Moose has some bizarre (and mostly) undocumented features relating to coercions and parameterizable types. This is a misfeature.

OPTIONAL PREREQS

• Ref::Util

  Installing this will speed up a number of type checks for built-in types.

• XString

  If this is installed it will be loaded instead of the B module if you have Perl 5.10 or greater. This module is much more memory efficient than loading all of B.

• Sub::Util or Sub::Name

  If one of these is installed then stack traces that end up in Specio code will have much better subroutine names for any frames.

WHY THE NAME?

LONG-TERM PLANS

SUPPORT

I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".

SOURCE

DONATIONS

Please note that I am not suggesting that you must do this in order for me to continue working on this particular software. I will continue to do so, inasmuch as I have in the past, for as long as it interests me.

Similarly, a donation made in this way will probably not make me work on this software much more, unless I get so many donations that I can consider working on free software full time (let's all have a chuckle at that together).

To donate, log into PayPal and send money to autarch@urth.org, or use the button at <https://www.urth.org/fs-donation.html>.

AUTHOR

CONTRIBUTORS

• Chris White <chrisw@leehayes.com>
• cpansprout <cpansprout@gmail.com>
• Graham Knop <haarg@haarg.org>
• Karen Etheridge <ether@cpan.org>

COPYRIGHT AND LICENSE

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.