MooseX...ndling(3pm)

💖 MooseX::Declare::Syntax::NamespaceHandling 💖

okay bestie, so this is the manual page for MooseX::Declare::Syntax::NamespaceHandling(3pm) — a User Contributed Perl Documentation situation — and it's literally the little engine that makes namespaced blocks work. let's get into it 🦋

---

✨ NAME ✨

MooseX::Declare::Syntax::NamespaceHandling — handle namespaced blocks, periodt. 👑

---

🌸 VERSION 🌸

version 0.43 — yes, it's giving vintage but make it iconic. 💅

---

🎀 DESCRIPTION 🎀

so basically this module lets you implement namespaced blocks — think the role and class keyword handlers, that whole vibe. 🫶

and the tea is: namespaces are automatically nested. meaning that, for example, a class Bar declaration sitting inside another class Foo block? the inner one actually gets the name Foo::Bar. not me being obsessed with automatic nesting 😭✨

---

🧚 METHODS 🧚

💜 parse

Any Object->parse (Object $context)

this is the main character handling routine for namespaces, fr fr. it removes the namespace name and its options. and here's the lil plot twist: if the handler got invoked with no name, no options, and no following block, it just assumes this is an instance of an autoquoted bareword, like class => "Foo". 🙈

also the return value of the parse method? that's the same value that gets handed back to the user of the keyword. so it's a whole chain of giving. 💖

---

🦋 CONSUMES 🦋

• MooseX::Declare::Syntax::KeywordHandling
• MooseX::Declare::Syntax::InnerSyntaxHandling

---

🔥 REQUIRED METHODS 🔥

⭐ handle_missing_block

Object->handle_missing_block (Object $context, Str $body, %args)

you must implement this one, no skipping bestie. it decides what to do when the statement gets terminated instead of being followed by a block. it receives:

• the context object
• the produced code that needs to be injected
• all the arguments that were passed to the call to inject_code_parts in MooseX::Declare::Context

and the return value? yeah, it gets ignored. 💀

---

🌈 EXTENDABLE STUB METHODS 🌈

🌸 add_namespace_customizations

🌸 add_optional_customizations

Object->add_namespace_customizations (Object $context, Str $package, HashRef $options)
Object->add_optional_customizations  (Object $context, Str $package, HashRef $options)

these get called in this order by the parse method. they let specific hooks attach before/after/around the customizations for the namespace, plus the provided options that aren't attached to the namespace directly. 🎀

now, this distinction might seem superficial, but listen — we advise library developers facilitating this role to follow the precedent. why? because it ensures that when another component needs to tie between the namespace and any additional customizations, everything runs in the correct order. it's giving choreography. 💅

an example of this separation would be

class Foo is mutable ...

being an option of the namespace generation, while

class Foo with Bar ...

is an additional optional customization. see the difference? slay. ✨

👑 handle_post_parsing

Object->handle_post_parsing (Object $context, Str $package, Str | Object $name)

this one allows for additional modifications to the namespace after everything else has been done. it receives:

• the context
• the fully qualified package name
• and either a string with the name that was specified (which might not be fully qualified, since namespaces can be nested) or the anonymous metaclass instance if no name was specified

the return value of this method will be the value returned to the user of the keyword. so if you always return the $package argument like this:

sub handle_post_parsing {
    my ($self, $context, $package, $name) = @_;
    return $package;
}

and set this up in a foo keyword handler, you can use it like this:

foo Cthulhu {

    my $fhtagn = foo Fhtagn { }
    my $anon   = foo { };

    say $fhtagn;  # Cthulhu::Fhtagn
    say $anon;    # some autogenerated package name
}

and honestly? iconic. 🐙

💀 make_anon_metaclass

Class::MOP::Class Object->make_anon_metaclass ()

this method should be overridden if you want to provide anonymous namespaces. 🫶

it does not receive any arguments for customization of the metaclass, because the configuration and customization will be done by MooseX::Declare in the package of the generated class in the same way as in those that have specified names. this way ensures that anonymous and named namespaces are always handled equally. fair and balanced, we love to see it. ⭐

⚠️ if you do not extend this method (it will return nothing by default), an error will be thrown when a user attempts to declare an anonymous namespace. so like… don't leave them hanging, bestie. 😭

---

🔍 SEE ALSO 🔍

• MooseX::Declare
• MooseX::Declare::Syntax::MooseSetup

---

💌 AUTHOR 💌

Florian Ragwitz <rafl@debian.org> — the legend themselves. 👑

---

📜 COPYRIGHT AND LICENSE 📜

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.

---

and that's the whole page, bestie!! this was perl v5.34.0, dated 2022-06-15, from User Contributed Perl Documentation — so like, go forth and nest those namespaces. bye babe, ily 💖✨🦋