RFC: New module "Module::Bundled::Files"

I've written a module, tentatively named Module::Bundled::Files. A
section of the POD docs is included to (attempt) to explain it's
purpose. It was inspired by the __tt_template_name() function in
CGI::Application::Plugin::TT.

I'm looking for any comments, particularly if anyone can suggest a
better name for the module.

Darcs repo and tar.gz is available at
http://kemitix.net/repos/module-bundled-files/

Thanks,
Paul

NAME
Module::Bundled::Files - Access files bundled with Module

VERSION
Version 0.01

SYNOPSIS
Access files installed with your module without needing to
specify an
install location on the target filesystem.

Setup

In Build.PL:

my $build = new Module::Build(...);
map{$build->add_build_element($_);}
qw{txt html tmpl};
# installs all .txt, .html and .tmpl files in the lib/ tree

Object-Oriented Interface

use base qw{Module::Bundled::Files};

if($self->mbf_exists('data.txt')){...}

my $filename = $self->mbf_path('data.txt');
open my $fh, '<', $filename or die $@;

my $fh = $self->mbf_open('data.txt');
while(<$fh>)
{
...
}

my $data = $self->mbf_read('data.txt');

Non-Object-Oriented Interface

use Module::Bundled::Files qw{:all};
my $object = new Other::Object;

if(mbf_exists($other,'otherfile.txt')){...}

my $filename = mbf_path($object,'otherfile.txt');

open my $fh, '<', $filename or die $@;

my $fh = mbf_open($object,'otherfile.txt');
while(<$fh>)
{
...
}

my $data = mbf_read($object,'otherfile.txt');

DESCRIPTION
This module provides an simple method of accessing files that
need to
be bundled with a module.

For example, a module My::Module, which needs to access a
seperate file
data.txt.

In your development directory you would place your data.txt in
your
lib/My/Module/ directory.

lib/
My/
Module.pm
Module/
data.txt

Using add_build_element(...) in your Build.PL file allows the
data.txt
file to be installed in the same relative location.

The file(s) can then be accessed using the mbf_* functions
provided by
this module.

Re: RFC: New module "Module::Bundled::Files"

"Paul Campbell" writes:

> I've written a module, tentatively named Module::Bundled::Files. A
> section of the POD docs is included to (attempt) to explain it's
> purpose. It was inspired by the __tt_template_name() function in
> CGI::Application::Plugin::TT.
>
> I'm looking for any comments, particularly if anyone can suggest a
> better name for the module.
>
> Darcs repo and tar.gz is available at
> http://kemitix.net/repos/module-bundled-files/

The module does not pass tests with 5.8.0:

t/00-load...........NOK 1
# Failed test (t/00-load.t at line 6)
# Tried to use 'Module::Bundled::Files'.
# Error: "import" is not exported by the Exporter module
# Can't continue after import errors at /tmp/module-bundled-files/blib/lib/Module/Bundled/Files.pm line 112
# BEGIN failed--compilation aborted at t/00-load.t line 6.
# Compilation failed in require at (eval 3) line 2.
# BEGIN failed--compilation aborted at (eval 3) line 2.
Use of uninitialized value in concatenation (.) or string at t/00-load.t line 9.
# Testing Module::Bundled::Files , Perl 5.008, /usr/local/bin/perl
# Looks like you failed 1 test of 1.
t/00-load...........dubious
Test returned status 1 (wstat 256, 0x100)
DIED. FAILED test 1
Failed 1/1 tests, 0.00% okay
etc.

Support for earlier perl versions (maybe down to 5.005) would be
preferable --- at least the module is not very complicated.

The object oriented interface and the usage of object references to
get the path of the data files will break if using inheritance. Just
try the "empty subclass test" as described in perltoot.pod. I would
entirely drop the OO interface and rewrite the functional interface to
use package/module names instead of object references.

I would also drop all convenience functions like mbf_exists, _open,
_read ... the only function which really is necessary is mbf_path.

As I mostly write Tk programs, I already use the (non- or
under-documented) function Tk::findINC for similar functionality:

$mw->Photo(-file => Tk::findINC($image));

Regards,
Slaven

--
Slaven Rezic - slaven rezic de
BBBike - route planner for cyclists in Berlin
WWW version: http://www.bbbike.de
Perl/Tk version for Unix and Windows: http://bbbike.sourceforge.net

Re: RFC: New module "Module::Bundled::Files"

Thanks for the bug report.

I've changed the Exporter module syntax back to a pre perl-5.8.3 form
which looks compatible with perl-5.005 (according to the CPAN docs).

Breaking when using inheritance is a good point. I hadn't thought of
that. I think I'd rather try to add support for inheriting modules to
be able to override files. So if the specific class doesn't provide a
requested file, we would walk up the inheritance tree till, hopefully,
one is found that does.

The convenience functions aren't exported by default. use
Module::Bundled::Files 'mbf_path'; would give you the level of
namespace polution you suggest.

I'll be having a look at Tk::findINC() to see if they do anything
interesting there that I can steal.

Thanks for your comments.

Re: RFC: New module "Module::Bundled::Files"

Support for inheriting classes to be able to override files has been
added.

Thus:

My::Module provides files data.txt and image.png.
My::OtherModule inherits My::Module and provides it's own image.png.

lib/
My/
Module.pm
Module/
data.txt
image.png
OtherModule.pm
OtherModule/
image.png

If an object created from My::OtherObject asks for image.png it will be
returned My::OtherModule's version of the file
(My/OtherModule/image.png), while a request for data.txt would return
the My::Module file (My/Module/data.txt).