namespa...toclean(3)

🦋 namespa...toclean(3) — namespace::autoclean 💅

okay so bestie, you're looking at a page from the User Contributed Perl Documentation (that's the manual name, don't @ me), and it's literally about keeping your namespace from getting cluttered. icon behavior tbh ✨

---

🌸 NAME 🌸

namespace::autoclean — keep imports out of your namespace, no cap 🧚

---

⭐ VERSION ⭐

version 0.31 — the glow-up number you're working with 🎀

---

💖 SYNOPSIS 💖

okay so picture this:

package Foo;
use namespace::autoclean;
use Some::Package qw/imported_function/;

sub bar { imported_function('stuff') }

# later on:
Foo->bar;               # works
Foo->imported_function; # will fail. imported_function got cleaned after compilation

read that comment again, bestie — that last line is the whole point of the module fr fr 😭

---

👑 DESCRIPTION 👑

So here's the tea 🍓: when you import a function into a Perl package, it naturally also becomes available as a method. Like, automatically. Whether you wanted that or not. Rude, honestly.

The namespace::autoclean pragma will remove all imported symbols at the end of the current package's compile cycle. Functions called inside the package itself will still be bound by their name — they still work, slay — but they won't show up as methods on your class or your instances. ✨

This module is very similar to namespace::clean, except it will clean all imported functions, no matter if you imported them before or after you used the pragma. It also will not touch anything that looks like a method. periodt 💅

Now — if you're writing an exporter and you want to clean up after yourself (and your peers, because we're considerate like that 🫶), you can use the -cleanee switch to specify what package to clean:

package My::MooseX::namespace::autoclean;
use strict;

use namespace::autoclean (); # no cleanup, just load

sub import {
    namespace::autoclean->import(
      -cleanee => scalar(caller),
    );
}

note the () on that use line — no cleanup, just load. that's the vibe check for this whole snippet 🔥

---

🌈 WHAT IS AND ISN'T CLEANED 🌈

namespace::autoclean will leave behind anything that it deems a method. Like it's out here doing favorites and honestly, fair.

• For Moose classes, this is based on the get_method_list method on from the Class::MOP::Class. 👑
• For non-Moose classes, anything defined within the package will be identified as a method.
• This should match Moose's definition of a method.
• Additionally, the magic subs installed by overload will not be cleaned. they're safe, don't worry 🙈

---

💜 PARAMETERS 💜

🎀 -also => [ ITEM | REGEX | SUB, .. ]

🎀 -also => ITEM

🎀 -also => REGEX

🎀 -also => SUB

Sometimes you don't want to clean imports only, but also helper functions you're using in your methods. The -also switch can be used to declare a list of functions that should be removed additional to any imports:

use namespace::autoclean -also => ['some_function', 'another_function'];

If only one function needs to be additionally cleaned, the -also switch also accepts a plain string:

use namespace::autoclean -also => 'some_function';

In some situations, you may wish for a more powerful cleaning solution. 💀

The -also switch can take a Regex or a CodeRef to match against local function names to clean:

use namespace::autoclean -also => qr/^_/

use namespace::autoclean -also => sub { $_ =~ m{^_} };

use namespace::autoclean -also => [qr/^_/ , qr/^hidden_/ ];

use namespace::autoclean -also => [sub { $_ =~ m/^_/ or $_ =~ m/^hidden/ }, sub { uc($_) == $_ } ];

🦋 -except => [ ITEM | REGEX | SUB, .. ]

🦋 -except => ITEM

🦋 -except => REGEX

🦋 -except => SUB

This takes exactly the same options as -also — except that anything this matches will not be cleaned. It's the "hands off, she's with me" option 🫶✨

---

💀 CAVEATS 💀

Big one, bestie, listen up:

When used with Moo classes, the heuristic used to check for methods won't work correctly for methods from roles consumed at compile time. 😭

package My::Class;
use Moo;
use namespace::autoclean;

# Bad, any consumed methods will be cleaned
BEGIN { with 'Some::Role' }

# Good, methods from role will be maintained
with 'Some::Role';

So like — BEGIN { with 'Some::Role' } is the bad one (methods get cleaned, oop), and plain with 'Some::Role' is the good one (methods maintained, slay). Don't mix these up ngl 🚩

Additionally, method detection may not work properly in Mouse classes in perls earlier than 5.10. old perl, old problems 🙈

---

🔥 SEE ALSO 🔥

• namespace::clean
• B::Hooks::EndOfScope
• namespace::sweep
• Sub::Exporter::ForMethods
• Sub::Name
• Sub::Install
• Test::CleanNamespaces
• Dist::Zilla::Plugin::Test::CleanNamespaces

go read all of these, iykyk 💅📚

---

🫶 SUPPORT 🫶

Bugs may be submitted through the RT bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=namespace-autoclean> (or bug-namespace-autoclean@rt.cpan.org <mailto:bug-namespace-autoclean@rt.cpan.org>). 🐛

There is also a mailing list available for users of this distribution, at <http://lists.perl.org/list/moose.html>. 📬

There is also an irc channel available for users of this distribution, at #moose on irc.perl.org <irc://irc.perl.org/#moose>. irc girlies rise up 🌸

---

✨ AUTHOR ✨

Florian Ragwitz <rafl@debian.org> — the main character of this page 👑

---

🌟 CONTRIBUTORS 🌟

• Karen Etheridge <ether@cpan.org>
• Graham Knop <haarg@haarg.org>
• Dave Rolsky <autarch@urth.org>
• Kent Fredric <kentfredric@gmail.com>
• Tomas Doran <bobtfish@bobtfish.net>
• Shawn M Moore <cpan@sartak.org>
• Felix Ostmann <sadrak@cpan.org>
• Andrew Rodland <arodland@cpan.org>
• Chris Prather <chris@prather.org>

the whole squad showed up, we love a collab 🫶✨

---

🎀 COPYRIGHT AND LICENCE 🎀

This software is copyright (c) 2009 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, no notes 💅

sign-off tea: this beauty was rendered from perl v5.42.0 and dated 2024-10-13, and yes it's still calling itself namespa...toclean(3) in the corner like the icon it is. slay 🦋