/ 
Pod-Query-0.04
River stage one • 1 direct dependent • 2 total dependents
/ Pod::Query

NAME

Pod::Query - Query pod documents

VERSION

Version 0.04

SYNOPSIS

Query POD information from a file

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

$pod contains the Pod::LOL object and a tree like:

"tree" => [
   {
     "sub" => [
       {
         "tag" => "Para",
         "text" => [
           "Pod::LOL - Transform POD into a list of lists"
         ]
       }
     ],
     "tag" => "head1",
     "text" => [
       "NAME"
     ]
   },
   {
     "sub" => [
       {
         "tag" => "Para",
         "text" => [
           "Version 0.01"
         ]
       }
     ],
     "tag" => "head1",
     "text" => [
       "VERSION"
     ]
   },
   ...

Find Methods:

say $pod->find_title;
say $pod->find_method;
say $pod->find_method_summary;
say $pod->find_events;
say $pod->find(@queries);

Inline (Debugging) perl -IPod-Query/lib -MPod::Query -MMojo::Util=dumper -E "say dumper(Pod::Query->new('Pod::LOL'))"

DESCRIPTION

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

SUBROUTINES/METHODS

new

Create a new object.

_class_to_path

Given a class name, retuns the path to the pod file.

_mock_root

For debugging only. Builds a sample object.

_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

Transforms a Pod::LOL object into a structured tree.

_has_head

Check if the node has sub heads.

_make_leaf

Creates a new node (aka leaf).

_structure_over

Restructures the text for an "over-text" element.

find_title

Extracts the title information.

find_method

Extracts the complete method information.

find_method_summary

Extracts the method summary.

_is_function_call

Regex for function call parenthesis.

find_events

Extracts a list of events with a description.

Returns a list of key value pairs.

find

Generic extraction command.

context sensitive!

$pod->find(@sections)

Where each section 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.
}

# 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 ...",
# ]

_check_sections

Check if queries are valid.

_set_section_defaults

Assigns default query options.

_get_heads_regex

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

_find

Lower level find command.

_to_list

NOT USED

Converts a tree to a plain list.

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

_render_over

Specifically called for rendering "over" elements.

get_term_width

Caches and returns the terminal width.

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.

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)