local-lib5/lib/perl5/PPI/Statement/Package.pm

   1 package PPI::Statement::Package;
   2
   3 =pod
   4
   5 =head1 NAME
   6
   7 PPI::Statement::Package - A package statement
   8
   9 =head1 INHERITANCE
  10
  11   PPI::Statement::Package
  12   isa PPI::Statement
  13       isa PPI::Node
  14           isa PPI::Element
  15
  16 =head1 DESCRIPTION
  17
  18 Most L<PPI::Statement> subclasses are assigned based on the value of the
  19 first token or word found in the statement. When PPI encounters a statement
  20 starting with 'package', it converts it to a C<PPI::Statement::Package>
  21 object.
  22
  23 When working with package statements, please remember that packages only
  24 exist within their scope, and proper support for scoping has yet to be
  25 completed in PPI.
  26
  27 However, if the immediate parent of the package statement is the
  28 top level L<PPI::Document> object, then it can be considered to define
  29 everything found until the next top-level "file scoped" package statement.
  30
  31 A file may, however, contain nested temporary package, in which case you
  32 are mostly on your own :)
  33
  34 =head1 METHODS
  35
  36 C<PPI::Statement::Package> has a number of methods in addition to the standard
  37 L<PPI::Statement>, L<PPI::Node> and L<PPI::Element> methods.
  38
  39 =cut
  40
  41 use strict;
  42 use PPI::Statement ();
  43
  44 use vars qw{$VERSION @ISA};
  45 BEGIN {
  46         $VERSION = '1.206';
  47         @ISA     = 'PPI::Statement';
  48 }
  49
  50 =pod
  51
  52 =head2 namespace
  53
  54 Most package declarations are simple, and just look something like
  55
  56   package Foo::Bar;
  57
  58 The C<namespace> method returns the name of the declared package, in the
  59 above case 'Foo::Bar'. It returns this exactly as written and does not
  60 attempt to clean up or resolve things like ::Foo to main::Foo.
  61
  62 If the package statement is done any different way, it returns false.
  63
  64 =cut
  65
  66 sub namespace {
  67         my $self = shift;
  68         my $namespace = $self->schild(1) or return '';
  69         $namespace->isa('PPI::Token::Word')
  70                 ? $namespace->content
  71                 : '';
  72 }
  73
  74 =pod
  75
  76 =head2 file_scoped
  77
  78 Regardless of whether it is named or not, the C<file_scoped> method will
  79 test to see if the package declaration is a top level "file scoped"
  80 statement or not, based on its location.
  81
  82 In general, returns true if it is a "file scoped" package declaration with
  83 an immediate parent of the top level Document, or false if not.
  84
  85 Note that if the PPI DOM tree B<does not> have a PPI::Document object at
  86 as the root element, this will return false. Likewise, it will also return
  87 false if the root element is a L<PPI::Document::Fragment>, as a fragment of
  88 a file does not represent a scope.
  89
  90 =cut
  91
  92 sub file_scoped {
  93         my $self     = shift;
  94         my ($Parent, $Document) = ($self->parent, $self->top);
  95         $Parent and $Document and $Parent == $Document
  96         and $Document->isa('PPI::Document')
  97         and ! $Document->isa('PPI::Document::Fragment');
  98 }
  99
 100 1;
 101
 102 =pod
 103
 104 =head1 SUPPORT
 105
 106 See the L<support section|PPI/SUPPORT> in the main module.
 107
 108 =head1 AUTHOR
 109
 110 Adam Kennedy E<lt>adamk@cpan.orgE<gt>
 111
 112 =head1 COPYRIGHT
 113
 114 Copyright 2001 - 2009 Adam Kennedy.
 115
 116 This program is free software; you can redistribute
 117 it and/or modify it under the same terms as Perl itself.
 118
 119 The full text of the license can be found in the
 120 LICENSE file included with this module.
 121
 122 =cut