The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Pod-Query-0.21
River stage one • 1 direct dependent • 1 total dependent
1 ++
/ Pod::Query

NAME

Pod::Query - Query pod documents

VERSION

Version 0.21

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)