NAME

Perl::ToPerl6::Transformer - Base class for all Transformer modules.

DESCRIPTION

Perl::ToPerl6::Transformer is the abstract base class for all Transformer objects. If you're developing your own Transformers, your job is to implement and override its methods in a subclass. To work with the Perl::ToPerl6 engine, your implementation must behave as described below. For a detailed explanation on how to make new Transformer modules, please see the Perl::ToPerl6::DEVELOPER document included in this distribution.

INTERFACE SUPPORT

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

METHODS

new( ... )

Don't call this. As a Transformer author, do not implement this. Use the initialize_if_enabled() method for your Transformer setup. See the developer documentation for more.

initialize_if_enabled( $config )

This receives an instance of Perl::ToPerl6::TransformerConfig as a parameter, and is only invoked if this Transformer is enabled by the user. Thus, this is the preferred place for subclasses to do any initialization.

Implementations of this method should return a boolean value indicating whether the Transformer should continue to be enabled. For most subclasses, this will always be $TRUE. Transformers that depend upon external modules or other system facilities that may or may not be available should test for the availability of these dependencies and return $FALSE if they are not.

prepare_to_scan_document( $document )

The parameter is about to be scanned by this Transformer. Whatever this Transformer wants to do in terms of preparation should happen here. Returns a boolean value indicating whether the document should be scanned at all; if this is a false value, this Transformer won't be applied to the document. By default, does nothing but return $TRUE.

violates( $element, $document )

Given a PPI::Element and a PPI::Document, returns one or more Perl::ToPerl6::Transformation objects if the $element violates this Transformer. If there are no transformations, then it returns an empty list. If the Transformer encounters an exception, then it should croak with an error message and let the caller decide how to handle it.

transform() is an abstract method and it will abort if you attempt to invoke it directly. It is the heart of all Transformer modules, and your subclass must override this method.

transformation( $description, $explanation, $element )

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.

These are the same as the constructor to Perl::ToPerl6::Transformation, but without the necessity. The Transformer itself knows the necessity.

new_parameter_value_exception( $option_name, $option_value, $source, $message_suffix )

Create a Perl::ToPerl6::Exception::Configuration::Option::Transformer::ParameterValue for this Transformer.

throw_parameter_value_exception( $option_name, $option_value, $source, $message_suffix )

Create and throw a Perl::ToPerl6::Exception::Configuration::Option::Transformer::ParameterValue. Useful in parameter parser implementations.

get_long_name()

Return the full package name of this transformer.

get_short_name()

Return the name of this transformer without the "Perl::ToPerl6::Transformer::" prefix.

is_enabled()

Answer whether this transformer is really active or not. Returns a true value if it is, a false, yet defined, value if it isn't, and an undefined value if it hasn't yet been decided whether it will be.

applies_to()

Returns a list of the names of PPI classes that this Transformer cares about. By default, the result is PPI::Element. Overriding this method in Transformer subclasses should lead to significant performance increases.

default_necessity()

Returns the default necessity for violating this Transformer. See the $NECESSITY constants in Perl::ToPerl6::Utils for an enumeration of possible necessity values. By default, this method returns $NECESSITY_LOWEST. Authors of Perl::ToPerl6::Transformer subclasses should override this method to return a value that they feel is appropriate for their Transformer. In general, Polices that are widely accepted or tend to prevent bugs should have a higher necessity than those that are more subjective or cosmetic in nature.

get_necessity()

Returns the necessity of violating this Transformer. If the necessity has not been explicitly defined by calling set_necessity, then the default_necessity is returned. See the $NECESSITY constants in Perl::ToPerl6::Utils for an enumeration of possible necessity values.

set_necessity( $N )

Sets the necessity for violating this Transformer. Clients of Perl::ToPerl6::Transformer objects can call this method to assign a different necessity to the Transformer if they don't agree with the default_necessity. See the $NECESSITY constants in Perl::ToPerl6::Utils for an enumeration of possible values.

default_themes()

Returns a sorted list of the default themes associated with this Transformer. The default method returns an empty list. Transformer authors should override this method to return a list of themes that are appropriate for their transformer.

get_themes()

Returns a sorted list of the themes associated with this Transformer. If you haven't added themes or set the themes explicitly, this method just returns the default themes.

set_themes( @THEME_LIST )

Sets the themes associated with this Transformer. Any existing themes are overwritten. Duplicate themes will be removed.

add_themes( @THEME_LIST )

Appends additional themes to this Transformer. Any existing themes are preserved. Duplicate themes will be removed.

get_abstract()

Retrieve the abstract for this transformer (the part of the NAME section of the POD after the module name), if it is available.

get_raw_abstract()

Retrieve the abstract for this transformer (the part of the NAME section of the POD after the module name), if it is available, in the unparsed form.

parameter_metadata_available()

Returns whether information about the parameters is available.

get_parameters()

Returns a reference to an array containing instances of Perl::ToPerl6::TransformerParameter.

Note that this will return an empty list if the parameters for this transformer are unknown. In order to differentiate between this circumstance and the one where this transformer does not take any parameters, it is necessary to call parameter_metadata_available().

set_format( $format )

Class method. Sets the format for all Transformer objects when they are evaluated in string context. The default is "%p\n". See "OVERLOADS" for formatting options.

get_format()

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

to_string()

Returns a string representation of the transformer. The content of the string depends on the current value returned by get_format(). See "OVERLOADS" for the details.

DOCUMENTATION

When your Transformer module first uses Perl::ToPerl6::Transformation, it will try and extract the DESCRIPTION section of your Transformer module's POD. This information is displayed by Perl::ToPerl6 if the verbosity level is set accordingly. Therefore, please include a DESCRIPTION section in the POD for any Transformer modules that you author. Thanks.

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:

%P

Name of the Transformer module.

%p

Name of the Transformer without the Perl::ToPerl6::Transformer:: prefix.

%a

The transformer abstract.

%O

List of supported transformer parameters. Takes an option of a format string for "to_formatted_string" in Perl::ToPerl6::TransformerParameter. For example, this can be used like %{%n - %d\n}O to get a list of parameter names followed by their descriptions.

%U

A message stating that the parameters for the transformer are unknown if parameter_metadata_available() returns false. Takes an option of what the message should be, which defaults to "Cannot programmatically discover what parameters this transformer takes.". The value of this option is interpolated in order to expand the standard escape sequences (\n, \t, etc.).

%S

The default necessity level of the transformer.

%s

The current necessity level of the transformer.

%T

The default themes for the transformer.

%t

The current themes for the transformer.

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.