NAME

Perl::ToPerl6::Transformation - A transformation of a Transformer found in some source code.

SYNOPSIS

  use PPI;
  use Perl::ToPerl6::Transformation;

  my $elem = $doc->child(0);      # $doc is a PPI::Document object
  my $desc = 'Offending code';    # Describe the transformation
  my $expl = [1,45,67];           # Page numbers from PBP
  my $sev  = 5;                   # Necessity level of this transformation

  my $vio  = Perl::ToPerl6::Transformation->new($desc, $expl, $node, $sev);

DESCRIPTION

Perl::ToPerl6::Transformation is the generic representation of an individual Transformer transformation. Its primary purpose is to provide an abstraction layer so that clients of Perl::ToPerl6 don't have to know anything about PPI. The transformations method of all Perl::ToPerl6::Transformer subclasses must return a list of these Perl::ToPerl6::Transformation objects.

INTERFACE SUPPORT

This is considered to be a public class. Any changes to its interface will go through a deprecation cycle.

CONSTRUCTOR

new( $description, $explanation, $element, $necessity )

Returns a reference to a new Perl::ToPerl6::Transformation object. The arguments are a description of the transformation (as string), an explanation for the transformer (as string) or a series of page numbers in PBP (as an ARRAY ref), a reference to the PPI element that caused the transformation, and the necessity of the transformation (as an integer).

METHODS

description()

Returns a brief description of the specific transformation. In other words, this value may change on a per transformation basis.

explanation()

Returns an explanation of the transformer as a string or as reference to an array of page numbers in PBP. This value will generally not change based upon the specific code violating the transformer.

location()

Don't use this method. Use the line_number(), logical_line_number(), column_number(), visual_column_number(), and logical_filename() methods instead.

Returns a five-element array reference containing the line and real & virtual column and logical numbers and logical file name where this Transformation occurred, as in PPI::Element.

line_number()

Returns the physical line number that the transformation was found on.

logical_line_number()

Returns the logical line number that the transformation was found on. This can differ from the physical line number when there were #line directives in the code.

column_number()

Returns the physical column that the transformation was found at. This means that hard tab characters count as a single character.

visual_column_number()

Returns the column that the transformation was found at, as it would appear if hard tab characters were expanded, based upon the value of "tab_width [ $width ]" in PPI::Document.

filename()

Returns the path to the file where this Transformation occurred. In some cases, the path may be undefined because the source code was not read directly from a file.

logical_filename()

Returns the logical path to the file where the Transformation occurred. This can differ from filename() when there was a #line directive in the code.

necessity()

Returns the necessity of this Transformation as an integer ranging from 1 to 5, where 5 is the "most" severe.

sort_by_necessity( @transformation_objects )

If you need to sort Transformations by necessity, use this handy routine:

    @sorted = Perl::ToPerl6::Transformation::sort_by_necessity(@transformations);

sort_by_location( @transformation_objects )

If you need to sort Transformations by location, use this handy routine:

    @sorted = Perl::ToPerl6::Transformation::sort_by_location(@transformations);

diagnostics()

Returns a formatted string containing a full discussion of the motivation for and details of the Transformer module that created this Transformation. This information is automatically extracted from the DESCRIPTION section of the Transformer module's POD.

transformer()

Returns the name of the Perl::ToPerl6::Transformer that created this Transformation.

source()

Returns the string of source code that caused this exception. If the code spans multiple lines (e.g. multi-line statements, subroutines or other blocks), then only the line containing the transformation will be returned.

element_class()

Returns the PPI::Element subclass of the code that caused this exception.

set_format( $format )

Class method. Sets the format for all Transformation objects when they are evaluated in string context. The default is '%d at line %l, column %c. %e'. See "OVERLOADS" for formatting options.

get_format()

Class method. Returns the current format for all Transformation objects when they are evaluated in string context.

to_string()

Returns a string representation of this transformation. The content of the string depends on the current value of the $format package variable. See "OVERLOADS" for the details.

OVERLOADS

Perl::ToPerl6::Transformation overloads the "" operator to produce neat little messages when evaluated in string context.

Formats are a combination of literal and escape characters similar to the way sprintf works. If you want to know the specific formatting capabilities, look at String::Format. Valid escape characters are:

    Escape    Meaning
    -------   ----------------------------------------------------------------
    %c        Column number where the transformation occurred
    %d        Full diagnostic discussion of the transformation (DESCRIPTION in POD)
    %e        Explanation of transformation or page numbers in PBP
    %F        Just the name of the logical file where the transformation occurred.
    %f        Path to the logical file where the transformation occurred.
    %G        Just the name of the physical file where the transformation occurred.
    %g        Path to the physical file where the transformation occurred.
    %l        Logical line number where the transformation occurred
    %L        Physical line number where the transformation occurred
    %m        Brief description of the transformation
    %P        Full name of the Transformer module that created the transformation
    %p        Name of the Transformer without the Perl::ToPerl6::Transformer:: prefix
    %r        The string of source code that caused the transformation
    %C        The class of the PPI::Element that caused the transformation
    %s        The necessity level of the transformation

Explanation of the %F, %f, %G, %G, %l, and %L formats: Using #line directives, you can affect what perl thinks the current line number and file name are; see "Plain Old Comments (Not!)" in perlsyn for the details. Under normal circumstances, the values of %F, %f, and %l will match the values of %G, %g, and %L, respectively. In the presence of a #line directive, the values of %F, %f, and %l will change to take that directive into account. The values of %G, %g, and %L are unaffected by those directives.

Here are some examples:

    Perl::ToPerl6::Transformation::set_format("%m at line %l, column %c.\n");
    # looks like "Mixed case variable name at line 6, column 23."

    Perl::ToPerl6::Transformation::set_format("%m near '%r'\n");
    # looks like "Mixed case variable name near 'my $theGreatAnswer = 42;'"

    Perl::ToPerl6::Transformation::set_format("%l:%c:%p\n");
    # looks like "6:23:NamingConventions::Capitalization"

    Perl::ToPerl6::Transformation::set_format("%m at line %l. %e. \n%d\n");
    # looks like "Mixed case variable name at line 6.  See page 44 of PBP.
      Conway's recommended naming convention is to use lower-case words
      separated by underscores.  Well-recognized acronyms can be in ALL
      CAPS, but must be separated by underscores from other parts of the
      name."

AUTHOR

Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>

COPYRIGHT

Copyright (c) 2005-2011 Imaginative Software Systems. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.