namespace::sweep(3pm)

✨ namespace::sweep ✨

okay bestie, this is the manual page for namespace::sweep — it's from the User Contributed Perl Documentation, which is exactly what it sounds like: docs that perl people wrote for other perl people 🫶. it's a Perl pragma, it lives in the 3pm section, and it is here to do one very specific, very iconic job.

---

💖 NAME 💖

namespace::sweep — sweep up imported subs in your classes 🧹✨

---

🌸 VERSION 🌸

version 0.006

---

🦋 SYNOPSIS 🦋

package Foo;

use namespace::sweep;
use Some::Module qw(some_function);

sub my_method {
     my $foo = some_function();
     ...
}

package main;

Foo->my_method;      # ok
Foo->some_function;  # ERROR!

see how Foo->my_method is fine and Foo->some_function is a whole disaster? yeah. that's the entire point of this module and we LOVE her for it 💅

---

👑 DESCRIPTION 👑

so here's the tea: because Perl methods are literally just regular subroutines, it's genuinely hard to tell what's a method and what's just some imported function that wandered into your class. and the consequence of that? imported functions can get called as methods on your objects. not cute. not the vibe.

this pragma deletes imported functions from your class's symbol table, which means your interface ends up being exactly the interface you specified. periodt. no random strays showing up to the party.

but — and this is the important bit — code inside your module can still use the imported functions with zero problems. they're gone from the outside, still fully available on the inside. it's giving "off duty but still on call" 💜

---

🎀 ARGUMENTS 🎀

you can pass these on the use line, bestie:

• -cleanee — if you wanna clean a different class than the one that's importing this pragma, say so with this flag. otherwise it just assumes the importing class. easy.

package Foo;
use namespace::sweep -cleanee => 'Bar'   # sweep up Bar.pm

• -also — this one lets you build a whole mechanism for specifying other subs to sweep up that wouldn't normally get caught. (think: private helper subs hanging out in your module's class that should never, ever be called as methods 🙈)

package Foo;
use namespace::sweep -also => '_helper';          # sweep up single sub
use namespace::sweep -also => [qw/foo bar baz/];  # list of subs
use namespace::sweep -also => qr/^secret_/;       # subs matching regex

you can also hand it a subroutine reference, and that sub will receive the symbol name as $_. if the sub returns true, the symbol gets swept. bye girl 💀

# sweep up those rude four-letter subs
use namespace::sweep -also => sub { return 1 if length $_ == 4 }

and yes, you can combine all of these methods into an array reference:

use namespace::sweep -also => [ 'string', sub { 1 if /$pat/ and $_ !~ /$other/ }, qr/^foo_.+/ ];

---

🔥 RATIONALE 🔥

this pragma exists to fix some problems with the excellent namespace::autoclean. specifically:

namespace::autoclean will remove special symbols that are installed by overload, which means you can't use namespace::autoclean on objects that overload Perl operators. rough.

also, namespace::autoclean relies on Class::MOP to figure out the list of methods your class provides. this pragma does not depend on Class::MOP or Moose, so you can use it on non-Moose classes without worrying about heavy dependencies. light and free, as she should be 🦋

however — if your class has a Moose (or Moose-compatible) meta object, then that will be used to find e.g. methods from composed roles that shouldn't be deleted. teamwork makes the dream work.

and in most cases, namespace::sweep should work as a drop-in replacement for namespace::autoclean. upon release, this pragma passes all of namespace::autoclean's tests, in addition to its own. ate that, no cap 👑

---

💀 CAVEATS 💀

this is an early release and there are b o u n d to be a few hiccups along the way. you have been warned, bestie.

---

🫶 ACKNOWLEDGEMENTS 🫶

thanks to Florian Ragwitz and Tomas Doran for writing and maintaining namespace::autoclean.

thanks to Toby Inkster for submitting some better code for finding meta objects.

---

🌈 SEE ALSO 🌈

namespace::autoclean, namespace::clean, overload

---

⭐ AUTHOR ⭐

Mike Friedman <friedo@friedo.com>

---

💜 COPYRIGHT AND LICENSE 💜

this software is copyright (c) 2011 by Mike Friedman.

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, babes 🎀 this was namespace::sweep, version 0.006, rendered from perl v5.34.0 and dated 2022-06-16. go forth and sweep 💅✨