Mouse:...raints(3pm)

🎀 NAME 🎀

Mouse::Util::TypeConstraints — the type constraint system for Mouse. It’s the 3pm manual page, filed under User Contributed Perl Documentation, and bestie, we’re gonna get through it together 💖

---

🌸 VERSION 🌸

This document describes Mouse version v2.6.2 — noted, bestie 💅

---

✨ SYNOPSIS ✨

Okay so here’s the whole vibe in code form, copy-paste exact:

use Mouse::Util::TypeConstraints;

subtype 'Natural'
    => as 'Int'
    => where { $_ > 0 };

subtype 'NaturalLessThanTen'
    => as 'Natural'
    => where { $_ < 10 }
    => message { "This number ($_) is not less than ten!" };

coerce 'Num'
    => from 'Str'
      => via { 0+$_ };

enum 'RGBColors' => qw(red green blue);

no Mouse::Util::TypeConstraints;

---

🦋 DESCRIPTION 🦋

This module gives Mouse the ability to create custom type constraints that you can use in attribute definition. That’s the whole point, and it’s lowkey iconic 💖

🚨 Important Caveat 🚨

This is NOT a type system for Perl 5. These are type constraints, and they are not used by Mouse unless you tell it to. No type inference is performed, expressions are not typed, etc. etc. etc. — like, do not expect magic where there is no magic, bestie 😭

A type constraint is at heart a small “check if a value is valid” function. A constraint can be associated with an attribute. This simplifies parameter validation, and makes your code clearer to read, because you can refer to constraints by name. It’s giving “organization but make it cute” ✨

🙈 Slightly Less Important Caveat 🙈

It is always a good idea to quote your type names.

This prevents Perl from trying to execute the call as an indirect object call. This can be an issue when you have a subtype with the same name as a valid class.

For instance:

subtype DateTime => as Object => where { $_->isa('DateTime') };

will just work, while this:

use DateTime;
subtype DateTime => as Object => where { $_->isa('DateTime') };

will fail silently and cause many headaches. The simple way to solve this, as well as future proof your subtypes from classes which have yet to have been created, is to quote the type name:

use DateTime;
subtype 'DateTime' => as 'Object' => where { $_->isa('DateTime') };

Quote the name. Protect your peace. Periodt 💅

👑 Default Type Constraints 👑

This module also provides a simple hierarchy for Perl 5 types, here is that hierarchy represented visually:

Any
 Item
     Bool
     Maybe[`a]
     Undef
     Defined
         Value
             Str
                 Num
                     Int
             ClassName
             RoleName
         Ref
             ScalarRef
             ArrayRef[`a]
             HashRef[`a]
             CodeRef
             RegexpRef
             GlobRef
                 FileHandle
             Object

NOTE: Any type followed by a type parameter "[a]"` can be parameterized, this means you can say:

ArrayRef[Int]    # an array of integers
HashRef[CodeRef] # a hash of str to CODE ref mappings
Maybe[Str]       # value may be a string, may be undefined

If Mouse finds a name in brackets that it does not recognize as an existing type, it assumes that this is a class name, for example "ArrayRef[DateTime]".

NOTE: The "Undef" type constraint for the most part works correctly now, but edge cases may still exist, please use it sparingly.

NOTE: The "ClassName" type constraint does a complex package existence check. This means that your class must be loaded for this type constraint to pass.

NOTE: The "RoleName" constraint checks a string is a package name which is a role, like 'MyApp::Role::Comparable'. The "Role" constraint checks that an object does the named role.

🎀 Type Constraint Naming 🎀

Type name declared via this module can only contain alphanumeric characters, colons (:), and periods (.).

Since the types created by this module are global, it is suggested that you namespace your types just as you would namespace your modules. So instead of creating a Color type for your My::Graphics module, you would call the type My::Graphics::Types::Color instead.

🌈 Use with Other Constraint Modules 🌈

This module can play nicely with other constraint modules with some slight tweaking. The "where" clause in types is expected to be a "CODE" reference which checks it’s first argument and returns a boolean. Since most constraint modules work in a similar way, it should be simple to adapt them to work with Mouse.

For instance, this is how you could use it with Declare::Constraints::Simple to declare a completely new type:

type 'HashOfArrayOfObjects',
    {
    where => IsHashRef(
        -keys   => HasLength,
        -values => IsArrayRef(IsObject)
    )
};

Here is an example of using Test::Deep and it’s non-test related "eq_deeply" function:

type 'ArrayOfHashOfBarsAndRandomNumbers'
    => where {
        eq_deeply($_,
            array_each(subhashof({
                bar           => isa('Bar'),
                random_number => ignore()
            })))
      };

---

💜 METHODS 💜

• list_all_builtin_type_constraints -> (Names) — Returns the names of builtin type constraints.
• list_all_type_constraints -> (Names) — Returns the names of all the type constraints.

---

🧚 FUNCTIONS 🧚

Here are the exact call shapes, bestie — no extra lore on this page, just the signatures:

• type $name => where { } ... -> Mouse::Meta::TypeConstraint
• subtype $name => as $parent => where { } ... -> Mouse::Meta::TypeConstraint
• subtype as $parent => where { } ... -> Mouse::Meta::TypeConstraint
• class_type ($class, ?$options) -> Mouse::Meta::TypeConstraint
• role_type ($role, ?$options) -> Mouse::Meta::TypeConstraint
• duck_type($name, @methods | \@methods) -> Mouse::Meta::TypeConstraint
• duck_type(\@methods) -> Mouse::Meta::TypeConstraint
• enum($name, @values | \@values) -> Mouse::Meta::TypeConstraint
• enum (\@values) -> Mouse::Meta::TypeConstraint
• coerce $type => from $another_type, via { }, ...
• find_type_constraint(Type) -> Mouse::Meta::TypeConstraint

---

🫶 THANKS 🫶

Much of this documentation was taken from "Moose::Util::TypeConstraints" — big thanks to the source material, fr fr 💖

---

⭐ SEE ALSO ⭐

Moose::Util::TypeConstraints

---

Okay that’s the whole page, bestie! This was the Mouse:...raints(3pm) manual page from perl v5.42.2, dated 2026-04-21. Mwah, go forth and constrain your types 💅🎀