=head1 Summary of Perl 5 AST nodes

=head2 P5AST01 - scope

=head3 Abstract

The scope node is used for every new scope in the code. It delimits
the lifespan of variables and pragmas. If a pragma is defined a new
scope is open, if a variable is redeclared, a new scope is open. An
optimizer can reuse the scope for pragma declarations in the start of
the code. But it cannot rename the re-declared variable, as the stash
can be manipulated, just emit a warning.

=head3 Elements

=over

=item scoped_declarations

a list of nodes containing scoped_variable_declaration, and
pragma_declaration. The list is ordered according to the source code.

=item outer_references

A list of nodes containing variables accessed by this scope that are
defined by the parent scope, or outer_referenced by the parent scope.

=item children

A list of statements to be run inside this scope.

=back

=head3 Example

  block_decl
  helloworld

=head2 P5AST02 - package

=head3 Abstract

The package node is the root node of a Perl5 AST. It can declare
subroutines, global variables. It inherits the "scope" node as every
package defines a new scope.

=head3 Elements

=over

=item name

The name of the package, default to 'main'.

=item package_declarations

A list of nodes containing global_variable_declaration,
subroutine_declaration and use_declaration.

=back

=head3 Example

  block_decl
  helloworld

=head2 P5AST03 - block

A block is a scope (inherits scope) defined explicitly. It tell us
that it is ok to redeclare a variable, and no warning is necessary.
It is also the boundary for closures.

=head3 Example

  block_decl

=head2 P5AST04 - variable_declaration

=head3 Abstract

The variable_declaration is the super-class for scoped and global
variable declaration. It defines how a variable can be declared.

=head3 Elements

=over

=item variable_type

One of SCALAR, ARRAY, HASH or GLOBs can only be scoped with
local, and they're always global. Even if they're scoped.

=item variable_name

An expression that defines the name of the variable. This expression
should be evaluated every time the variable is used. It can reference
another variable in this expression. An outer_references entry should
be added if the referenced variable is from the parent scope.

=item alias

Alias to be used inside the AST when referencing this variable. For
optimizing performance, it should be unique in this AST.

=back

=head2 P5AST05 - scoped_variable_declaration

=head3 Abstract

Defines a variable with a limited visibility, either by name or by
value. Inherits variable_declaration.

=head3 Elements

=over

=item variable_visibility

One of "my" or "local". If "local", it should also declare a "global"
variable.

=back

=head2 P5AST06 - global_variable_declaration

=head3 Abstract

This node causes the same effect of the "our" declaration, but appears
here even if the declaration didn't appears in the original code.

=cut