Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
executable file 246 lines (162 sloc) 4.97 KB
package Pod::Plexus::Distribution;
# TODO - Edit pass 1 done.
use Moose;
use Template;
use Carp qw(confess croak);
use Module::Util qw(find_installed);
use Pod::Plexus::Module;
use Template::Stash;
=abstract Represent a distribution containing zero or more Pod::Pleuxs modules.
=example Pod::Plexus::Cli attribute _distribution
[% %] represents an entire code distribution. It contains zero
or more modules, each of which must contain documentation and code.
[% %] provides attributes and methods to access and manipulate
modules and their documentation.
$Template::Stash::SCALAR_OPS->{call} = sub {
my ($class, $method, @parameters) = @_;
return $class->$method(@parameters);
$Template::Stash::SCALAR_OPS->{does} = sub {
my ($class, $method) = @_;
return $class->does($method);
=attribute template
"[% %]" contains a template object that will be used to expand
variables and perhaps other things within the documentation. It's a
Text::Template object by default.
has template => (
is => 'ro',
isa => 'Template',
default => sub {
return Template->new(
STRICT => 1,
TRIM => 0,
=attribute modules_by_file
"[% %]" maps relative module paths to their corresponding
Pod::Plexus::Module objects. Paths are relative to the distribution's
root directory.
Modules use this attribute to find siblings by their relative paths.
This implementation restricts each module to hold a single class.
Multiple classes per module may be supported in the future.
=method _add_module_by_file
Associate a MODULE_OBJECT with the FILE_PATH from which it was
parsed. Don't use this directly. Instead, use the public add_file()
method, which handles cross references between files and modules.
=method _get_module_by_file
Retrieve a Pod::Plexus::Module from the distribution by its
FILE_PATH relative to the distribution's root directory.
=method has_module_by_file
[% %] determines whether the distribution contains a module
for the given FILE_PATH.
has modules_by_file => (
is => 'rw',
isa => 'HashRef[Pod::Plexus::Module]',
default => sub { { } },
traits => [ 'Hash' ],
handles => {
_add_module_by_file => 'set',
_get_module_by_file => 'get',
has_module_by_file => 'exists',
=attribute modules_by_package
[% %] holds a hash of Pod::Plexus::Module objects keyed
on their main package names. For Pod::Plexus's purposes, the main
package is defined by the first C<package> statement in the module.
=method get_known_module_objects
[% %] returns a list of known module objects.
=method get_known_module_names
[% %] returns a list of known module package names.
has modules_by_package => (
is => 'rw',
isa => 'HashRef[Pod::Plexus::Module]',
default => sub { { } },
traits => [ 'Hash' ],
handles => {
_has_module_by_package => 'exists',
_add_module_by_package => 'set',
_get_module_by_package => 'get',
get_known_module_names => 'keys',
get_known_module_objects => 'values',
=inherits Pod::Plexus::Cli attribute blame
has blame => (
is => 'rw',
isa => 'Bool',
default => 0,
=inherits Pod::Plexus::Cli attribute verbose
has verbose => (
is => 'rw',
isa => 'Bool',
default => 0,
=method add_file
[% $](MODULE_PATH) adds a file to the distribution. A
Pod::Plexus::Module is built from the contents of the file at the
relative MODULE_PATH and added to the distribution.
The get_module() accessor will retrieve the module object by either
its relative MODULE_PATH or its main package name.
sub add_file {
my ($self, $file_path) = @_;
my $module = Pod::Plexus::Module->new(
pathname => $file_path,
distribution => $self,
verbose => $self->verbose(),
blame => $self->blame(),
$self->_add_module_by_file($file_path => $module);
$self->_add_module_by_package($module->package() => $module);
=method add_module
[% %] adds a module by its MODULE_NAME. It looks up the full
path to the module, and then it calls add_file() to add that file.
sub add_module {
my ($self, $module_name) = @_;
my $path = find_installed($module_name);
croak "Can't find $module_name name" unless defined $path and length $path;
=method get_module
[% %](RELATIVE_PATH) or [% %](MAIN_PACKAGE) returns a
Pod::Plexus::Module object that matches a given RELATIVE_PATH or
MAIN_PACKAGE name. It returns undef if the module is unknoqn.
sub get_module {
my ($self, $module_key) = @_;
if ($module_key =~ /^[\w:']+$/) {
return unless $self->_has_module_by_package($module_key);
return $self->_get_module_by_package($module_key);
return unless $self->has_module_by_file($module_key);
return $self->_get_module_by_file($module_key);
no Moose;
Jump to Line
Something went wrong with that request. Please try again.