Type::Coercion(3)

📦

version 2.010001 · 14 versions

💖 NAME 💖

Type::Coercion — bestie, it's literally a whole set of coercions aimed at one specific target type constraint. That's the whole vibe. It's Type::Coercion(3), third section of the manual, and she's here to convert your values for you. 💅

✨ STATUS ✨

This module is covered by the Type-Tiny stability policy. So like… she's stable, she's not going anywhere, we love that for her. 🫶

🌸 DESCRIPTION 🌸

🎀 Constructors

new(%attributes) — the classic Moose-style constructor function, doing exactly what you'd expect a constructor to do. ✨
add($c1, $c2) — okay so this one takes two existing Type::Coercion objects and makes a brand-new Type::Coercion out of them. It's giving "collab".

🦋 Attributes

Attributes are named values you can pass to the constructor, and every single one of them has a matching reader method. For example:

my $c = Type::Coercion->new( type_constraint => Int );
my $t = $c->type_constraint;  # Int

💜 Important attributes

These are the ones you're most likely to actually want to pass in when you're building your own type coercions, and the ones you'll be most interested in reading back out when you're handling coercion objects. Main character attributes, no cap.

type_constraint — a weak reference to the target type constraint, aka the type constraint that the output of your coercion coderefs is expected to conform to. She's the goal. 👑
type_coercion_map — an arrayref of source-type/code pairs. Yeah. A map. Of pairs. 🗺️
frozen — boolean, and the default is false. If a coercion is frozen, you cannot call add_type_coercions on it. She's locked in, literally. 💀
name — a name for the coercion. It has to follow certain naming rules: it must begin with an uppercase letter, and then keep going using only letters, digits 0-9 and underscores. It's optional; if you don't supply one, you get an anonymous coercion. Mysterious. ✨
display_name — the name shown for the coercion when it gets stringified. These ones don't have to follow any naming rules at all, go feral bestie. Optional; a default name will be calculated from the name.
library — the package name of the type library this coercion is associated with. Optional. It's informational only, so heads up: setting this attribute does not install the coercion into the package. It's just a label, not a spell. 🧚

These next ones get used for parameterized coercions, but they're not fully documented because they might change in the near future. So like, she's a work in progress, don't get too attached. 🙈

coercion_generator
parameters
parameterized_from

⭐ Lazy generated attributes

These ones you should not usually pass to the constructor. Unless you're doing something especially unusual, just let the default lazily-built return values do their thing. She'll handle it. 💅

compiled_coercion — a coderef to coerce a value ($_[0]).

The whole point of this attribute is that you should not set it — rely on the lazily-built default instead. Type::Coerce will usually generate a pretty fast coderef, inlining all the type constraint checks and everything. She's optimized. 🔥

moose_coercion — a Moose::Meta::TypeCoercion object equivalent to this one. Do not set this manually, okay? Rely on the default built one. 🫶

👑 Methods

🍓 Predicate methods

These return booleans telling you stuff about the coercion, and each one is tightly associated with a particular attribute. (Go look at "Attributes" if you need a refresher.)

has_type_constraint, has_library — simple Moose-style predicate methods that indicate the presence or absence of an attribute. Present or not present, that's it. ✅
is_anon — returns true iff the coercion does not have a name. Anonymous queen. 🙈

The following predicates are used for parameterized coercions, but are not fully documented because they may change in the near future:

has_coercion_generator
has_parameters
is_parameterizable
is_parameterized

💫 Coercion

These are the methods that actually coerce values to a type constraint. The moment you've been waiting for.

coerce($value) — coerce the value to the target type.

Returns the coerced value, or the original value if no coercion was possible. She tries her best, and if she can't, she hands it back unchanged. 😭

check_coerce($value) — coerces the value to the target type, and checks that the coerced value passes the target type constraint.

Returns the coerced value if it passes the target type constraint, or undef if it doesn't. Vibe check passed? Slay. Vibe check failed? undef.

assert_coerce($value) — coerces the value to the target type, and throws an exception if the result does not validate against the target type constraint.

Returns the coerced value.

But here's the tea: if this type coercion does not have an associated target type constraint, then it will not attempt to validate against it, and will always return the coerced value, never throwing an exception (in theory). In theory. 💀

🧚 Coercion code definition methods

Every single one of these returns $self, so they're all suitable for chaining. Chain them, bestie. It's giving fluent interface. ✨

add_type_coercions($type1, $code1, ...) — takes one or more pairs of Type::Tiny constraints and coercion code, creating an ordered list of source types and coercion codes.

Coercion codes can be expressed as either a string of Perl code (this includes objects which overload stringification), or a coderef (or an object that overloads coderefification). In either case, the value to be coerced is $_.

add_type_coercions($coercion_object) also works, and you can use it to copy coercions from another type constraint:

$type->coercion->add_type_coercions($othertype->coercion)->freeze;

freeze — sets the frozen attribute to true. Type::Tiny calls this automatically sometimes, so like, don't be surprised. 🥶
i_really_want_to_unfreeze — if you really want to unfreeze a coercion, call this method.

Don't call this method. It will potentially lead to subtle bugs. 😭

This method is considered unstable; future versions of Type::Tiny may alter its behaviour (e.g. to throw an exception if it has been detected that unfreezing this particular coercion will cause bugs). You have been warned, bestie. 💀

🎀 Parameterization

The following method is used for parameterized coercions, but is not fully documented because it may change in the near future:

parameterize(@params)

🔥 Type coercion introspection methods

These let you figure out how a coercion relates to type constraints. Investigative journalism, but for types.

has_coercion_for_type($source_type) — returns true iff this coercion has a coercion from the source type.

Returns the special string "0 but true" if no coercion should actually be necessary for this type. (For example, if a coercion coerces to a theoretical "Number" type, there is probably no coercion necessary for values that already conform to the "Integer" type.) Yes, "0 but true" — she's a real Perl string, she's iconic, she's confusing, she's everything. 💅

has_coercion_for_value($value) — returns true iff the value could be coerced by this coercion.

Returns the special string "0 but true" if no coercion would actually be necessary for this value, because it already meets the target type constraint. She's already perfect, no coercion needed. ✨

The type_constraint attribute provides a type constraint object for the target type constraint of the coercion. See "Attributes".

🌈 Inlining methods

These generate strings of Perl code which you can paste into stringy evaluated subs to perform type coercions. Stringy eval, yes, we're doing that, don't look at me.

can_be_inlined — returns true iff the coercion can be inlined. 🫶
inline_coercion($varname) — much like inline_coerce from Type::Tiny. Same energy, different name.

💜 Other methods

qualified_name — for non-anonymous coercions that have a library, returns a qualified MyLib::MyCoercion sort of name. Otherwise, returns the same as name. Simple as that.
isa($class), can($method), AUTOLOAD(@args) — if Moose is loaded, then the combination of these methods is used to mock a Moose::Meta::TypeCoercion. Fake it till you make it. 🎭

The following methods exist for Moose/Mouse compatibility, but do not do anything useful:

compile_type_coercion
meta

🦋 Overloading

Boolification is overloaded to always return true. She's always true. Always. 👑
Coderefification is overloaded to call coerce.
On Perl 5.10.1 and above, smart match is overloaded to call has_coercion_for_value.

Previous versions of Type::Coercion would overload the "+" operator to call add. Support for this was dropped after 0.040. Pour one out. 😭

💀 DIAGNOSTICS 💀

Attempt to add coercion code to a Type::Coercion which has been frozen

Type::Tiny type constraints are designed as immutable objects. Once you've created a constraint, rather than modifying it you generally create child constraints to do what you need.

Type::Coercion objects, on the other hand, are mutable. Coercion routines can be added at any time during the object's lifetime.

Sometimes Type::Tiny needs to freeze a Type::Coercion object to prevent this. In Moose and Mouse code this is likely to happen as soon as you use a type constraint in an attribute.

Workarounds:

Define as many of your coercions as possible within type libraries, not within the code that uses the type libraries. The type library will be evaluated relatively early, likely before there is any reason to freeze a coercion.
If you do need to add coercions to a type within application code outside the type library, instead create a subtype and add coercions to that. The plus_coercions method provided by Type::Tiny should make this simple. 🫶

🙈 BUGS 🙈

Please report any bugs to <https://github.com/tobyink/p5-type-tiny/issues>. She wants to hear from you, bestie. 💖

⭐ SEE ALSO ⭐

Type::Tiny::Manual.
Type::Tiny, Type::Library, Type::Utils, Types::Standard.
Type::Coercion::Union.
Moose::Meta::TypeCoercion.

💅 AUTHOR 💅

Toby Inkster <tobyink@cpan.org>. The icon. The legend. 🫶

🎀 COPYRIGHT AND LICENCE 🎀

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Free software, slay. ✨

🌸 DISCLAIMER OF WARRANTIES 🌸

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. No warranty, no promises, no cap. 😭

And that's the whole page, bestie — this was perl v5.42.0, dated 2026-01-17, for Type::Coercion(3). Go forth and coerce responsibly. 💖✨🦋

📦 where this page comes from

fedora 44: perl-Type-Tiny 2.010001-2.fc44 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms