/ 
Module-Bundled-Files-0.02
River stage zero No dependents
/ Module::Bundled::Files

NAME

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

VERSION

Version 0.02

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(mf_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.

EXPORT

The following functions can be exported if you will not be using the Object-Oriented Interface.

:all
  mbf_validate
  mbf_dir
  mbf_exists
  mbf_path
  mbf_open
  mbf_read

FUNCTIONS

mbf_validate(FILENAME)

Returns true if the filename does not contain illegal sequences (i.e. '..')

Dies if filename is invalid.

mbf_dir([MODULE])

Returns the path of the directory where all files would be installed.

The non-OO interface requires an object reference or module name as the only parameter.

mbf_exists([MODULE,] FILENAME)

Returns true of the named file has been bundled with the module.

The non-OO interface requires an object reference or module name as the first parameter.

mbf_path([MODULE,] FILENAME)

Returns the full path to the named file. Dies if the file does not exist.

Will look for file in inherited classes (by reading @ISA) if the file is not found for the derived class. @ISA navigation is the same as per Perl searching for methods. See Class::ISA for more details.

The non-OO interface requires an object reference or module name as the first parameter.

mbf_open([MODULE,] FILENAME)

Returns an open file handle for the named file. Dies if the file does not exist.

The non-OO interface requires an object reference or module name as the first parameter.

mbf_read([MODULE,] FILENAME)

Returns the content of the named file. Dies if the file does not exist.

The non-OO interface requires an object reference or module name as the first parameter.

AUTHOR

Paul Campbell, <kemitix@gmail.com>

BUGS

Please report any bugs or feature requests to kemitix@gmail.com.

COPYRIGHT & LICENSE

Copyright 2005 Paul Campbell, all rights reserved.

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