Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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

Derive the package an element is defined in
https://github.com/kentnl/ppix-element-package

Last synced: 4 days ago
JSON representation

Derive the package an element is defined in

Awesome Lists containing this project

README 

        
=pod



=encoding UTF-8



=head1 NAME



PPIx::Element::Package - Derive the package an element is defined in



=head1 VERSION



version 0.001001



=head1 SYNOPSIS



  use PPI;

  use PPIx::Element::Package qw( identify_package identify_package_namespace );



  # Do your normal PPI stuff here.



  # Get the logical enclosing package or undef if one cannot be discovered

  my $package = identify_package( $element );



  # Get the name of the logical enclosing package, or main if one cannot be discovered

  my $namespace = identify_package_namespace( $element );



=head1 DESCRIPTION



This module aims to determine the scope any L<< C|PPI::Element >>

( which includes L<< C|PPI::Node >> and L<< C|PPI::Token >> ) is defined in.



It provides two utility methods as follows:



=over 4



=item C - The Logical L<<

C|PPI::Statement::Package

>> that owns the C



=item C - The name-space of the logical C<<

PPI::Statement::Package >> that owns the element.



=back



The latter of these is just a convenience wrapper on top of C that

returns C when either the owning C cannot be found,

or when the owning C's name-space is somehow undefined.



=head1 FUNCTIONS



=head2 identify_package



Upwards-Recursively identifies the logical owner C for

C<$element>.



  my $package = PPIx::Element::Package::identify_package( $element );



=head2 identify_package_namespace



Recursively find the C as per C and return the

imagined name-space associated.



  my $name = identify_package_namespace( $element );



This is mostly a convenience wrapper that returns C safely when no

package can be otherwise determined.



=head2 identify_package_in_previous_siblings



Non-Recursively find a C statement that is the nearest preceding sibling

of C<$element>.



  my $package = identify_package_in_previous_siblings( $element );



Returns the nearest C, or C if none can be

found in the siblings.



=head1 LOGIC



Here lies the assumptions that this module uses to find the C:



=over 4



=item 1. That any node that has children nodes implies a lexical scope.



=item 2. That within a given lexical scope, the first C sibling prior

to a given Element is the C package.



=item 3. In the event a given lexical scope has no C declarations

between the Element and the first child of that lexical scope, that the

C can be derived from the position of the scope itself, by re-applying

rules 1 and 2 recursively upwards until the C is reached.



=item 4. Any nodes that are C are contained I

B, that is:



  package Foo; # This Whole line is inside "Foo"

  package Bar; # This Whole line is inside "Bar"



=item 5. And subsequently, any children of a C C

(which are the tokens themselves that compose the statement) are themselves

within that package. ( This is just a logical extension of #4 ).



=back



The biggest scope I presently have for error in these assumptions is in the

assumptions about Package scope being determinable from the C document

hierarchy, which may lead to an over-eager presumption that a lexical scope

exists where one may not exist.



However, under my testing so far this approach has proven more useful and

accurate than manually traversing the tokens and only declaring scopes on

C boundaries.



=head1 SEE ALSO



=head2 C



I initially tried using L<< C|PPIx::LineToSub >>, however,

in testing it proved far too sloppy for my uses, and having no support for

lexical contexts at all and is entirely oriented on a

"new package overrides previous package" principle.



Its is also limited for my use cases in that it is entirely line oriented,

so cases like this are intractably insolvable:



  package Quux; { package Foo; baz() } bar();



Answering "what package is on this line" is not even a sensible question to

ask there.



It has however a performance advantage due to being a single-pass indexing

sweep with all subsequent checks being a simple array look-up.



=head1 THANKS



To L<< C|https://metacpan.org/author/MITHALDU >> for feedback

and code review on the initial design. All lurking bugs still present I can

take full credit for.



=head1 AUTHOR



Kent Fredric 



=head1 COPYRIGHT AND LICENSE



This software is copyright (c) 2015 by Kent Fredric .



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

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



=cut