https://github.com/kentnl/devel-isa-explainer

Pretty Print Function Hierarchies of Classes
https://github.com/kentnl/devel-isa-explainer

Last synced: 4 days ago
JSON representation

Pretty Print Function Hierarchies of Classes

• Host: GitHub
• URL: https://github.com/kentnl/devel-isa-explainer
• Owner: kentnl
• License: other
• Created: 2016-03-27T15:59:45.000Z (over 8 years ago)
• Default Branch: master
• Last Pushed: 2016-06-29T00:27:08.000Z (over 8 years ago)
• Last Synced: 2023-08-20T22:25:41.720Z (about 1 year ago)
• Language: Perl
• Size: 172 KB
• Stars: 1
• Watchers: 2
• Forks: 0
• Open Issues: 9
• Metadata Files:
  • Readme: README.mkdn
  • Changelog: Changes
  • Contributing: CONTRIBUTING.pod
  • License: LICENSE

Awesome Lists containing this project

README

        
# NAME

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

# VERSION

version 0.002901

# 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)`](#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 `sub`s 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 

# COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Kent Fredric .

This is free software; you can redistribute it and/or modify it under

the same terms as the Perl 5 programming language system itself.