1Specio::Constraint::SimUpsleer(3C)ontributed Perl DocumeSnpteactiioo:n:Constraint::Simple(3)
2
3
4

NAME

6       Specio::Constraint::Simple - Class for simple (non-parameterized or
7       specialized) types
8

VERSION

10       version 0.48
11

SYNOPSIS

13           my $str = t('Str');
14
15           print $str->name; # Str
16
17           my $parent = $str->parent;
18
19           if ( $str->value_is_valid($value) ) { ... }
20
21           $str->validate_or_die($value);
22
23           my $code = $str->inline_coercion_and_check('$_[0]');
24

DESCRIPTION

26       This class implements simple type constraints, constraints without
27       special properties or parameterization.
28
29       It does not actually contain any real code of its own. The entire
30       implementation is provided by the Specio::Constraint::Role::Interface
31       role, but the primary API for type constraints is documented here.
32
33       All other type constraint classes in this distribution implement this
34       API, except where otherwise noted.
35

API

37       This class provides the following methods.
38
39   Specio::Constraint::Simple->new(...)
40       This creates a new constraint. It accepts the following named
41       parameters:
42
43       •   name => $name
44
45           This is the type's name. The name is optional, but if provided it
46           must be a string.
47
48       •   parent => $type
49
50           The type's parent type. This must be an object which does the
51           Specio::Constraint::Role::Interface role.
52
53           This parameter is optional.
54
55       •   constraint => sub { ... }
56
57           A subroutine reference implementing the constraint. It will be
58           called as a method on the object and passed a single argument, the
59           value to check.
60
61           It should return true or false to indicate whether the value
62           matches the constraint.
63
64           This parameter is mutually exclusive with "inline_generator".
65
66           You can also pass this option with the key "where" in the parameter
67           list.
68
69       •   inline_generator => sub { ... }
70
71           This should be a subroutine reference which returns a string
72           containing a single term. This code should not end in a semicolon.
73           This code should implement the constraint.
74
75           The generator will be called as a method on the constraint with a
76           single argument. That argument is the name of the variable being
77           coerced, something like '$_[0]' or '$var'.
78
79           The inline generator is expected to include code to implement both
80           the current type and all its parents. Typically, the easiest way to
81           do this is to write a subroutine something like this:
82
83             sub {
84                 my $self = shift;
85                 my $var  = shift;
86
87                 return $_[0]->parent->inline_check( $_[1] )
88                     . ' and more checking code goes here';
89             }
90
91           This parameter is mutually exclusive with "constraint".
92
93           You can also pass this option with the key "inline" in the
94           parameter list.
95
96       •   inline_environment => {}
97
98           This should be a hash reference of variable names (with sigils) and
99           values for that variable. The values should be references to the
100           values of the variables.
101
102           This environment will be used when compiling the constraint as part
103           of a subroutine. The named variables will be captured as closures
104           in the generated subroutine, using Eval::Closure.
105
106           It should be very rare to need to set this in the constructor. It's
107           more likely that a special type subclass would need to provide
108           values that it generates internally.
109
110           If you do set this, you are responsible for generating variable
111           names that won't clash with anything else in the inlined code.
112
113           This parameter defaults to an empty hash reference.
114
115       •   message_generator => sub { ... }
116
117           A subroutine to generate an error message when the type check
118           fails. The default message says something like "Validation failed
119           for type named Int declared in package Specio::Library::Builtins
120           (.../Specio/blib/lib/Specio/Library/Builtins.pm) at line 147 in sub
121           named (eval) with value 1.1".
122
123           You can override this to provide something more specific about the
124           way the type failed.
125
126           The subroutine you provide will be called as a subroutine, not as a
127           method, with two arguments. The first is the description of the
128           type (the bit in the message above that starts with "type named Int
129           ..." and ends with "... in sub named (eval)". This description says
130           what the thing is and where it was defined.
131
132           The second argument is the value that failed the type check, after
133           any coercions that might have been applied.
134
135           You can also pass this option with the key "message" in the
136           parameter list.
137
138       •   declared_at => $declared_at
139
140           This parameter must be a Specio::DeclaredAt object.
141
142           This parameter is required.
143
144       It is possible to create a type without a constraint of its own.
145
146   $type->name
147       Returns the name of the type as it was passed the constructor.
148
149   $type->parent
150       Returns the parent type passed to the constructor. If the type has no
151       parent this returns "undef".
152
153   $type->is_anon
154       Returns false for named types, true otherwise.
155
156   $type->is_a_type_of($other_type)
157       Given a type object, this returns true if the type this method is
158       called on is a descendant of that type or is that type.
159
160   $type->is_same_type_as($other_type)
161       Given a type object, this returns true if the type this method is
162       called on is the same as that type.
163
164   $type->coercions
165       Returns a list of Specio::Coercion objects which belong to this
166       constraint.
167
168   $type->coercion_from_type($name)
169       Given a type name, this method returns a Specio::Coercion object which
170       coerces from that type, if such a coercion exists.
171
172   $type->validate_or_die($value)
173       This method does nothing if the value is valid. If it is not, it throws
174       a Specio::Exception.
175
176   $type->value_is_valid($value)
177       Returns true or false depending on whether the $value passes the type
178       constraint.
179
180   $type->has_real_constraint
181       This returns true if the type was created with a "constraint" or
182       "inline_generator" parameter. This is used internally to skip type
183       checks for types that don't actually implement a constraint.
184
185   $type->description
186       This returns a string describing the type. This includes the type's
187       name and where it was declared, so you end up with something like 'type
188       named Foo declared in package My::Lib (lib/My/Lib.pm) at line 42'. If
189       the type is anonymous the name will be "anonymous type".
190
191   $type->id
192       This is a unique id for the type as a string. This is useful if you
193       need to make a hash key based on a type, for example. This should be
194       treated as an essentially arbitrary and opaque string, and could change
195       at any time in the future. If you want something human-readable, use
196       the "$type->description" method.
197
198   $type->add_coercion($coercion)
199       This adds a new Specio::Coercion to the type. If the type already has a
200       coercion from the same type as the new coercion, it will throw an
201       error.
202
203   $type->has_coercion_from_type($other_type)
204       This method returns true if the type can coerce from the other type.
205
206   $type->coerce_value($value)
207       This attempts to coerce a value into a new value that matches the type.
208       It checks all of the type's coercions. If it finds one which has a
209       "from" type that accepts the value, it runs the coercion and returns
210       the new value.
211
212       If it cannot find a matching coercion it returns the original value.
213
214   $type->inline_coercion_and_check($var)
215       Given a variable name, this returns a string of code and an environment
216       hash that implements all of the type's coercions as well as the type
217       check itself.
218
219       This will throw an exception unless both the type and all of its
220       coercions are inlinable.
221
222       The generated code will throw a Specio::Exception if the type
223       constraint fails. If the constraint passes, then the generated code
224       returns the (possibly coerced) value.
225
226       The return value is a two-element list. The first element is the code.
227       The second is a hash reference containing variables which need to be in
228       scope for the code to work. This is intended to be passed to
229       Eval::Closure's "eval_closure" subroutine.
230
231       The returned code is a single "do { }" block without a terminating
232       semicolon.
233
234   $type->inline_assert($var)
235       Given a variable name, this generates code that implements the
236       constraint and throws an exception if the variable does not pass the
237       constraint.
238
239       The return value is a two-element list. The first element is the code.
240       The second is a hash reference containing variables which need to be in
241       scope for the code to work. This is intended to be passed to
242       Eval::Closure's "eval_closure" subroutine.
243
244   $type->inline_check($var)
245       Given a variable name, this returns a string of code that implements
246       the constraint. If the type is not inlinable, this method throws an
247       error.
248
249   $type->inline_coercion($var)
250       Given a variable name, this returns a string of code and an environment
251       hash that implements all of the type's coercions. It does not check
252       that the resulting value is valid.
253
254       This will throw an exception unless all of the type's coercions are
255       inlinable.
256
257       The return value is a two-element list. The first element is the code.
258       The second is a hash reference containing variables which need to be in
259       scope for the code to work. This is intended to be passed to
260       Eval::Closure's "eval_closure" subroutine.
261
262       The returned code is a single "do { }" block without a terminating
263       semicolon.
264
265   $type->inline_environment()
266       This returns a hash defining the variables that need to be closed over
267       when inlining the type. The keys are full variable names like '$foo' or
268       '@bar'. The values are references to a variable of the matching type.
269
270   $type->coercion_sub
271       This method returns a sub ref that takes a single argument and applied
272       all relevant coercions to it. This sub ref will use Sub::Quote if all
273       the type's coercions are inlinable.
274
275       This method exists primarily for the benefit of Moo.
276

OVERLOADING

278       All constraints implement the following overloads:
279
280   Subroutine De-referencing
281       This is done for the benefit of Moo. The returned subroutine uses
282       Sub::Quote if the type constraint is inlinable.
283
284   Stringification
285       For non-anonymous types, this will be the type's name. For anonymous
286       types, a string like "__ANON__(Str)" is generated. However, this string
287       should not be expected to be stable across releases, so don't use it
288       for things like equality checks!
289
290   Boolification
291       This always returns true.
292
293   String Equality (eq)
294       This calls "$type->is_same_type_as($other)" to compare the two types.
295

ROLES

297       This role does the Specio::Constraint::Role::Interface and
298       Specio::Role::Inlinable roles.
299

SUPPORT

301       Bugs may be submitted at
302       <https://github.com/houseabsolute/Specio/issues>.
303

SOURCE

305       The source code repository for Specio can be found at
306       <https://github.com/houseabsolute/Specio>.
307

AUTHOR

309       Dave Rolsky <autarch@urth.org>
310
312       This software is Copyright (c) 2012 - 2022 by Dave Rolsky.
313
314       This is free software, licensed under:
315
316         The Artistic License 2.0 (GPL Compatible)
317
318       The full text of the license can be found in the LICENSE file included
319       with this distribution.
320
321
322
323perl v5.38.0                      2023-07-21     Specio::Constraint::Simple(3)
Impressum