https://github.com/kentnl/ppix-element-sub

Find subroutines associated with any element
https://github.com/kentnl/ppix-element-sub

Last synced: 4 days ago
JSON representation

Find subroutines associated with any element

• Host: GitHub
• URL: https://github.com/kentnl/ppix-element-sub
• Owner: kentnl
• License: other
• Created: 2015-10-05T08:46:10.000Z (about 9 years ago)
• Default Branch: master
• Last Pushed: 2015-10-19T14:50:43.000Z (about 9 years ago)
• Last Synced: 2023-04-16T05:55:57.123Z (over 1 year ago)
• Language: Perl
• Size: 227 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.mkdn
  • Changelog: Changes
  • Contributing: CONTRIBUTING.pod
  • License: LICENSE

Awesome Lists containing this project

README

        
# NAME

PPIx::Element::Sub - Find subroutines associated with any element.

# VERSION

version 0.001001

# SYNOPSIS

    use PPIx::Element::Sub qw( identify_associated_sub );

    my $assoc_sub = identify_associated_sub( $comment_element );

# DESCRIPTION

This module contains a handful of utility functions for finding logical `PPI`

nodes in the relative proximity of any given `element`.

It contains three primary exportable utility functions:

- `identify_sub` - Find a logically enclosing sub

- `identify_next_sub` - Find a logically succeeding sub

- `identify_associated_sub` - Find a logically enclosing sub, or if none,

a logically succeeding sub.

# FUNCTIONS

## identify\_sub

Given an `element`, ascertain the logical `sub` that contains it.

    my $sub = identify_sub( $element )

Due to structure of `PPI` documents, this is simply the nearest `parent` of

`element` that is a `sub`, which could be the `element` itself.

    package Foo;  # undef

                  # ↑

    sub           # sub 'bar'

    bar           # ↑

    {             # ↑

                  # ↑

    }             # ↑

                  # undef

Returns `undef` if no `sub` parent can be derived.

## identify\_next\_sub

Given an `element`, ascertain the _next_ `sub` that appears logically

_after_ it in the document.

    my $sub = identify_next_sub( $element );

Returns `undef` if no `next` <sub> can be found.

    package Foo;  # sub 'bar'

                  # ↑

    sub           # quux

    bar           # ↑

    {             # ↑

                  # ↑

    }             # ↑

                  # ↑

    sub quux      # undef

    {             # ↑

    }             # ↑

## identify\_associated\_sub

This is a combination of `identify_sub` and `identify_next_sub` aimed at

comments, as logically, any comment inside a `sub` pertains to the `sub`

itself, but any comment **before** a `sub` may also pertain to that `sub`.

    my $sub = identify_associated_sub( $element );

Any `element` inside a `sub` is associated with the `sub` itself.

Any `element` _before_ a `sub` is associated with the subsequent `sub`

    package Foo;  # sub 'bar'

                  # ↑

    sub           # ↑

    bar           # ↑

    {             # ↑

                  # ↑

    }             # ↑

                  # sub 'quux'

    sub quux      # ↑

    {             # ↑

    }             # ↑

                  # undef

Returns `undef` if no `sub` can be determined.

# AUTHOR

Kent Fredric <[email protected]>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Kent Fredric <[email protected]>.

This is free software; you can redistribute it and/or modify it under

the same terms as the Perl 5 programming language system itself.