MooseX::Declare(3pm)

📦
version 0.43 · 4 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 MooseX::Declare 💖

okay so bestie, this is MooseX::Declare, straight out of the User Contributed Perl Documentation — the whole vibe is declarative syntax for Moose. Sit down, hydrate, we're getting into it. 🎀

✨ NAME ✨

MooseX::Declare — (DEPRECATED) declarative syntax for Moose 💅

🌸 VERSION 🌸

version 0.43 ⭐

🦋 SYNOPSIS 🦋

use MooseX::Declare;

class BankAccount {
    has 'balance' => ( isa => 'Num', is => 'rw', default => 0 );

    method deposit (Num $amount) {
        $self->balance( $self->balance + $amount );
    }

    method withdraw (Num $amount) {
        my $current_balance = $self->balance();
        ( $current_balance >= $amount )
            || confess "Account overdrawn";
        $self->balance( $current_balance - $amount );
    }
}

class CheckingAccount extends BankAccount {
    has 'overdraft_account' => ( isa => 'BankAccount', is => 'rw' );

    before withdraw (Num $amount) {
        my $overdraft_amount = $amount - $self->balance();
        if ( $self->overdraft_account && $overdraft_amount > 0 ) {
            $self->overdraft_account->withdraw($overdraft_amount);
            $self->deposit($overdraft_amount);
        }
    }
}

look at that. a whole bank account, declared like a sentence. iconic. 👑

💜 DESCRIPTION 💜

This module hands you syntactic sugar for Moose, the postmodern object system for Perl 5. When you use it, it sets up the class and role keywords for you. ✨

Note: Please see the WARNING section below! bestie I am not joking, go read it. 😭

🧚 KEYWORDS 🧚

🌟 class

class Foo { ... }

my $anon_class = class { ... };

Declares a new class. It can be named or anonymous, depending on whether or not you hand it a classname. Inside the class definition, Moose and MooseX::Method::Signatures get set up automatically, plus all the other keywords described in this doc. When the definition ends, the class gets made immutable. namespace::autoclean gets injected so it can clean up Moose and other imports for you. no cap, it does the tidying for you 🧹

Because of the way the options are parsed, you cannot have a class named is, with or extends. just. don't. 💀

It's possible to specify options for classes:

💫 extends

class Foo extends Bar { ... }

Sets a superclass for the class being declared.

💫 with

class Foo with Role             { ... }
class Foo with Role1 with Role2 { ... }
class Foo with (Role1, Role2)   { ... }

Applies a role or roles to the class being declared.

💫 is mutable

class Foo is mutable { ... }

Causes the class not to be made immutable after its definition.

Options can also be provided for anonymous classes using the same syntax:

my $meta_class = class with Role;

🌟 role

role Foo { ... }

my $anon_role = role { ... };

Declares a new role. Named or anonymous, depending on whether or not a name is given. Inside the role definition, Moose::Role and MooseX::Method::Signatures get set up automatically, plus the other keywords described in this doc. And again, namespace::autoclean gets injected to clean up Moose::Role and other imports for you. 🫶

It's possible to specify options for roles:

💫 with

role Foo with Bar { ... }

Applies a role to the role being declared.

🌟 before / after / around / override / augment

before   foo ($x, $y, $z) { ... }
after    bar ($x, $y, $z) { ... }
around   baz ($x, $y, $z) { ... }
override moo ($x, $y, $z) { ... }
augment  kuh ($x, $y, $z) { ... }

Adds a method modifier. These work like documented in Moose, except the syntax is slightly nicer and the method signatures work like documented in MooseX::Method::Signatures. ✨

For the around modifier an additional argument called $orig is automatically set up as the invocant for the method. it just shows up. like a gift. 🎁

🌟 clean

Sometimes you don't want the automatic cleaning the class and role keywords provide using namespace::autoclean. In those cases you can specify the dirty trait for your class or role:

use MooseX::Declare;
class Foo is dirty { ... }

This will prevent cleaning of your namespace, except for the keywords imported from Moose or Moose::Role. Additionally, a clean keyword is provided, which lets you explicitly clean all functions that were defined prior to calling clean. Here's an example:

use MooseX::Declare;
class Foo is dirty {
    sub helper_function { ... }
    clean;
    method foo ($stuff) { ...; return helper_function($stuff); }
}

With that, the helper function won't be available as a method to a user of your class, but you're still able to use it inside your class. best of both worlds fr fr 💅

🌈 NOTE ON IMPORTS 🌈

When creating a class with MooseX::Declare like:

use MooseX::Declare;
class Foo { ... }

What actually happens is something like this:

{
    package Foo;
    use Moose;
    use namespace::autoclean;
    ...
    __PACKAGE__->meta->make_immutable;
}

So if you declare imports outside the class, the symbols get imported into the main:: namespace, not the class' namespace. And then those symbols cannot be called from within the class:

use MooseX::Declare;
use Data::Dump qw/dump/;
class Foo {
    method dump($value) { return dump($value) } # Data::Dump::dump IS NOT in Foo::
    method pp($value)   { $self->dump($value) } # an alias for our dump method
}

To solve this, only import MooseX::Declare outside the class definition (because you have to). Make all other imports inside the class definition. 🧠✨

use MooseX::Declare;
class Foo {
    use Data::Dump qw/dump/;
    method dump($value) { return dump($value) } # Data::Dump::dump IS in Foo::
    method pp($value)   { $self->dump($value) } # an alias for our dump method
}

Foo->new->dump($some_value);
Foo->new->pp($some_value);

NOTE that the import Data::Dump::dump() and the method Foo::dump(), although having the same name, do not conflict with each other, because the imported dump function will be cleaned during compile time, so only the method remains there at run time. If you want to do more esoteric things with imports, have a look at the clean keyword and the dirty trait. 😌

💀 WARNING 💀

Warning: MooseX::Declare is based on Devel::Declare, a giant bag of crack originally implemented by mst with the goal of upsetting the perl core developers so much by its very existence that they implemented proper keyword handling in the core.

As of perl5 version 14, this goal has been achieved, and modules such as Devel::CallParser, Function::Parameters, and Keyword::Simple provide mechanisms to mangle perl syntax that don't require hallucinogenic drugs to interpret the error messages they produce. 😭💀

If you want to use declarative syntax in new code, please for the love of kittens get yourself a recent perl and look at Moops instead. 🐱💖

🎀 SEE ALSO 🎀

🫶 AUTHOR 🫶

Florian Ragwitz <rafl@debian.org>

🌸 CONTRIBUTORS 🌸

  • Karen Etheridge <ether@cpan.org>
  • Piers Cawley <pdcawley@bofh.org.uk>
  • Robert 'phaylon' Sedlacek <rs@474.at>
  • Ash Berlin <ash_github@firemirror.com>
  • Nick Perez <nperez@cpan.org>
  • Nelo Onyiah <nelo.onyiah@gmail.com>
  • Chas. J. Owens IV <chas.owens@gmail.com>
  • leedo <lee@laylward.com>
  • Michele Beltrame <arthas@cpan.org>
  • Frank Wiegand <fwie@cpan.org>
  • David Steinbrunner <dsteinbrunner@pobox.com>
  • Oleg Kostyuk <cub.uanic@gmail.com>
  • Dave Rolsky <autarch@urth.org>
  • Rafael Kitover <rkitover@io.com>
  • Chris Prather <chris@prather.org>
  • Stevan Little <stevan.little@iinteractive.com>
  • Tomas Doran <bobtfish@bobtfish.net>
  • Yanick Champoux <yanick@babyl.dyndns.org>
  • Justin Hunter <justin.d.hunter@gmail.com>

look at this whole squad. a community. 🥹💖

This software is copyright (c) 2008 by Florian Ragwitz.

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

okay bestie that's the whole page, and this cute little sign-off is brought to you by perl v5.34.0, dated 2022-06-15 — that's the footer, folded up all cozy at the end. now go read that WARNING again. ily, bye 💖🦋✨

📦 where this page comes from