.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "Specio::Constraint::Simple 3pm"
.TH Specio::Constraint::Simple 3pm "2022-06-21" "perl v5.34.0" "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::Constraint::Simple \- Class for simple (non\-parameterized or specialized) types
.SH "VERSION"
.IX Header "VERSION"
version 0.48
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    my $str = t(\*(AqStr\*(Aq);
\&
\&    print $str\->name; # Str
\&
\&    my $parent = $str\->parent;
\&
\&    if ( $str\->value_is_valid($value) ) { ... }
\&
\&    $str\->validate_or_die($value);
\&
\&    my $code = $str\->inline_coercion_and_check(\*(Aq$_[0]\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class implements simple type constraints, constraints without special
properties or parameterization.
.PP
It does not actually contain any real code of its own. The entire
implementation is provided by the Specio::Constraint::Role::Interface role,
but the primary \s-1API\s0 for type constraints is documented here.
.PP
All other type constraint classes in this distribution implement this \s-1API,\s0
except where otherwise noted.
.SH "API"
.IX Header "API"
This class provides the following methods.
.SS "Specio::Constraint::Simple\->new(...)"
.IX Subsection "Specio::Constraint::Simple->new(...)"
This creates a new constraint. It accepts the following named parameters:
.IP "\(bu" 4
name => \f(CW$name\fR
.Sp
This is the type's name. The name is optional, but if provided it must be a
string.
.IP "\(bu" 4
parent => \f(CW$type\fR
.Sp
The type's parent type. This must be an object which does the
Specio::Constraint::Role::Interface role.
.Sp
This parameter is optional.
.IP "\(bu" 4
constraint => sub { ... }
.Sp
A subroutine reference implementing the constraint. It will be called as a
method on the object and passed a single argument, the value to check.
.Sp
It should return true or false to indicate whether the value matches the
constraint.
.Sp
This parameter is mutually exclusive with \f(CW\*(C`inline_generator\*(C'\fR.
.Sp
You can also pass this option with the key \f(CW\*(C`where\*(C'\fR in the parameter list.
.IP "\(bu" 4
inline_generator => sub { ... }
.Sp
This should be a subroutine reference which returns a string containing a
single term. This code should \fInot\fR end in a semicolon. This code should
implement the constraint.
.Sp
The generator will be called as a method on the constraint with a single
argument. That argument is the name of the variable being coerced, something
like \f(CW\*(Aq$_[0]\*(Aq\fR or \f(CW\*(Aq$var\*(Aq\fR.
.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 $_[0]\->parent\->inline_check( $_[1] )
\&          . \*(Aq and more checking code goes here\*(Aq;
\&  }
.Ve
.Sp
This parameter is mutually exclusive with \f(CW\*(C`constraint\*(C'\fR.
.Sp
You can also pass this option with the key \f(CW\*(C`inline\*(C'\fR in the parameter list.
.IP "\(bu" 4
inline_environment => {}
.Sp
This should be a hash reference of variable names (with sigils) and values for
that variable. The values should be \fIreferences\fR to the values of the
variables.
.Sp
This environment will be used when compiling the constraint as part of a
subroutine. The named variables will be captured as closures in the generated
subroutine, using Eval::Closure.
.Sp
It should be very rare to need to set this in the constructor. It's more likely
that a special type subclass would need to provide values that it generates
internally.
.Sp
If you do set this, you are responsible for generating variable names that
won't clash with anything else in the inlined code.
.Sp
This parameter defaults to an empty hash reference.
.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 subroutine, \fInot as a method\fR,
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.
.Sp
You can also pass this option with the key \f(CW\*(C`message\*(C'\fR in the parameter list.
.IP "\(bu" 4
declared_at => \f(CW$declared_at\fR
.Sp
This parameter must be a Specio::DeclaredAt object.
.Sp
This parameter is required.
.PP
It is possible to create a type without a constraint of its own.
.ie n .SS "$type\->name"
.el .SS "\f(CW$type\fP\->name"
.IX Subsection "$type->name"
Returns the name of the type as it was passed the constructor.
.ie n .SS "$type\->parent"
.el .SS "\f(CW$type\fP\->parent"
.IX Subsection "$type->parent"
Returns the parent type passed to the constructor. If the type has no parent
this returns \f(CW\*(C`undef\*(C'\fR.
.ie n .SS "$type\->is_anon"
.el .SS "\f(CW$type\fP\->is_anon"
.IX Subsection "$type->is_anon"
Returns false for named types, true otherwise.
.ie n .SS "$type\->is_a_type_of($other_type)"
.el .SS "\f(CW$type\fP\->is_a_type_of($other_type)"
.IX Subsection "$type->is_a_type_of($other_type)"
Given a type object, this returns true if the type this method is called on is
a descendant of that type or is that type.
.ie n .SS "$type\->is_same_type_as($other_type)"
.el .SS "\f(CW$type\fP\->is_same_type_as($other_type)"
.IX Subsection "$type->is_same_type_as($other_type)"
Given a type object, this returns true if the type this method is called on is
the same as that type.
.ie n .SS "$type\->coercions"
.el .SS "\f(CW$type\fP\->coercions"
.IX Subsection "$type->coercions"
Returns a list of Specio::Coercion objects which belong to this constraint.
.ie n .SS "$type\->coercion_from_type($name)"
.el .SS "\f(CW$type\fP\->coercion_from_type($name)"
.IX Subsection "$type->coercion_from_type($name)"
Given a type name, this method returns a Specio::Coercion object which
coerces from that type, if such a coercion exists.
.ie n .SS "$type\->validate_or_die($value)"
.el .SS "\f(CW$type\fP\->validate_or_die($value)"
.IX Subsection "$type->validate_or_die($value)"
This method does nothing if the value is valid. If it is not, it throws a
Specio::Exception.
.ie n .SS "$type\->value_is_valid($value)"
.el .SS "\f(CW$type\fP\->value_is_valid($value)"
.IX Subsection "$type->value_is_valid($value)"
Returns true or false depending on whether the \f(CW$value\fR passes the type
constraint.
.ie n .SS "$type\->has_real_constraint"
.el .SS "\f(CW$type\fP\->has_real_constraint"
.IX Subsection "$type->has_real_constraint"
This returns true if the type was created with a \f(CW\*(C`constraint\*(C'\fR or
\&\f(CW\*(C`inline_generator\*(C'\fR parameter. This is used internally to skip type checks for
types that don't actually implement a constraint.
.ie n .SS "$type\->description"
.el .SS "\f(CW$type\fP\->description"
.IX Subsection "$type->description"
This returns a string describing the type. This includes the type's name and
where it was declared, so you end up with something like \f(CW\*(Aqtype named Foo
declared in package My::Lib (lib/My/Lib.pm) at line 42\*(Aq\fR. If the type is
anonymous the name will be \*(L"anonymous type\*(R".
.ie n .SS "$type\->id"
.el .SS "\f(CW$type\fP\->id"
.IX Subsection "$type->id"
This is a unique id for the type as a string. This is useful if you need to
make a hash key based on a type, for example. This should be treated as an
essentially arbitrary and opaque string, and could change at any time in the
future. If you want something human-readable, use the \f(CW\*(C`$type\->description\*(C'\fR
method.
.ie n .SS "$type\->add_coercion($coercion)"
.el .SS "\f(CW$type\fP\->add_coercion($coercion)"
.IX Subsection "$type->add_coercion($coercion)"
This adds a new Specio::Coercion to the type. If the type already has a
coercion from the same type as the new coercion, it will throw an error.
.ie n .SS "$type\->has_coercion_from_type($other_type)"
.el .SS "\f(CW$type\fP\->has_coercion_from_type($other_type)"
.IX Subsection "$type->has_coercion_from_type($other_type)"
This method returns true if the type can coerce from the other type.
.ie n .SS "$type\->coerce_value($value)"
.el .SS "\f(CW$type\fP\->coerce_value($value)"
.IX Subsection "$type->coerce_value($value)"
This attempts to coerce a value into a new value that matches the type. It
checks all of the type's coercions. If it finds one which has a \*(L"from\*(R" type
that accepts the value, it runs the coercion and returns the new value.
.PP
If it cannot find a matching coercion it returns the original value.
.ie n .SS "$type\->inline_coercion_and_check($var)"
.el .SS "\f(CW$type\fP\->inline_coercion_and_check($var)"
.IX Subsection "$type->inline_coercion_and_check($var)"
Given a variable name, this returns a string of code and an environment hash
that implements all of the type's coercions as well as the type check itself.
.PP
This will throw an exception unless both the type and all of its coercions are
inlinable.
.PP
The generated code will throw a Specio::Exception if the type constraint
fails. If the constraint passes, then the generated code returns the (possibly
coerced) value.
.PP
The return value is a two-element list. The first element is the code. The
second is a hash reference containing variables which need to be in scope for
the code to work. This is intended to be passed to Eval::Closure's
\&\f(CW\*(C`eval_closure\*(C'\fR subroutine.
.PP
The returned code is a single \f(CW\*(C`do { }\*(C'\fR block without a terminating semicolon.
.ie n .SS "$type\->inline_assert($var)"
.el .SS "\f(CW$type\fP\->inline_assert($var)"
.IX Subsection "$type->inline_assert($var)"
Given a variable name, this generates code that implements the constraint and
throws an exception if the variable does not pass the constraint.
.PP
The return value is a two-element list. The first element is the code. The
second is a hash reference containing variables which need to be in scope for
the code to work. This is intended to be passed to Eval::Closure's
\&\f(CW\*(C`eval_closure\*(C'\fR subroutine.
.ie n .SS "$type\->inline_check($var)"
.el .SS "\f(CW$type\fP\->inline_check($var)"
.IX Subsection "$type->inline_check($var)"
Given a variable name, this returns a string of code that implements the
constraint. If the type is not inlinable, this method throws an error.
.ie n .SS "$type\->inline_coercion($var)"
.el .SS "\f(CW$type\fP\->inline_coercion($var)"
.IX Subsection "$type->inline_coercion($var)"
Given a variable name, this returns a string of code and an environment hash
that implements all of the type's coercions. \fIIt does not check that the
resulting value is valid.\fR
.PP
This will throw an exception unless all of the type's coercions are inlinable.
.PP
The return value is a two-element list. The first element is the code. The
second is a hash reference containing variables which need to be in scope for
the code to work. This is intended to be passed to Eval::Closure's
\&\f(CW\*(C`eval_closure\*(C'\fR subroutine.
.PP
The returned code is a single \f(CW\*(C`do { }\*(C'\fR block without a terminating semicolon.
.ie n .SS "$type\->\fBinline_environment()\fP"
.el .SS "\f(CW$type\fP\->\fBinline_environment()\fP"
.IX Subsection "$type->inline_environment()"
This returns a hash defining the variables that need to be closed over when
inlining the type. The keys are full variable names like \f(CW\*(Aq$foo\*(Aq\fR or
\&\f(CW\*(Aq@bar\*(Aq\fR. The values are \fIreferences\fR to a variable of the matching type.
.ie n .SS "$type\->coercion_sub"
.el .SS "\f(CW$type\fP\->coercion_sub"
.IX Subsection "$type->coercion_sub"
This method returns a sub ref that takes a single argument and applied all
relevant coercions to it. This sub ref will use Sub::Quote if all the type's
coercions are inlinable.
.PP
This method exists primarily for the benefit of Moo.
.SH "OVERLOADING"
.IX Header "OVERLOADING"
All constraints implement the following overloads:
.SS "Subroutine De-referencing"
.IX Subsection "Subroutine De-referencing"
This is done for the benefit of Moo. The returned subroutine uses
Sub::Quote if the type constraint is inlinable.
.SS "Stringification"
.IX Subsection "Stringification"
For non-anonymous types, this will be the type's name. For anonymous types, a
string like \*(L"_\|_ANON_\|_(Str)\*(R" is generated. However, this string should not be
expected to be stable across releases, so don't use it for things like equality
checks!
.SS "Boolification"
.IX Subsection "Boolification"
This always returns true.
.SS "String Equality (eq)"
.IX Subsection "String Equality (eq)"
This calls \f(CW\*(C`$type\->is_same_type_as($other)\*(C'\fR to compare the two types.
.SH "ROLES"
.IX Header "ROLES"
This role does the Specio::Constraint::Role::Interface and
Specio::Role::Inlinable roles.
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs may be submitted at <https://github.com/houseabsolute/Specio/issues>.
.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 \- 2022 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.