view release on metacpan or  search on metacpan

lib/PPR/X.pm  view on Meta::CPAN

}

sub _croak {
    require Carp;
    Carp::croak(@_);
}

sub _report {
    state $CONTEXT_WIDTH = 20;
    state $BUFFER = q{ } x $CONTEXT_WIDTH;
    state $depth = 0;
    my ($msg, $increment) = @_;
    $depth++ if $increment;
    my $at = pos();
    my $str = $BUFFER . $_ . $BUFFER;
    my $pre  = substr($str, $at,                $CONTEXT_WIDTH);
    my $post = substr($str, $at+$CONTEXT_WIDTH, $CONTEXT_WIDTH);
    tr/\n/ / for $pre, $post;
    no warnings 'utf8';
    warn sprintf("%05d ⎜%*s⎜%-*s⎜  %s%s\n",
        $at, $CONTEXT_WIDTH, $pre, $CONTEXT_WIDTH, $post, q{ } x $depth, $msg);
    $depth-- if !$increment;
}

1; # Magic true value required at end of module

__END__

=head1 NAME

PPR::X - Pattern-based Perl Recognizer


=head1 VERSION

This document describes PPR::X version 0.001009


=head1 SYNOPSIS

    use PPR::X;

    # Define a regex that will match an entire Perl document...
    my $perl_document = qr{

        # What to match            # Install the (?&PerlDocument) rule
        (?&PerlEntireDocument)     $PPR::X::GRAMMAR

    }x;


    # Define a regex that will match a single Perl block...
    my $perl_block = qr{

        # What to match...         # Install the (?&PerlBlock) rule...
        (?&PerlBlock)              $PPR::X::GRAMMAR
    }x;


    # Define a regex that will match a simple Perl extension...
    my $perl_coroutine = qr{

        # What to match...
        coro                                           (?&PerlOWS)
        (?<coro_name>  (?&PerlQualifiedIdentifier)  )  (?&PerlOWS)
        (?<coro_code>  (?&PerlBlock)                )

        # Install the necessary subrules...
        $PPR::X::GRAMMAR
    }x;


    # Define a regex that will match an integrated Perl extension...
    my $perl_with_classes = qr{

        # What to match...
        \A
            (?&PerlOWS)       # Optional whitespace (including comments)
            (?&PerlDocument)  # A full Perl document
            (?&PerlOWS)       # More optional whitespace
        \Z

        # Add a 'class' keyword into the syntax that PPR::X understands...
        (?(DEFINE)
            (?<PerlKeyword>

                    class                              (?&PerlOWS)
                    (?&PerlQualifiedIdentifier)        (?&PerlOWS)
                (?: is (?&PerlNWS) (?&PerlIdentifier)  (?&PerlOWS) )*+
                    (?&PerlBlock)
            )

            (?<kw_balanced_parens>
                \( (?: [^()]++ | (?&kw_balanced_parens) )*+ \)
            )
        )

        # Install the necessary standard subrules...
        $PPR::X::GRAMMAR
    }x;


=head1 DESCRIPTION

The PPR::X module provides a single regular expression that defines a set
of independent subpatterns suitable for matching entire Perl documents,
as well as a wide range of individual syntactic components of Perl
(i.e. statements, expressions, control blocks, variables, etc.)

The regex does not "parse" Perl (that is, it does not build a syntax
tree, like the PPI module does). Instead it simply "recognizes" standard
Perl constructs, or new syntaxes composed from Perl constructs.

Its features and capabilities therefore complement those of the PPI
module, rather than replacing them. See L<"Comparison with PPI">.


=head1 INTERFACE

=head2 Importing and using the Perl grammar regex

The PPR::X module exports no subroutines or variables,
and provides no methods. Instead, it defines a single
package variable, C<$PPR::X::GRAMMAR>, which can be
interpolated into regexes to add rules that permit
Perl constructs to be parsed: