The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Pod-Query-0.06
River stage one • 1 direct dependent • 1 total dependent
1 ++
/ Pod::Query

NAME

Pod::Query - Query pod documents

VERSION

Version 0.06

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

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

TODO: Need to clean this up and possibly restructure.

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

CAVEAT

These options to _find() appear to only be currently working if set to o or -1: nth nth_group

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)