NAME

Devel::Isa::Explainer - Pretty Print Hierarchies of Subs in Packages

VERSION

version 0.002001

SYNOPSIS

use Devel::Isa::Explainer qw( explain_isa );

# Load it yourself first
print explain_isa('Dist::Zilla::Dist::Builder');

DESCRIPTION

This module is a simple tool for quickly visualizing inheritance hierarchies to quickly see what subs are available for a given package, or to ascertain where a given sub you might see in use is coming from.

This module does not concern itself with any of the fanciness of Roles, and instead, relies entirely on standard Perl5 Object Model infrastructure. ( Roles are effectively invisible at run-time as they appear as composed subs in the corresponding class )

Conventional Sub Name Interpretation

This module utilizes a cultural understanding of the naming conventions that are standardized on CPAN, and applies color highlighting to make them stand out.

For instance:

• all lower case subs are assumed to be normal methods/functions/subs

• all upper case subs are assumed to be used for semi-private inter-module interoperability ( for instance, DESTROY, BUILDALL )

• subs with a leading underscore are assumed to be private methods/functions/subs

• subs with CamelCase naming are assumed to be uncleaned Moose/Types::Tiny type-constraint subs

• subs starting with is_ to_ and assert_ followed by CamelCase lettering are assumed to be uncleaned type-constraint utility subs.

Inheritance Aware Sub Shadowing

This module analyses the presence of "Shadowed" subs by indicating specifically when a given module has an overriding sub in higher context.

We don't do any work to ascertain if in fact the higher sub chains to the shadowed one or not, but we merely indicate that there's a possibility, and show where the default method call will get routed on the relevant class.

FUNCTIONS

explain_isa

print explain_isa( $loaded_module_name );

Returns a pretty-printed formatted description of the class referenced by $loaded_module_name

DIAGNOSTICS

(id: Devel::Isa::Explainer#1)

explain_isa() expects exactly one argument, a (loaded) module name to print the ISA hierarchy of. You passed either 0 arguments ( too few to be useful ) or too many ( Which silently ignoring might block us from adding future enhancements )

(id: Devel::Isa::Explainer#2)

explain_isa( $argument ) expects $argument to be a defined module name, but you somehow managed to pass undef. I don't think there is a legitimate use case for a module with an undefined name, but I could be wrong.

File a bug if you have proof.

(id: Devel::Isa::Explainer#3)

explain_isa( $argument ) expects $argument to have a positive length, but you passed an empty string. Again as with (id: Devel::Isa::Explainer#2), file a bug if there's a real use case here that I missed.

(id: Devel::Isa::Explainer#4)

explain_isa( $argument ) expects $argument to be a normal scalar value describing a module name, but you passed a reference of some kind.

This is presently an error to protect it for future possible use.

(id: Devel::Isa::Explainer#5)

When trying to extract subs and inheritance from the module name you passed in explain_isa( $module_name ), no subs could be found, there were no parent classes, and the module name in question had never been registered in %INC by Perl.

This indicates that the most likely thing that happened was you forgot to either require the module in question first, or you forgot to locally define that package with some classes prior to calling explain_isa( $module_name )

AUTHOR

Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Kent Fredric <kentfredric@gmail.com>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.