NAME

Data::PackageName - OO handling of package name transformations

VERSION

0.01

SYNOPSIS

  use Data::PackageName;

  my $foo = Data::PackageName->new('Foo');
  print "$foo\n";               # prints 'Foo'

  my $foo_bar = $foo->append('Bar');
  print "$foo_bar\n";           # prints 'Foo::Bar'

  my $quuxbaz_foo_bar = $foo_bar->prepend('QuuxBaz');
  print "$quuxbaz_foo_bar\n";   # prints 'QuuxBaz::Foo::Bar'

  my $bar = $quuxbaz_foo_bar->after_start(qw( QuuxBaz ));
  print "$bar\n";               # prints 'Bar'

  # prints QuuxBaz/Foo/Bar
  print join('/', $quuxbaz_foo_bar->parts), "\n";

  # prints quux_baz/foo/bar
  print join('/', $quuxbaz_foo_bar->parts_lc), "\n";

  # create a Path::Class::File and a Path::Class::Dir
  my $file = $quuxbaz_foo_bar->filename('.yml');
  my $dir  = $quuxbaz_foo_bar->dirname;
  print "$file\n";              # prints quux_baz/foo/bar.yml
  print "$dir\n";               # prints quux_baz/foo/bar

DESCRIPTION

This module provides the mostly simple functionality of transforming package names in common ways. I didn't write it because it is complicated, but rather because I have done it once too often.

Data::PackageName is a Moose class.

ATTRIBUTES

package

A Str representing the package name, e.g. Foo::Bar. This attribute is required and must be specified at creation time.

METHODS

new

This method is inherited from Moose and only referenced here for completeness. Please consult the Moose documentation for a complete description of the object model.

  my $foo_bar = Data::PackageName->new(package => 'Foo::Bar');

The "package" attribute is required.

meta

This method is imported from Moose and only referenced here for completeness. Please consult the Moose documentation for a complete description of the object model.

The meta method returns the Moose meta class.

append

  # Foo::Bar::Baz
  my $foo_bar_baz      = $foo_bar->append('Baz');

  # Foo::Bar::Baz::Qux
  my $foo_bar_baz_qux  = $foo_bar->append('Baz::Qux'); 

  # same as above
  my $foo_bar_baz_qux2 = $foo_bar->append(qw( Baz Qux ));

This method returns a new Data::PackageName instance with its arguments appended as name parts. This means that qw( Foo Bar ) is equivalent to Foo::Bar.

prepend

Does the same as "append", but rather than appending its arguments it prepends the new package with them.

after_start

You often want to get to the part of a module name that is under a specific namespace, for example to remove the project's root namespace from the front.

  my $p = Data::PackageName->new(package => 'MyProject::Foo::Bar');
  print $p->after_start('MyProject'), "\n";     # prints 'Foo::Bar'

This method accepts values exactly as "append" and "prepend" do. The argument list will be joined with :: as separator, so it doesn't matter how you pass the names in.

parts

This splits up the namespace in parts.

  my $p = Data::PackageName->new(package => 'Foo::Bar::Baz');
  print join(', ', $p->parts), "\n"; # prints 'Foo, Bar, Baz'

transform_to_lc

This module uses a simple algorithm to transform namespace parts into their lowercase representations. For example, Foo would of course become foo, but FooBar would result in foo_bar.

  # prints 'foo'
  print Data::PackageName->transform_to_lc('Foo'), "\n";

  # prints 'foo_bar'
  print Data::PackageName->transform_to_lc('FooBar'), "\n";

parts_lc

The same as "parts", but each part will be transformed to lowercase with "transform_to_lc" first.

filename_lc

This returns a Path::Class::File object with a path containing the lower-cased parts of the package name.

  # prints 'foo/bar_baz'
  my $p = Data::PackageName->new(package => 'Foo::BarBaz');
  print $p->filename_lc, "\n";

You can optionally specify a file extension that will be appended to the filename.

  # prints 'foo/bar_baz.yml'
  my $p = Data::PackageName->new(package => 'Foo::BarBaz');
  print $p->filename_lc('.yml'), "\n";

dirname

Returns a Path::Class::Dir object containing the lower-cased parts of the package name.

  # prints 'foo/bar'
  my $p = Data::PackageName->new(package => 'Foo::Bar');
  print $p->dirname, "\n";

package_filename

This will return a Path::Class::File object containing the filename the package corresponds to, e.g. Foo::Bar would be an object with the value Foo/Bar.pm.

require

This will try to load the package via Perl's require builtin. It will return true if it loaded the file, false if it was already loaded. Exceptions raised by require will not be intercepted.

is_loaded

Returns true if the package is already loaded, false if it's not.

SEE ALSO

Moose (Underlying object system), Path::Class ("filename_lc" and "dirname" methods)

REQUIREMENTS

Moose (Underlying object system), Scalar::Util (blessed for object recreation), Path::Class::File (Filenames), Path::Class::Dir (Dirnames), Class::Inspector ("package_filename" transition and loaded-class detection)

AUTHOR AND COPYRIGHT

Robert 'phaylon' Sedlacek <rs@474.at>

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as perl itself.

cpanm Data::PackageName

perl -MCPAN -e shell
install Data::PackageName