NAME

Pod::Query - Query pod documents

VERSION

Version 0.20

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

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

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

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)