# NAME

Pod::Query - Query pod documents

# SYNOPSIS

Query POD information from a file

    % perl -MPod::Query -E 'say for Pod::Query->new("ojo")->find("head1[0]")'

    NAME
    ojo - Fun one-liners with Mojo

    % perl -MPod::Query -E 'say Pod::Query->new("ojo")->find("head1[0]/Para[0]")'

    ojo - Fun one-liners with Mojo

    % perl -MPod::Query -E 'say Pod::Query->new(shift)->find("head1[0]/Para[0]")' my.pod

Find Methods:

        find_title;
        find_method;
        find_method_summary;
        find_events;
        find($query_sting);
        find(@query_structs);

# DESCRIPTION

This module takes a class name, extracts the POD
and provides methods to query specific information.

# SUBROUTINES/METHODS

## \_has

Generates class accessor methods (like Mojo::Base::attr)

## path

Path to the pod class file

## lol

List of lists (LOL) structure of the pod file.
Result of Pod::LOL.

## tree

An hierarchy is added to the lol to create a
tree like structure of the pod file.

## class\_is\_path

Flag to indicate if the class is really a path to the file.

## new

Create a new object.
Return value is cached (based on the class of the pod file).

        use Pod::Query;
        my $pod = Pod::Query->new('Pod::LOL', PATH_ONLY=0);

PATH\_ONLY can be used to determine the path to the pod
document without having to do much unnecessary work.

## \_class\_to\_path

Given a class name, returns the path to the pod file.
Return value is cached (based on the class of the pod file).

If the class is not found in INC, it will be checked whether
the input is an existing file path.

Returns an empty string if there are any errors.

## \_mock\_root

For debugging and/or testing.
Builds a sample object (overwrite this in a test file).

## \_flatten\_for\_tags

Removes for tags from the lol and flattens
out the inner tags to be on the same level as the for
tag was.

## \_lol\_to\_tree

Generates a tree from a Pod::LOL object.
The structure of the tree is based on the N (level) in "=headN".

This example pod:

    =head1 FUNCTIONS

    =Para  Description of Functions

    =head2 Function1

    =Para  Description of Function1

    =head1 AUTHOR

    =cut

This will be grouped as:

    =head1 FUNCTIONS
       =Para Description of Functions
       =head2 Function1
          =Para Description of Function1
    =head1 AUTHOR

In summary:

- Non "head" tags are always grouped "below".
- HeadN tags with a higher N with also be grouped below.
- HeadN tags with the same or lower N will be grouped higher.

## \_define\_heads\_regex\_table

Generates the regexes for head elements inside
and outside the current head.

## \_make\_leaf

Creates a new node (aka leaf).

## \_structure\_over

Restructures the text for an "over-text" element to be under it.
Also, "item-text" will be the first element of each group.

## find\_title

Extracts the title information.

## find\_method

Extracts the complete method information.

## find\_method\_summary

Extracts the method summary.

## \_clean\_method\_name

Returns a method name without any possible parenthesis.

## find\_events

Extracts a list of events with a description.

Returns a list of key value pairs.

## find

Generic extraction command.

Note: This function is Scalar/List context sensitive!

    $query->find($condition)

Where condtion is a string as described in ["\_query\_string\_to\_struct"](#_query_string_to_struct)

    $query->find(@conditions)

Where each condition can contain:

    {
       tag       => "TAG_NAME",    # Find all matching tags.
       text      => "TEXT_NAME",   # Find all matching texts.
       keep      => 1,             # Capture the text.
       keep_all  => 1,             # Capture entire section.
       nth       => 0,             # Use only the nth match.
       nth_in_group => 0,             # Use only the nth matching group.
    }

Return contents of entire head section:

    find (
       {tag => "head", text => "a", keep_all => 1},
    )

Results:

    [
       "  my \$app = a('/hel...",
       {text => "Create a route with ...", wrap => 1},
       "  \$ perl -Mojo -E ...",
    ]

## \_query\_string\_to\_struct

Convert a pod query string into a structure based on these rules:

    1. Split string by '/'.
       Each piece is a separate list of conditions.

    2. Remove an optional '*' or '**' from the last condition.
       Keep is set if we have '*'.
       Keep all is set if we have '**'.

    3. Remove an optional [N] from the last condition.
       (Where N is a decimal).
       Set nth base on 'N'.
       Set nth_in_group if previous word is surrounded by ():
          (WORD)[N]

    4. Double and single quotes are removed from the ends (if matching).

    5. Split each list of conditions by "=".
       First word is the tag.
       Second word is the text (if any).
       If either starts with a tilde, then the word:
          - is treated like a pattern.
          - is case Insensitive.

    Precedence:
       If quoted and ~, left wins:
       ~"head1" => qr/"head"/,
       "~head1" => qr/head/,

## \_check\_conditions

Check if queries are valid.

## \_set\_condition\_defaults

Assigns default query options.

## \_find

Lower level find command.

## \_invert

Previous elements are inside of the child
(due to the way the tree is created).

This method walks through each child and puts
the parent in its place.

## \_render

Transforms a tree of found nodes in a simple list
or a string depending on context.

Pod::Text formatter is used for `Para` tags when `keep_all` is set.

## get\_term\_width

Determines, caches and returns the terminal width.

### Error: Unable to get Terminal Size

If terminal width cannot be detected, 80 will be assumed.

# SEE ALSO

[App::Pod](https://metacpan.org/pod/App%3A%3APod)

[Pod::LOL](https://metacpan.org/pod/Pod%3A%3ALOL)

[Pod::Text](https://metacpan.org/pod/Pod%3A%3AText)

# AUTHOR

Tim Potapov, `<tim.potapov[AT]gmail.com>`

# BUGS

Please report any bugs or feature requests to [https://github.com/poti1/pod-query/issues](https://github.com/poti1/pod-query/issues).

# CAVEAT

Nothing to report.

# SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Pod::Query

You can also look for information at:

[https://metacpan.org/pod/Pod::Query](https://metacpan.org/pod/Pod::Query)
[https://github.com/poti1/pod-query](https://github.com/poti1/pod-query)

# ACKNOWLEDGEMENTS

TBD

# LICENSE AND COPYRIGHT

This software is Copyright (c) 2022 by Tim Potapov.

This is free software, licensed under:

    The Artistic License 2.0 (GPL Compatible)