Find(3)

📦
version 0.17 · 11 versions
, in fedora 43

💖 Find(3) — Module::Find 💖

okay so this is the Find(3) page from the User Contributed Perl Documentation section, and it's literally about one of the most useful little modules ever: Module::Find 🎀 (yes that's the manual name, and yes it slays)

✨ NAME ✨

Module::Find — find and use installed modules in a (sub)category 💅

🌸 SYNOPSIS 🌸

  use Module::Find;

  # use all modules in the Plugins/ directory
  @found = usesub Mysoft::Plugins;

  # use modules in all subdirectories
  @found = useall Mysoft::Plugins;

  # find all DBI::... modules
  @found = findsubmod DBI;

  # find anything in the CGI/ directory
  @found = findallmod CGI;

  # set your own search dirs (uses @INC otherwise)
  setmoduledirs(@INC, @plugindirs, $appdir);

  # not exported by default
  use Module::Find qw(ignoresymlinks followsymlinks);

  # ignore symlinks
  ignoresymlinks();

  # follow symlinks (default)
  followsymlinks();

🦋 DESCRIPTION 🦋

So Module::Find lets you, bestie, find and use modules that live in categories. Lowkey iconic for auto-detecting driver modules or plugin modules — like, it does the "who's in this folder" homework for you 🫶. And you get to pick whether you look just in the category itself or in all the subcategories too. Different vibes, different functions.

okay important one 👑 — if you want Module::Find to search in a certain directory on your harddisk (say, the plugins directory of your software installation), make sure you modify @INC before you call the Module::Find functions. No cap, order matters.

💜 FUNCTIONS 💜

  • setmoduledirs(@directories) — sets the directories that get searched for modules. If you don't set them, Module::Find will just use @INC. And heads up: if you do use this function, @INC is not included automatically — so add it yourself if you want it in the mix 🧚. Set it to undef to revert to the default behaviour.
  • @found = findsubmod Module::Category — returns the modules found in the Module/Category subdirectories of your perl installation. Like, findsubmod CGI will return CGI::Session, but not CGI::Session::File. Surface level only, bestie ✨
  • @found = findallmod Module::Category — returns the modules found in the Module/Category subdirectories of your perl installation. So findallmod CGI will return CGI::Session and also CGI::Session::File. It goes deep 💀
  • @found = usesub Module::Category — uses and returns the modules found in the Module/Category subdirectories of your perl installation. usesub CGI will return CGI::Session, but not CGI::Session::File.
and if any module dies during loading, usesub will also die at this point 😭 like it goes down with the ship. fr fr.
  • @found = useall Module::Category — uses and returns the modules found in the Module/Category subdirectories of your perl installation. useall CGI will return CGI::Session and also CGI::Session::File.
same deal: if any module dies during loading, useall will also die at this point. drama follows it 💅
  • ignoresymlinks() — do not follow symlinks. This function is not exported by default 🙈
  • followsymlinks() — follow symlinks (this is the default behaviour). This function is not exported by default either 🎀

🌈 HISTORY 🌈

the whole glow-up timeline, periodt:

  • 0.01, 2004-04-22 — original version; created by h2xs 1.22
  • 0.02, 2004-05-25 — added test modules that were left out in the first version. Thanks to Stuart Johnston for alerting me to this.
  • 0.03, 2004-06-18 — fixed a bug (non-localized $_) by declaring a loop variable in use functions. Thanks to Stuart Johnston for alerting me to this and providing a fix. Also fixed non-platform compatibility by using File::Spec. Thanks to brian d foy. Added setmoduledirs and updated tests — idea shamelessly stolen from ...errm... inspired by brian d foy 😂
  • 0.04, 2005-05-20 — added POD tests.
  • 0.05, 2005-11-30 — fixed issue with bugfix in PathTools-3.14.
  • 0.06, 2008-01-26 — Module::Find now won't report duplicate modules several times anymore (thanks to Uwe Völker for the report and the patch) 🔥
  • 0.07, 2009-09-08 — fixed RT#38302: Module::Find now follows symlinks by default (can be disabled).
  • 0.08, 2009-09-08 — fixed RT#49511: removed Mac OS X extended attributes from distribution.
  • 0.09, 2010-02-26 — fixed RT#38302: fixed META.yml generation (thanks very much to cpanservice for the help).
  • 0.10, 2010-02-26 — fixed RT#55010: removed Unicode BOM from Find.pm.
  • 0.11, 2012-05-22 — fixed RT#74251: defined(@array) is deprecated under Perl 5.15.7. Thanks to Roman F, who contributed the implementation.
  • 0.12, 2014-02-08 — fixed RT#81077: useall fails in taint mode. Thanks to Aran Deltac, who contributed the implementation and test. Fixed RT#83596: documentation doesn't describe behaviour if a module fails to load — clarified documentation for useall and usesub. Fixed RT#62923: setmoduledirs(undef) doesn't reset to searching @INC — added more explicit tests. Thanks to Colin Robertson for his input. 🫶
  • 0.13, 2015-03-09 — this release contains two contributions from Moritz Lenz: link to Module::Pluggable and Class::Factory::Util in SEE ALSO, and align package name parsing with how perl does it (allowing single quotes as module separator). Also, added a test for meta.yml.
  • 0.14, 2019-12-25 — a long overdue update. Thank you for the many contributions! Fixed RT#99055: removed file readability check (pull request contributed by Moritz Lenz). Now supports @INC hooks (pull request contributed by Graham Knop). Now filters out filenames starting with a dot (pull request contributed by Desmond Daignault). Now uses strict (pull request contributed by Shlomi Fish). Fixed RT#122016: test/ files show up in metacpan (bug report contributed by Karen Etheridge). 🎁
  • 0.15, 2019-12-26 — fixed RT#127657 (bug report contributed by Karen Etheridge): Module::Find now uses @ModuleDirs (if specified) for loading modules. Previously, when using setmoduledirs() to set an array of directories that did not contain @INC, Module::Find would find the modules correctly, but load them from @INC. sneaky 😭
  • 0.16, 2022-08-01 — fixes an issue where symlink tests failed on systems that do not support creation of symlinks. The issue appears on Windows systems due to changed behaviour in File::Find described in perl5/issue #19995 <https://github.com/Perl/perl5/issues/19995>. Symlink tests were previously skipped if symlink() is not available, and now also if creation of a symlink is not possible. Fixes issue #9 <https://github.com/crenz/Module-Find/issues/9>. Note that on Windows system, the patch to File::Find from perl5/PR #20008 <https://github.com/Perl/perl5/pull/20008> will be required for proper operation. 💀
  • 0.17, 2025-02-16 — fixes issue 13 <https://github.com/crenz/Module-Find/issues/13> / 148978 <https://rt.cpan.org/Ticket/Display.html?id=148978> where warnings where produced upon extracting the installation archive, which prevented installation under cpanm and other tools. 💅

🧚 DEVELOPMENT NOTES 🧚

The development repository for this module is hosted on GitHub: <http://github.com/crenz/Module-Find/>. Please report any bugs by opening an issue there 👑

⭐ SEE ALSO ⭐

perl, Module::Pluggable, Class::Factory::Util

🍓 AUTHOR 🍓

Christian Renz, <crenz@web42.com>

Copyright 2004-2025 by Christian Renz <crenz@web42.com>. All rights reserved.

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

and that's the whole page bestie 💖 perl v5.42.0, dated 2025-07-25 — go find some modules, you got this 🦋

📦 where this page comes from