.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Specio::Declare 3"
.TH Specio::Declare 3 "2019-08-14" "perl v5.16.3" "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::Declare \- Specio declaration subroutines
.SH "VERSION"
.IX Header "VERSION"
version 0.44
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& package MyApp::Type::Library;
\&
\& use parent \*(AqSpecio::Exporter\*(Aq;
\&
\& use Specio::Declare;
\& use Specio::Library::Builtins;
\&
\& declare(
\& \*(AqFoo\*(Aq,
\& parent => t(\*(AqStr\*(Aq),
\& where => sub { $_[0] =~ /foo/i },
\& );
\&
\& declare(
\& \*(AqArrayRefOfInt\*(Aq,
\& parent => t( \*(AqArrayRef\*(Aq, of => t(\*(AqInt\*(Aq) ),
\& );
\&
\& my $even = anon(
\& parent => t(\*(AqInt\*(Aq),
\& inline => sub {
\& my $type = shift;
\& my $value_var = shift;
\&
\& return $value_var . \*(Aq % 2 == 0\*(Aq;
\& },
\& );
\&
\& coerce(
\& t(\*(AqArrayRef\*(Aq),
\& from => t(\*(AqFoo\*(Aq),
\& using => sub { [ $_[0] ] },
\& );
\&
\& coerce(
\& $even,
\& from => t(\*(AqInt\*(Aq),
\& using => sub { $_[0] % 2 ? $_[0] + 1 : $_[0] },
\& );
\&
\& # Specio name is DateTime
\& any_isa_type(\*(AqDateTime\*(Aq);
\&
\& # Specio name is DateTimeObject
\& object_isa_type( \*(AqDateTimeObject\*(Aq, class => \*(AqDateTime\*(Aq );
\&
\& any_can_type(
\& \*(AqDuck\*(Aq,
\& methods => [ \*(Aqduck_walk\*(Aq, \*(Aqquack\*(Aq ],
\& );
\&
\& object_can_type(
\& \*(AqDuckObject\*(Aq,
\& methods => [ \*(Aqduck_walk\*(Aq, \*(Aqquack\*(Aq ],
\& );
\&
\& enum(
\& \*(AqColors\*(Aq,
\& values => [qw( blue green red )],
\& );
\&
\& intersection(
\& \*(AqHashRefAndArrayRef\*(Aq,
\& of => [ t(\*(AqHashRef\*(Aq), t(\*(AqArrayRef\*(Aq) ],
\& );
\&
\& union(
\& \*(AqIntOrArrayRef\*(Aq,
\& of => [ t(\*(AqInt\*(Aq), t(\*(AqArrayRef\*(Aq) ],
\& );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package exports a set of type declaration helpers. Importing this package
also causes it to create a \f(CW\*(C`t\*(C'\fR subroutine the caller.
.SH "SUBROUTINES"
.IX Header "SUBROUTINES"
This module exports the following subroutines.
.SS "t('name')"
.IX Subsection "t('name')"
This subroutine lets you access any types you have declared so far, as well as
any types you imported from another type library.
.PP
If you pass an unknown name, it throws an exception.
.SS "declare(...)"
.IX Subsection "declare(...)"
This subroutine declares a named type. The first argument is the type name,
followed by a set of key/value parameters:
.IP "\(bu" 4
parent => \f(CW$type\fR
.Sp
The parent should be another type object. Specifically, it can be anything
which does the Specio::Constraint::Role::Interface role. The parent can be a
named or anonymous type.
.IP "\(bu" 4
where => sub { ... }
.Sp
This is a subroutine which defines the type constraint. It will be passed a
single argument, the value to check, and it should return true or false to
indicate whether or not the value is valid for the type.
.Sp
This parameter is mutually exclusive with the \f(CW\*(C`inline\*(C'\fR parameter.
.IP "\(bu" 4
inline => sub { ... }
.Sp
This is a subroutine that is called to generate inline code to validate the
type. Inlining can be \fImuch\fR faster than simply providing a subroutine with
the \f(CW\*(C`where\*(C'\fR parameter, but is often more complicated to get right.
.Sp
The inline generator is called as a method on the type with one argument. This
argument is a \fIstring\fR containing the variable name to use in the generated
code. Typically this is something like \f(CW\*(Aq$_[0]\*(Aq\fR or \f(CW\*(Aq$value\*(Aq\fR.
.Sp
The inline generator subroutine should return a \fIstring\fR of code representing
a single term, and it \fIshould not\fR be terminated with a semicolon. This
allows the inlined code to be safely included in an \f(CW\*(C`if\*(C'\fR statement, for
example. You can use \f(CW\*(C`do { }\*(C'\fR blocks and ternaries to get everything into one
term. Do not assign to the variable you are testing. This single term should
evaluate to true or false.
.Sp
The inline generator is expected to include code to implement both the current
type and all its parents. Typically, the easiest way to do this is to write a
subroutine something like this:
.Sp
.Vb 3
\& sub {
\& my $self = shift;
\& my $var = shift;
\&
\& return $self\->parent\->inline_check($var)
\& . \*(Aq and more checking code goes here\*(Aq;
\& }
.Ve
.Sp
Or, more concisely:
.Sp
.Vb 1
\& sub { $_[0]\->parent\->inline_check( $_[1] ) . \*(Aqmore code that checks $_[1]\*(Aq }
.Ve
.Sp
The \f(CW\*(C`inline\*(C'\fR parameter is mutually exclusive with the \f(CW\*(C`where\*(C'\fR parameter.
.IP "\(bu" 4
message_generator => sub { ... }
.Sp
A subroutine to generate an error message when the type check fails. The
default message says something like \*(L"Validation failed for type named Int
declared in package Specio::Library::Builtins
(.../Specio/blib/lib/Specio/Library/Builtins.pm) at line 147 in sub named (eval)
with value 1.1\*(R".
.Sp
You can override this to provide something more specific about the way the
type failed.
.Sp
The subroutine you provide will be called as a method on the type with two
arguments. The first is the description of the type (the bit in the message
above that starts with \*(L"type named Int ...\*(R" and ends with \*(L"... in sub named
(eval)\*(R". This description says what the thing is and where it was defined.
.Sp
The second argument is the value that failed the type check, after any
coercions that might have been applied.
.SS "anon(...)"
.IX Subsection "anon(...)"
This subroutine declares an anonymous type. It is identical to \f(CW\*(C`declare\*(C'\fR
except that it expects a list of key/value parameters without a type name as
the first parameter.
.SS "coerce(...)"
.IX Subsection "coerce(...)"
This declares a coercion from one type to another. The first argument should
be an object which does the Specio::Constraint::Role::Interface role. This
can be either a named or anonymous type. This type is the type that the
coercion is \fIto\fR.
.PP
The remaining arguments are key/value parameters:
.IP "\(bu" 4
from => \f(CW$type\fR
.Sp
This must be an object which does the Specio::Constraint::Role::Interface
role. This is type that we are coercing \fIfrom\fR. Again, this can be either a
named or anonymous type.
.IP "\(bu" 4
using => sub { ... }
.Sp
This is a subroutine which defines the type coercion. It will be passed a
single argument, the value to coerce. It should return a new value of the type
this coercion is to.
.Sp
This parameter is mutually exclusive with the \f(CW\*(C`inline\*(C'\fR parameter.
.IP "\(bu" 4
inline => sub { ... }
.Sp
This is a subroutine that is called to generate inline code to perform the
coercion.
.Sp
The inline generator is called as a method on the type with one argument. This
argument is a \fIstring\fR containing the variable name to use in the generated
code. Typically this is something like \f(CW\*(Aq$_[0]\*(Aq\fR or \f(CW\*(Aq$value\*(Aq\fR.
.Sp
The inline generator subroutine should return a \fIstring\fR of code representing
a single term, and it \fIshould not\fR be terminated with a semicolon. This
allows the inlined code to be safely included in an \f(CW\*(C`if\*(C'\fR statement, for
example. You can use \f(CW\*(C`do { }\*(C'\fR blocks and ternaries to get everything into one
term. This single term should evaluate to the new value.
.SH "DECLARATION HELPERS"
.IX Header "DECLARATION HELPERS"
This module also exports some helper subs for declaring certain kinds of types:
.SS "any_isa_type, object_isa_type"
.IX Subsection "any_isa_type, object_isa_type"
The \f(CW\*(C`any_isa_type\*(C'\fR helper creates a type which accepts a class name or
object of the given class. The \f(CW\*(C`object_isa_type\*(C'\fR helper creates a type
which only accepts an object of the given class.
.PP
These subroutines take a type name as the first argument. The remaining
arguments are key/value pairs. Currently this is just the \f(CW\*(C`class\*(C'\fR key, which
should be a class name. This is the class that the type requires.
.PP
The type name argument can be omitted to create an anonymous type.
.PP
You can also pass just a single argument, in which case that will be used as
both the type's name and the class for the constraint to check.
.SS "any_does_type, object_does_type"
.IX Subsection "any_does_type, object_does_type"
The \f(CW\*(C`any_does_type\*(C'\fR helper creates a type which accepts a class name or
object which does the given role. The \f(CW\*(C`object_does_type\*(C'\fR helper creates a
type which only accepts an object which does the given role.
.PP
These subroutines take a type name as the first argument. The remaining
arguments are key/value pairs. Currently this is just the \f(CW\*(C`role\*(C'\fR key, which
should be a role name. This is the class that the type requires.
.PP
This should just work (I hope) with roles created by Moose, Mouse, and
Moo (using Role::Tiny).
.PP
The type name argument can be omitted to create an anonymous type.
.PP
You can also pass just a single argument, in which case that will be used as
both the type's name and the role for the constraint to check.
.SS "any_can_type, object_can_type"
.IX Subsection "any_can_type, object_can_type"
The \f(CW\*(C`any_can_type\*(C'\fR helper creates a type which accepts a class name or
object with the given methods. The \f(CW\*(C`object_can_type\*(C'\fR helper creates a type
which only accepts an object with the given methods.
.PP
These subroutines take a type name as the first argument. The remaining
arguments are key/value pairs. Currently this is just the \f(CW\*(C`methods\*(C'\fR key,
which can be either a string or array reference of strings. These strings are
the required methods for the type.
.PP
The type name argument can be omitted to create an anonymous type.
.SS "enum"
.IX Subsection "enum"
This creates a type which accepts a string matching a given list of acceptable
values.
.PP
The first argument is the type name. The remaining arguments are key/value
pairs. Currently this is just the \f(CW\*(C`values\*(C'\fR key. This should an array
reference of acceptable string values.
.PP
The type name argument can be omitted to create an anonymous type.
.SS "intersection"
.IX Subsection "intersection"
This creates a type which is the intersection of two or more other types. A
union only accepts values which match all of its underlying types.
.PP
The first argument is the type name. The remaining arguments are key/value
pairs. Currently this is just the \f(CW\*(C`of\*(C'\fR key. This should an array
reference of types.
.PP
The type name argument can be omitted to create an anonymous type.
.SS "union"
.IX Subsection "union"
This creates a type which is the union of two or more other types. A union
accepts any of its underlying types.
.PP
The first argument is the type name. The remaining arguments are key/value
pairs. Currently this is just the \f(CW\*(C`of\*(C'\fR key. This should an array
reference of types.
.PP
The type name argument can be omitted to create an anonymous type.
.SH "PARAMETERIZED TYPES"
.IX Header "PARAMETERIZED TYPES"
You can create a parameterized type by calling \f(CW\*(C`t\*(C'\fR with additional
parameters, like this:
.PP
.Vb 1
\& my $arrayref_of_int = t( \*(AqArrayRef\*(Aq, of => t(\*(AqInt\*(Aq) );
\&
\& my $arrayref_of_hashref_of_int = t(
\& \*(AqArrayRef\*(Aq,
\& of => t(
\& \*(AqHashRef\*(Aq,
\& of => t(\*(AqInt\*(Aq),
\& ),
\& );
.Ve
.PP
The \f(CW\*(C`t\*(C'\fR subroutine assumes that if it receives more than one argument, it
should look up the named type and call \f(CW\*(C`$type\->parameterize(...)\*(C'\fR with
the additional arguments.
.PP
If the named type cannot be parameterized, it throws an error.
.PP
You can also call \f(CW\*(C`$type\->parameterize\*(C'\fR directly if needed. See
Specio::Constraint::Parameterizable for details.
.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 \- 2019 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.