1Specio::Constraint::SimUpsleer(3C)ontributed Perl DocumeSnpteactiioo:n:Constraint::Simple(3)
2
6 Specio::Constraint::Simple - Class for simple (non-parameterized or
7 specialized) types
8
10 version 0.48
11
13 my $str = t('Str');
14 print $str->name; # Str
16 my $parent = $str->parent;
18 if ( $str->value_is_valid($value) ) { ... }
20 $str->validate_or_die($value);
22 my $code = $str->inline_coercion_and_check('$_[0]');
24
26 This class implements simple type constraints, constraints without
27 special properties or parameterization.
28 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 All other type constraint classes in this distribution implement this
34 API, except where otherwise noted.
35
37 This class provides the following methods.
38 Specio::Constraint::Simple->new(...)
40 This creates a new constraint. It accepts the following named
41 parameters:
42 • name => $name
44 This is the type's name. The name is optional, but if provided it
46 must be a string.
47 • parent => $type
49 The type's parent type. This must be an object which does the
51 Specio::Constraint::Role::Interface role.
52 This parameter is optional.
54 • constraint => sub { ... }
56 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 It should return true or false to indicate whether the value
62 matches the constraint.
63 This parameter is mutually exclusive with "inline_generator".
65 You can also pass this option with the key "where" in the parameter
67 list.
68 • inline_generator => sub { ... }
70 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 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 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 sub {
84 my $self = shift;
85 my $var = shift;
86 return $_[0]->parent->inline_check( $_[1] )
88 . ' and more checking code goes here';
89 }
90 This parameter is mutually exclusive with "constraint".
92 You can also pass this option with the key "inline" in the
94 parameter list.
95 • inline_environment => {}
97 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 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 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 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 This parameter defaults to an empty hash reference.
114 • message_generator => sub { ... }
116 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 You can override this to provide something more specific about the
124 way the type failed.
125 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 The second argument is the value that failed the type check, after
133 any coercions that might have been applied.
134 You can also pass this option with the key "message" in the
136 parameter list.
137 • declared_at => $declared_at
139 This parameter must be a Specio::DeclaredAt object.
141 This parameter is required.
143 It is possible to create a type without a constraint of its own.
145 $type->name
147 Returns the name of the type as it was passed the constructor.
148 $type->parent
150 Returns the parent type passed to the constructor. If the type has no
151 parent this returns "undef".
152 $type->is_anon
154 Returns false for named types, true otherwise.
155 $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 $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 $type->coercions
165 Returns a list of Specio::Coercion objects which belong to this
166 constraint.
167 $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 $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 $type->value_is_valid($value)
177 Returns true or false depending on whether the $value passes the type
178 constraint.
179 $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 $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 $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 $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 $type->has_coercion_from_type($other_type)
204 This method returns true if the type can coerce from the other type.
205 $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 If it cannot find a matching coercion it returns the original value.
213 $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 This will throw an exception unless both the type and all of its
220 coercions are inlinable.
221 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 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 The returned code is a single "do { }" block without a terminating
232 semicolon.
233 $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 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 $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 $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 This will throw an exception unless all of the type's coercions are
255 inlinable.
256 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 The returned code is a single "do { }" block without a terminating
263 semicolon.
264 $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 $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 This method exists primarily for the benefit of Moo.
276
278 All constraints implement the following overloads:
279 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 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 Boolification
291 This always returns true.
292 String Equality (eq)
294 This calls "$type->is_same_type_as($other)" to compare the two types.
295
297 This role does the Specio::Constraint::Role::Interface and
298 Specio::Role::Inlinable roles.
299
301 Bugs may be submitted at
302 <https://github.com/houseabsolute/Specio/issues>.
303
305 The source code repository for Specio can be found at
306 <https://github.com/houseabsolute/Specio>.
307
309 Dave Rolsky <autarch@urth.org>
310
312 This software is Copyright (c) 2012 - 2022 by Dave Rolsky.
313 This is free software, licensed under:
315 The Artistic License 2.0 (GPL Compatible)
317 The full text of the license can be found in the LICENSE file included
319 with this distribution.
320perl v5.38.0 2023-07-21 Specio::Constraint::Simple(3)