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->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

Pod::LOL

Pod::Text

AUTHOR

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

BUGS

Please report any bugs or feature requests to 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://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)