Data::Constraint(3)

✨ Data::Constraint ✨

okay bestie, gather round, because we're about to talk about Data::Constraint — yes, the one from the User Contributed Perl Documentation section of your perldoc, and yes, it's giving prototypical value checking 🦋

---

💖 NAME 💖

Data::Constraint — it does prototypical value checking. that's the whole vibe. one condition, one value, yes or no, periodt. 💅

---

🌸 SYNOPSIS 🌸

use Data::Constraint;

my $constraint = Data::Constraint->add_constraint(
        'name_of_condition',
        run         => sub { $_[1] =~ /Perl/ },
        description => "String should have 'Perl' in it";
        );

if( $constraint->check( 'Java' ) )
        {
        ...
        }

like... you make a constraint, you check a thing against it, you move on with your life. iconic behavior fr fr. ✨

---

🎀 DESCRIPTION 🎀

so a constraint is just some sort of condition on a datum, okay? this module checks one condition against one value at a time, and the thing doing the checking is what we call the "constraint". a constraint returns true or false and that's literally it. no side effects. it does not change program flow. it minds its own business, like a well-behaved bestie. 🫶 let whatever called the constraint figure out what to do with the answer. we want something that says "yes" or "no" — and yeah, we'll get into why that needs a fancy module later, hold on.

for instance, the constraint may state that the value has to be a number. the condition may be something that makes sure the value doesn't have non-digits:

$value =~ /^\d+\z/

and the value may have additional constraints too, like a lower limit:

$value > $minimum

ngl, even though constraints were designed as a single condition, you might wanna create constraints that check more than one thing:

$value > $minimum and $value < $maximum

so here's the tea ☕ in the previous examples, we could tell exactly what was wrong with the value if the return value was false: the value didn't satisfy its single condition. if it was supposed to be all digits and wasn't, then it had non-digits. if it was supposed to be greater than the minimum value but wasn't, it was less than (or equal to) the minimal value. but with more than one condition, like that last example? i cannot tell which one failed. i might be able to say the value is out of range, but i think it's nicer to know whether the value should have been larger or smaller so i can pass that info on to the user. having said that — i give you enough rope to do what you wish. 🙈

🧚 Why I need a fancy, high-falutin' module

this module is a sub-class of Class::Prototyped. in brief, that means constraints are class-objects even if they don't look like they are. each constraint is a self-contained class, and i can modify a constraint by adding data and behaviour without affecting any of the other constraints. i can also make a list of constraints that i store for later use — also known as "delayed" execution. ⏳

several data may need the same conditions, so they can share the same constraint. other data that need different constraints can get their own, or modify copies of ones that exist. slay.

i can also associate several constraints with some data, and each one has its own constraint. in the compelling case for this module, i needed to generate different warnings for different failures. that's the moment. that's the plot. 👑

💫 Interacting with a constraint

i can get a constraint object by asking for it:

my $constraint = Data::Constraint->get_by_name( $name );

if no constraint has that name, i get back the default constraint which always returns true. or should it be false? 🤔 i guess that depends on what you are doing. (iykyk)

if i don't know which constraints exist, i can get all the names. the names are just simple strings, so they have no magic. maybe this should be a hash so you can immediately use the value of the key you want:

my @names = Data::Constraint->get_all_names;

once i have the constraint, i give it a value to check:

$constraint->check( $value );

and bestie, i can do this all in one step:

Data::Constraint->get_by_name( $name )->check( $value );

🌈 Predefined constraints

i previously had some pre-loaded contraints ("defined", "ordinal", and "test") but that got in the way of things that didn't want them. 😭 you can still find them defined in the test files though.

💜 Adding a new constraint

add a new constraint with the class method add_constraint. the first argument is the name you want to give the constraint. the rest of the arguments are optional, although i need to add a "run" key if i want the constraint to do anything useful: its value should be something that returns true when the value satisfies the condition (so a constant is probably not what you want). an anonymous subroutine is probably what you want. 🎀

Data::Constraint->add_constraint(
        $name_of_constraint,
        'run' => sub {...},
        [ @optional_arguments ],
        );

once i create the constraint, it exists forever (for now). i get back the constraint object:

my $constraint = Data::Constraint->add_constraint( ... );

the object sticks around after $constraint goes out of scope. the $constraint is just a reference to the object. i can get another reference to it through get_by_name(). see "Deleting a constraint" if you want to get rid of them. 💀

🫣 Modifying a constraint

um, don't do that yet unless you know what you are doing. 🙈

🗑️ Deleting a constraint

Data::Constraint->delete_by_name( $name );

Data::Constraint->delete_all();

😤 Doing anything you want

you wish! this module can't help you there. 💀

---

🔥 METHODS 🔥

check( VALUE )

apply the constraint to the VALUE. that's it, that's the method. ✨

add_constraint( NAME, KEY-VALUES )

added a constraint with name NAME. possible keys and values:

• run — reference to subroutine to run
• description — string that decribes the constraint

example:

Data::Constraint->add_constraint(
        $name_of_constraint,
        'run'       => sub {...},
        description => 'This is what I do",
        );

get_all_names

return a list of all the defined constraints. 📋

get_by_name( CONSTRAINT_NAME )

return the constraint with name CONSTRAINT_NAME. this is

delete_by_name( CONSTRAINT_NAME )

delete the constraint with name CONSTRAINT_NAME. it's no longer available. gone. poof. 💨

delete_all()

delete all the constraints, even the default ones. 😱

description

return the description. the default description is the empty string. you should supply your own description with "add_constraint".

run

return the description. the default description is the empty string. you should supply your own description with "add_constraint".

bestie i am telling you exactly what the page says here, word for word energy. 💅

---

🦋 SOURCE AVAILABILITY 🦋

this source is in Github:

https://github.com/briandfoy/data-constraint

---

👑 AUTHOR 👑

brian d foy, "<briandfoy@pobox.com>"

---

⭐ COPYRIGHT AND LICENSE ⭐

Copyright © 2004-2025, brian d foy <briandfoy@pobox.com>. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

---

and that's the whole page, bestie! 🫶 this came to you via perl v5.42.0, dated 2025-07-25 — Data::Constraint(3), signing off. mwah. 💖✨🎀