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