perldoc > Pod::Simple::Search

man perldoc info pydoc3 ri search

📖 NAME

Pod::Simple::Search — find POD documents in directory trees

🚀 Quick Reference

Use Case	Command	Description
🔍 Survey all PODs in default directories	Pod::Simple::Search->new->survey	Returns hashes mapping module names to paths and vice versa, using @INC and scriptdir
🎯 Find a specific POD file	Pod::Simple::Search->new->find('Module::Name')	Returns full path to first occurrence of a POD file with given name
🔒 Limit search to a glob pattern	Pod::Simple::Search->new->limit_glob('LWP::*')->survey	Only returns modules matching the wildcard expression
📁 Search in custom directories (no @INC)	Pod::Simple::Search->new->inc(0)->survey(@dirs)	Disables implicit @INC paths and searches only specified directories
🔁 Callback on each found POD	Pod::Simple::Search->new->callback(\&sub)->survey	Invokes the callback with (filespec, podname) for every matching file
📢 Verbose debugging	Pod::Simple::Search->new->verbose(2)->find('Foo')	Prints progress messages via warn; level 2 gives even more detail

📝 SYNOPSIS

  use Pod::Simple::Search;
  my $name2path = Pod::Simple::Search->new->limit_glob('LWP::*')->survey;
  print "Looky see what I found: ",
    join(' ', sort keys %$name2path), "\n";

  print "LWPUA docs = ",
    Pod::Simple::Search->new->find('LWP::UserAgent') || "?",
    "\n";

📚 DESCRIPTION

Pod::Simple::Search is a class for searching for Pod files. An object of this class has several attributes (options) and methods for searching.

Usage: create a new object, set options, then call one of the search methods (typically survey or find).

🛠️ CONSTRUCTOR

This class provides one constructor, new, which takes no parameters:

  use Pod::Simple::Search;
  my $search = Pod::Simple::Search->new;

⚙️ ACCESSORS

Each accessor returns $self when called with a value, enabling chaining:

  my $name2path =
    Pod::Simple::Search->new
    -> inc(0) -> verbose(1) -> callback(\&blab)
    ->survey(@there);

• $search->inc( true-or-false ) — If true (default), searches include @INC directories (and PERL5LIB). Set to false to search only specific directories.
• $search->verbose( nonnegative-number ) — If non-zero, emits warn messages about search progress. 0 = silent (default), 1 = some messages, 2 = more verbose.
• $search->limit_glob( some-glob-string ) — Limits results to module names matching a wildcard (e.g., 'LWP::*', '*Find*'). Supports ? and *.
• $search->callback( \&some_routine ) — Sets a callback invoked with ($filespec, $podname) for each matching Pod file. Return value ignored. Default: no callback.
• $search->laborious( true-or-false ) — If true, disables Perl-specific heuristics (file extension filtering, version-specific subdirs, etc.). Default: false.
• $search->recurse( true-or-false ) — If true (default), recurses into subdirectories during search.
• $search->shadows( true-or-false ) — If true, includes "shadow" files (duplicate module names in later directories). Default: false.
• $search->is_case_insensitive( true-or-false ) — Override filesystem case sensitivity detection. Default: auto-detect.
• $search->limit_re( some-regexp ) — Limits results to module names matching a regexp. Normally use limit_glob instead.
• $search->dir_prefix( some-string-value ) — Starts search in the given subdirectory (e.g., 'Pod' or 'File::Find'). Usually set automatically by limit_glob.
• $search->progress( some-progress-object ) — Accepts an object with reach and done methods for progress reporting. Not commonly used.
• $name2path = $self->name2path; — After survey, returns the hashref mapping pod names to file paths.
• $path2name = $self->path2name; — After survey, returns the hashref mapping file paths to pod names.

🔍 MAIN SEARCH METHODS

🔍 $search->survey( @directories )

Searches for POD documents in the given files/directories (plus @INC if inc is true). Returns two hashes (or in scalar context, only the name2path hash):

• name2path — maps module names to filespecs (e.g., "Stuff::Thing" => "/path/Stuff/Thing.pm")
• path2name — inverse mapping

These hashes are also stored as attributes. In list context: (\%name2path, \%path2name). In void context, results are still saved.

Only text files containing at least one valid POD command are found. In verbose mode, warnings are issued for shadows (duplicate module names).

POD names are derived from base names with Perl-like extensions (.pm, .pl, .pod) stripped and path separators replaced by ::.

Calling Pod::Simple::Search->search(...) is shorthand for new->search(...).

🔍 $search->simplify_name( $str )

Equivalent to basename, but also strips extensions like .pm, .pl, .pod, .bat (Win32), .cmd (OS/2), .com (VMS).

🔍 $search->find( $pod )

🔍 $search->find( $pod, @search_dirs )

Returns the full path to the first occurrence of a Pod file for the given module/script name (e.g., 'Foo::Bar', 'perlvar'). Package names are converted to directory paths; extensions .pm, .pl, .pod are appended automatically.

If no file is found, returns undef. If a search directory contains a pod/ subdirectory, it is also searched.

When inc is true (default), adds @INC and $Config::Config{'scriptdir'} to the search directories.

Common usage: $filename = Pod::Simple::Search->new->find("perlvar").

🔍 $self->contains_pod( $file )

Returns true if the given file (not a POD module) contains some Pod documentation.

❓ SUPPORT

Questions or discussion about POD and Pod::Simple should be sent to the pod-people AT perl.org mail list. Send an empty email to pod-people-subscribe AT perl.org to subscribe.

This module is managed in an open GitHub repository, <https://github.com/perl-pod/pod-simple/>. Feel free to fork and contribute, or to clone <git://github.com/perl-pod/pod-simple.git> and send patches!

Patches against Pod::Simple are welcome. Please send bug reports to <bug-pod-simple AT rt.org>.

©️ COPYRIGHT AND DISCLAIMERS

Copyright (c) 2002 Sean M. Burke.

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

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

👤 AUTHOR

Pod::Simple was created by Sean M. Burke <sburke AT cpan.org> with code borrowed from Marek Rouchal's Pod::Find, which in turn heavily borrowed code from Nick Ing-Simmons' "PodToHtml".

But don't bother him, he's retired.

Pod::Simple is maintained by:

• Allison Randal <allison AT perl.org>
• Hans Dieter Pearcey <hdp AT cpan.org>
• David E. Wheeler <dwheeler AT cpan.org>

📖 NAME 🚀 Quick Reference 📝 SYNOPSIS 📚 DESCRIPTION 🛠️ CONSTRUCTOR ⚙️ ACCESSORS 🔍 MAIN SEARCH METHODS ❓ SUPPORT ©️ COPYRIGHT AND DISCLAIMERS 👤 AUTHOR