# perldoc > Pod::Simple::Search

---
type: CommandReference
command: Pod::Simple::Search
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference

- `Pod::Simple::Search->new` — create a new search object
- `$search->survey(@directories)` — search for POD files, return name2path and path2name hashes
- `$search->find($pod, @search_dirs)` — find location of a POD file by name
- `$search->limit_glob('LWP::*')` — restrict search to matching glob pattern
- `$search->inc(0)` — disable searching @INC directories

## Name

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

## Synopsis

perl
use Pod::Simple::Search;

# Survey with limit_glob
my $name2path = Pod::Simple::Search->new->limit_glob('LWP::*')->survey;
print join(' ', sort keys %$name2path), "\n";

# Find a specific module
print Pod::Simple::Search->new->find('LWP::UserAgent') || "?\n";
## Options

### Constructor

- `new` — constructor, takes no parameters

### Search control accessors

All accessors return `$self` when called with a value, allowing chaining.

- `inc(true_or_false)` — if true, include `@INC` paths in search (default true)
- `verbose(nonnegative_number)` — set verbosity level (0, 1, 2) for debugging
- `limit_glob(glob_string)` — restrict to pod names matching glob (e.g., `'LWP::*'`)
- `limit_re(regexp)` — restrict to pod names matching regexp
- `callback(\&routine)` — call routine for each matched POD file, receives (filespec, podname)
- `laborious(true_or_false)` — disable Perl-specific heuristics (default false)
- `recurse(true_or_false)` — recurse into subdirectories (default true)
- `shadows(true_or_false)` — include shadow files (default false)
- `is_case_insensitive(true_or_false)` — force case-insensitive comparison (default auto-detect)
- `dir_prefix(string)` — start search in given subdirectory (e.g., `'Pod'`)
- `progress(progress_object)` — object with `reach` and `done` methods for progress reporting

### Result accessors (set by `survey`)

- `name2path` — read-only hashref mapping pod names to filespecs
- `path2name` — read-only hashref mapping filespecs to pod names

## Examples

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

# Find with default @INC
my $filename = Pod::Simple::Search->new->find('perlvar');

# Check if a file contains POD
if (Pod::Simple::Search->contains_pod($file)) { ... }

# Survey returns (\%name2path, \%path2name) in list context,
# \%name2path in scalar context
my ($name2path, $path2name) = $search->survey(@dirs);
## See Also

- [Pod::Simple](https://metacpan.org/pod/Pod::Simple)
- [Pod::Find](https://metacpan.org/pod/Pod::Find)
- [Pod::Search](https://metacpan.org/pod/Pod::Search)
- [perlpod](https://metacpan.org/pod/perlpod)