/ 
PPIx-Shorthand-v1.2.0
River stage one • 2 direct dependents • 2 total dependents
/ PPIx::Shorthand

NAME

PPIx::Shorthand - Translation of short names to PPI::Element classes.

VERSION

This document describes PPIx::Shorthand version 1.2.0.

SYNOPSIS

use PPIx::Shorthand qw< get_ppi_class >;

# All of these assign 'PPI::Statement::Include' to $class_name.
my $class_name = get_ppi_class('include');
my $class_name = get_ppi_class('statementinclude');
my $class_name = get_ppi_class('statement-include');
my $class_name = get_ppi_class('sTatEMenT::inclUde');
my $class_name = get_ppi_class('PPI::Statement::Include');

my $shorthand = PPIx::Shorthand->new();
$shorthand->remove_class_translation('token');
$shorthand->add_class_translation( t => 'PPI::Token' );
my $other_class_name = $shorthand->get_class('t');

DESCRIPTION

When developing tools that allow a user to specify a subclass of PPI::Element, the long names of the classes don't make for ease of use. This module exists to provide common short names for these classes so that users don't need to learn different ones for different tools.

TRANSLATIONS

All translations are case-insensitive.

The translations include the identity ones, i.e. 'PPI::Token::Number::Float' maps to 'PPI::Token::Number::Float'.

The translations include the class names without the "PPI::" prefix, i.e. 'Token::Number::Float' maps to 'PPI::Token::Number::Float'.

The translations include the class names without the "PPI::" prefix and with the following delimiters instead of double colons: _, -, ., :, and the empty string. So 'statement_variable', 'statement-variable', 'statement.variable', 'statement:variable', and 'statementvariable' all map to 'PPI::Statement::Variable'.

The translations include the base name of the classes. The non-unique base names translate to the corresponding 'PPI::Token::' subclass; presently the non-unique names are 'Data', 'End', 'Regexp', 'Structure', and 'Unknown'. So, 'exp' translates to 'PPI::Token::Number::Float::Exp' and 'regexp' translates to 'PPI::Token::Regexp'.

The translations include all of the above, pluralized, with the exception of "PPI::Token::Word" because it conflicts with "PPI::Token::QuoteLike::Words".

The translations are based upon the classes in PPI v1.208. While currently supported, the translations for PPI::Token::DashedWord may disappear in the future based upon the evolution of PPI itself.

INTERFACE

Procedural

get_ppi_class($name)

Attempts to find a PPI::Element subclass for the given string, in a case-insensitive manner. Returns nothing if no matching value is found.

The translation is read-only via the procedural interface. If you want to modify the translation, use the object-oriented interface.

Object-Oriented

new()

Create a new PPIx::Shorthand instance.

get_class($name)

Attempts to find a PPI::Element subclass for the given string, in a case-insensitive manner. Returns nothing if no matching value is found.

add_class_translation( $name => $ppi_element_subclass )

Give an alternative name for the class. If you specify a name that already has a translation, this method will overwrite it.

remove_class_translation( $name )

Stop translating the specified name.

DIAGNOSTICS

"%s" is not a known subclass of PPI::Element.

An attempt was made via add_class_translation() to create a translation to a PPI::Element subclass that this module doesn't know about.

"%s" is not a known translation.

An attempt was made via remove_class_translation() to delete a translation that does not exist.

Must specify PPI class.

A subroutine/method was invoked without a value for the PPI class parameter.

Must specify name.

A subroutine/method was invoked without a value for the name parameter.

CONFIGURATION AND ENVIRONMENT

PPIx::Shorthand requires no configuration files or environment variables.

DEPENDENCIES

Readonly, version

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-ppix-shorthand@rt.cpan.org, or through the web interface at http://rt.cpan.org.

SEE ALSO

App::Grepl, PPIx::Grep

AUTHOR

Elliot Shank <perl@galumph.com>

LICENSE AND COPYRIGHT

Copyright ©2008-2010, Elliot Shank <perl@galumph.com>.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic and perlgpl.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.