Declar...y::Base(3pm)

💖 Declar...y::Base(3pm) — the User Contributed Perl Documentation moment 💖

okay bestie, gather round, because this is Declare::Constraints::Simple::Library::Base and it is literally the blueprint every other library in this family builds on. it's the base class, the mom friend, the one holding everybody's stuff together. no cap. ✨

---

🌸 NAME 🌸

Declare::Constraints::Simple::Library::Base — the Library Base Class, aka the foundational vibe 💅

---

🦋 SYNOPSIS 🦋

here's the whole aesthetic, verbatim, don't touch a character:

package My::Constraint::Library;
use warnings;
use strict;

# this installs the base class and helper functions
use Declare::Constraints::Simple-Library;

# we can also automagically provide other libraries
# to the importer
use base 'Declare::Constraints::Simple::Library::Numericals';

# with this we define a constraint to check a value
# against a serial number regular expression
constraint 'SomeSerial',
  sub {
    return sub {
      return _true if $_[0] =~ /\d{3}-\d{3}-\d{4}/;
      return _false('Not in SomeSerial format');
    };
  };

1;

see how clean that is? that's the energy. that's the assignment. 🫶

---

✨ DESCRIPTION ✨

so like, this base class is where all the common library functionality lives. we're talking helper functions and the install mechanisms — the whole infrastructure. everything else gets to just exist on top of it, which is honestly main character behavior of the supportive kind. 💜

---

👑 METHODS 👑

install_into($target)

installs the base classes and helper functions into the $target namespace. the %CONSTRAINT_GENERATORS package variable of that class is what gets used as storage for its constraints. that's the closet. that's where the fits live. 🎀

fetch_constraint_declarations()

class method. hands you back all the constraints registered to the class. the whole collection. no gatekeeping. 🌈

fetch_constraint_generator($name)

class method. returns the constraint generator code reference registered under $name. and heads up bestie — if that generator can't be found, this call will raise a "croak". it's not being dramatic, it's being correct. 😭

prepare_generator($constraint_name, $generator)

class method. this wraps the $generator in a closure that provides stack and failure-collapsing decisions. it's giving backstage pass energy — all the messy logistics handled before the performance. ⭐

add_constraint_generator($name, $code)

class method. this is the actual registration method, and it's the one "constraint" uses under the hood. the real one. the plug. 🔥

---

💅 HELPER FUNCTIONS 💅

okay so quick note before we dive in: some of these helper functions have an "_" prefix. and yes, that technically means they're internal functions — but it is totally ok to call them, because they have a fixed API. they're not distribution-internal, they're library-internal. so the only intended audience is code running inside constraints. iykyk. 🙈

constraint($name, $code)

constraint 'Foo', sub { ... };

this registers a new constraint in the calling library. important detail though — constraints have to return result objects. to make that happen you can use the helper functions "_result($bool, $msg", _true() and _false($msg). yes we're all using the helpers. it's a group project and we're all participating. 💖

_result($bool, $msg)

returns a new result object. its validity flag depends on the $bool argument. and the $msg argument is the error message to use on failure. so basically: you decide if it's a slay or a fail, and you write the note. 🍓

_false($msg)

returns a non-valid result object, with its message set to $msg. we love a clear rejection. 🌸

_true()

returns a valid result object. that's it. that's the whole thing. and honestly? iconic. ✨

_info($info)

sets the current failure info to use in the stack info part. 🧚

_apply_checks($value, \@constraints, [$info])

this applies all constraints in the "\@constraints" array reference to the passed $value. and optionally you can specify an $info string, which gets used in the stack of the newly created non-valid results. so you can label your sadness. thoughtful! 😭

_listify($value)

puts $value into an array reference and returns it — but only if it isn't already one. so if it's already an arrayref, it just leaves it alone. we do not double-wrap. we have boundaries. 🎀

_with_message($msg, $closure, @args)

this is the internal version of the general "Message" constraint. it sets the current overridden message to $msg and then executes the $closure with @args as arguments. 💜

_with_scope($scope_name, $constraint, @args)

applies the $constraint to @args in a newly created scope named by $scope_name. new scope, who dis. 🦋

_set_result($scope, $name, $result)

stores the given $result unter the name $name in $scope. (that's "unter" as in the original, bestie — we don't correct the source, we honor it. 💅)

_get_result($scope, $name)

returns the result named $name from $scope. 🫶

_has_result($scope, $name)

returns true only if such a result was registered already. a vibe check, essentially. 🌈

---

🔥 SEE ALSO 🔥

• Declare::Constraints::Simple
• Declare::Constraints::Simple::Library

go read those too, bestie. they're the extended universe. ⭐

---

💖 AUTHOR 💖

Robert 'phaylon' Sedlacek "<phaylon@dunkelheit.at>" — thank you for your service, king. 👑

---

🎀 LICENSE AND COPYRIGHT 🎀

this module is free software, you can redistribute it and/or modify it under the same terms as perl itself. periodt. 💅

---

okay that's the whole page!! and just so you have the receipts at the very end: this was perl v5.32.0, dated 2021-01-09, from Declar...y::Base(3pm). slay, go write some constraints, love u bye 💜✨