NAME<\/a> Specio \u2212 Type constraints and coercions for Perl<\/p>\n version 0.46<\/p>\n package MyApp::Type::Library; The “Specio” distribution provides classes for representing type constraints and coercion, along with syntax sugar for declaring them.<\/p>\n 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\u2019s type on assignment to a variable. In fact, there\u2019s no built-in way to apply a type to a variable at all.<\/p>\n Instead, you can explicitly check a value against a type, and optionally coerce values to that type.<\/p>\n My long-term goal is to replace Moose\u2019s built-in types and MooseX::Types with this module.<\/p>\n At it\u2019s core, a type is simply a constraint. A constraint is code that checks a value and returns true or false. Most constraints are represented by Specio::Constraint::Simple objects. However, there are other type constraint classes for specialized kinds of constraints.<\/p>\n Types can be named or anonymous, and each type can have a parent type. A type\u2019s constraint is optional because sometimes you may want to create a named subtype of some existing type without adding additional constraints.<\/p>\n 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.<\/p>\n 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.<\/p>\n 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.<\/p>\n This distribution ships with a set of builtin types representing the types provided by the Perl interpreter itself. They are arranged in a hierarchy as follows:<\/p>\n Item The “Item” type accepts anything and everything.<\/p>\n The “Bool” type only accepts “undef”, 0, or 1.<\/p>\n The “Undef” type only accepts “undef”.<\/p>\n The “Defined” type accepts anything except<\/i> “undef”.<\/p>\n 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”.<\/p>\n The “ClassName” type constraint checks that the name is valid and<\/i> that the class is loaded.<\/p>\n The “FileHandle” type accepts either a glob, a scalar filehandle, or anything that isa IO::Handle.<\/p>\n All types accept overloaded objects that support the required operation. See below for details.<\/p>\n Overloading<\/b> However, unlike Moose, all type constraints allow overloaded objects where they make sense.<\/p>\n For types where overloading makes sense, we explicitly check that the object provides the type overloading we expect. We do not<\/i> simply try to use the object as the type in question and hope it works. This means that these checks effectively ignore the “fallback” setting for the overloaded object. In other words, an object that overloads stringification will not pass the “Bool” type check unless it also<\/i> overloads boolification.<\/p>\n Most types do not check that the overloaded method actually returns something that matches the constraint. This may change in the future.<\/p>\n The “Bool” type accepts an object that implements “bool” overloading.<\/p>\n The “Str” type accepts an object that implements string (“q{“”}”) overloading.<\/p>\n The “Num” type accepts an object that implements numeric (“‘0+’}”) overloading. The “Int” type does as well, but it will check that the overloading returns an actual integer.<\/p>\n The “ClassName” type will accept an object with string overloading that returns a class name.<\/p>\n To make this all more confusing, the “Value” type will never<\/i> accept an object, even though some of its subtypes will.<\/p>\n The various reference types all accept objects which provide the appropriate overloading. The “FileHandle” type accepts an object which overloads globification as long as the returned glob is an open filehandle.<\/p>\n Any type followed by a type parameter “of `a” in the hierarchy above can be parameterized. The parameter is itself a type, so you can say you want an “ArrayRef of Int”, or even an “ArrayRef of HashRef of ScalarRef of ClassName”.<\/p>\n 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).<\/p>\n Maybe<\/b> This is useful for optional attributes or parameters. However, you\u2019re probably better off making your code simply not pass the parameter at all This usually makes for a simpler API.<\/small><\/p>\n Types are local to each package where they are used. When you “import” types from some other library, you are actually making a copy of that type.<\/p>\n 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.<\/p>\n The registry is managed internally by the Specio distribution\u2019s modules, and is not exposed to your code. To access a type, you always call “t(‘TypeName’)”.<\/p>\n This returns the named type or dies if no such type exists.<\/p>\n Because types are always copied on import, it\u2019s 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.<\/p>\n When you import types, you import every type defined in the package you import from. However, you can<\/i> overwrite an imported type with your own type definition. You cannot<\/i> define the same type twice internally.<\/p>\n By default, all types created inside a package are invisible to other packages. If you want to create a type library, you need to inherit from Specio::Exporter package:<\/p>\n package MyApp::Type::Library; Now the MyApp::Type::Library package will export a single type named “Foo”. It does not<\/i> re-export the types provided by Specio::Library::Builtins.<\/p>\n If you want to make your library re-export some other libraries types, you can ask for this explicitly:<\/p>\n package MyApp::Type::Library; Now MyApp::Types::Library exports any types it defines, as well as all the types defined in Specio::Library::Builtins.<\/p>\n Use the Specio::Declare module to declare types. It exports a set of helpers for declaring types. See that module\u2019s documentation for more details on these helpers.<\/p>\n This should just work. Use a Specio type anywhere you\u2019d specify a type.<\/p>\n Using Specio with Moo is easy. You can pass Specio constraint objects as “isa” parameters for attributes. For coercions, simply call “$type\u2212>coercion_sub”.<\/p>\n package Foo; The subs returned by Specio use Sub::Quote internally and are suitable for inlining.<\/p>\n See Specio::Constraint::Simple for the API<\/small> that all constraint objects share.<\/p>\n This module aims to supplant both Moose\u2019s built-in type system (see Moose::Util::TypeConstraints aka MUTC<\/small> ) and MooseX::Types, which attempts to patch some of the holes in the Moose built-in type design.<\/p>\n Here are some of the salient differences:<\/p>\n
VERSION<\/a>
SYNOPSIS<\/a>
DESCRIPTION<\/a>
WHAT IS A TYPE?<\/a>
BUILTIN TYPES<\/a>
PARAMETERIZABLE TYPES<\/a>
REGISTRIES AND IMPORTING<\/a>
CREATING A TYPE LIBRARY<\/a>
DECLARING TYPES<\/a>
USING SPECIO WITH Moose<\/a>
USING SPECIO WITH Moo<\/a>
USING SPECIO WITH OTHER THINGS<\/a>
Moose, MooseX::Types, and Specio<\/a>
OPTIONAL PREREQS<\/a>
WHY THE NAME?<\/a>
LONG-TERM PLANS<\/a>
SUPPORT<\/a>
SOURCE<\/a>
DONATIONS<\/a>
AUTHOR<\/a>
CONTRIBUTORS<\/a>
COPYRIGHT AND LICENSE<\/a> <\/p>\n
\nNAME <\/a> <\/h2>\n
VERSION <\/a> <\/h2>\n
SYNOPSIS <\/a> <\/h2>\n
use Specio::Declare;
use Specio::Library::Builtins;
declare(
‘PositiveInt’,
parent => t(‘Int’),
inline => sub {
$_[0]\u2212>parent\u2212>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’);<\/p>\nDESCRIPTION <\/a> <\/h2>\n
WHAT IS A TYPE? <\/a> <\/h2>\n
BUILTIN TYPES <\/a> <\/h2>\n
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<\/p>\n
Perl\u2019s overloading is horribly broken and doesn\u2019t make much sense at all.<\/p>\nPARAMETERIZABLE TYPES <\/a> <\/h2>\n
The “Maybe” type is a special parameterized type. It allows for either “undef” or a value. All by itself, it is meaningless, since it is equivalent to “Maybe of Item”, which is equivalent to Item. When parameterized, it accepts either an “undef” or the type of its parameter.<\/p>\nREGISTRIES AND IMPORTING <\/a> <\/h2>\n
CREATING A TYPE LIBRARY <\/a> <\/h2>\n
use parent ‘Specio::Exporter’;
use Specio::Declare;
use Specio::Library::Builtins;
declare(
‘Foo’,
parent => t(‘Str’),
where => sub { $_[0] =~ \/foo\/i },
);<\/p>\n
use parent ‘Specio::Exporter’;
use Specio::Declare;
use Specio::Library::Builtins \u2212reexport;
declare( ‘Foo, … );<\/p>\nDECLARING TYPES <\/a> <\/h2>\n
USING SPECIO WITH Moose <\/a> <\/h2>\n
USING SPECIO WITH Moo <\/a> <\/h2>\n
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\u2212Z]+$\/ },
);
coerce(
$ucstr,
from => t(‘Str’),
using => sub { return uc $_[0] },
);
has ucstr => (
is => ‘ro’,
isa => $ucstr,
coerce => $ucstr\u2212>coercion_sub,
);<\/p>\nUSING SPECIO WITH OTHER THINGS <\/a> <\/h2>\n
Moose, MooseX::Types, and Specio <\/a> <\/h2>\n