view release on metacpan or  search on metacpan

lib/Perl/ToPerl6/Annotation.pm  view on Meta::CPAN

    $sib->logical_line_number() == $annotation_line
        and return 1;

    # If the sibling is a node, we may have an annotation on one line of a
    # statement that was split over multiple lines. So we descend through the
    # children, keeping the last significant child of each, until we bottom
    # out. If the ultimate significant descendant is on the same line as the
    # annotation, we accept the annotation as a single-line annotation.
    if ( $sib->isa( 'PPI::Node' ) &&
        $sib->logical_line_number() < $annotation_line
    ) {
        my $neighbor = $sib;
        while ( $neighbor->isa( 'PPI::Node' )
                and my $kid = $neighbor->schild( $LAST_ELEMENT ) ) {
            $neighbor = $kid;
        }
        if ( $neighbor &&
            $neighbor->logical_line_number() == $annotation_line
        ) {
            return 1;
        }
    }

    # We do not understand any other sort of single-line annotation. Accepting
    # the annotation as such (if it is) is Someone Else's Problem.
    return 0;
}

#-----------------------------------------------------------------------------

sub _parse_annotation {

    my ($annotation_element) = @_;

    #############################################################################
    # This regex captures the list of Transformer name patterns that are to be
    # disabled.  It is generally assumed that the element has already been
    # verified as a no-mogrify annotation.  So if this regex does not match,
    # then it implies that all Transformers are to be disabled.
    #
    my $no_mogrify = qr{\#\# \s* no \s+ mogrify \s* (?:qw)? [("'] ([\s\w:,]+) }xms;
    #                  -------------------------- ------- ----- -----------
    #                                 |              |      |        |
    #   "## no mogrify" with optional spaces          |      |        |
    #                                                |      |        |
    #             Transformer list may be prefixed with "qw"     |        |
    #                                                       |        |
    #         Optional Transformer list must begin with one of these      |
    #                                                                |
    #                 Capture entire Transformer list (with delimiters) here
    #
    #############################################################################

    my @disabled_transformer_names = ();
    if ( my ($patterns_string) = $annotation_element =~ $no_mogrify ) {

        # Compose the specified modules into a regex alternation.  Wrap each
        # in a no-capturing group to permit "|" in the modules specification.

        my @transformer_name_patterns = grep { $_ ne $EMPTY }
            split m{\s *[,\s] \s*}xms, $patterns_string;
        my $re = join $PIPE, map {"(?:$_)"} @transformer_name_patterns;
        my @site_transformer_names = Perl::ToPerl6::TransformerFactory::site_transformer_names();
        @disabled_transformer_names = grep {m/$re/ixms} @site_transformer_names;

        # It is possible that the Transformer patterns listed in the annotation do not
        # match any of the site transformer names.  This could happen when running
        # on a machine that does not have the same set of Transformers as the
        # author.
        # So we must return something here, otherwise all Transformers will be
        # disabled.  We probably need to add a mechanism to (optionally) warn
        # about this, just to help the author avoid writing invalid Transformer names.

        if (not @disabled_transformer_names) {
            @disabled_transformer_names = @transformer_name_patterns;
        }
    }

    return hashify(@disabled_transformer_names);
}

#-----------------------------------------------------------------------------

1;

__END__

=pod

=head1 NAME

Perl::ToPerl6::Annotation - A "## no mogrify" annotation in a document.


=head1 SYNOPSIS

  use Perl::ToPerl6::Annotation;
  $annotation = Perl::ToPerl6::Annotation->new( -element => $no_mogrify_ppi_element );

  $bool = $annotation->disables_line( $number );
  $bool = $annotation->disables_transformer( $transformer_object );
  $bool = $annotation->disables_all_transformers();

  ($start, $end) = $annotation->effective_range();
  @disabled_transformer_names = $annotation->disabled_transformers();


=head1 DESCRIPTION

C<Perl::ToPerl6::Annotation> represents a single C<"## no mogrify">
annotation in a L<PPI:Document>.  The Annotation takes care of parsing
the annotation and keeps track of which lines and Transformers it affects.
It is intended to encapsulate the details of the no-mogrify
annotations, and to provide a way for Transformer objects to interact with
the annotations (via a L<Perl::ToPerl6::Document|Perl::ToPerl6::Document>).


=head1 INTERFACE SUPPORT

This is considered to be a non-public class.  Its interface is subject
to change without notice.