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

Module-Bundled-Files documentation Contained in the Module-Bundled-Files distribution.

Index

Code Index:

NAME

Top

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

VERSION

Top

Version 0.03

SYNOPSIS

Top

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 found in the lib/ tree

Create files:

  Build.PL
  lib/
    My/
      Module.pm
      Module/
        index.html
        data.txt
        form.tmpl

Object-Oriented Interface

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

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

  my $filename = $self->mbf_path('data.txt');
  # $filename = '/usr/local/share/perl/5.8.7/My/Module/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

Top

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

Top

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

Top

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

Top

Paul Campbell, <kemitix@gmail.com>

BUGS

Top

Please report any bugs or feature requests to bug-module-bundled-files@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Bundled-Files. I will be notified, and then you will automatically be notified of progress on your bug as I make changes.

#=head1 ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Top

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.

Module-Bundled-Files documentation Contained in the Module-Bundled-Files distribution. 
#!/usr/bin/perl -w
package Module::Bundled::Files;

use warnings;
use strict;

use File::Spec::Functions;
use Class::ISA;


our $VERSION = '0.03';


use base 'Exporter';
our @EXPORT_OK = qw{mbf_validate mbf_dir mbf_exists mbf_path mbf_open mbf_read};
our %EXPORT_TAGS = (all => [@EXPORT_OK]);


sub mbf_validate($;$)
{
    my $filename = shift;
    $filename = shift if ref($filename) && $filename->isa('Module::Bundled::Files');
    die "Illegal reference to parent directory in filename '$filename'" 
        if $filename =~ /\.\./;
    return 1;
}


sub mbf_dir(;$)
{
    my $module = shift;
    $module = ref($module) if ref($module);
    # Convert My::Module into My/Module.pm
    # %INC uses '/' for delimiters, even on Windows
    my $shortpath = join('/',split(/::/,$module)).'.pm';
    die "Short path not generated for $module" unless $shortpath;
    # Find the complete path for the module
    my $fullpath = $INC{$shortpath};
    die "Full path not found in \%INC for '$shortpath'" unless $fullpath;
    # convert the '/' delimiters in %INC to those used by the OS
    $fullpath = catfile(split(m|/|,$fullpath));
    # Strip the .pm to get the directory name
    $fullpath =~ s|\.pm$||;
    return $fullpath;
}


sub mbf_exists($;$)
{
    my $module = shift;
    my $filename = shift;
    mbf_validate($module,$filename);
    my $dir = mbf_dir($module);
    my $fullpath = catfile($dir,$filename);
    return stat($fullpath) ? 1 : 0;
}


sub mbf_path($;$)
{
    my $module = shift;
    my $filename = shift;
    unless( mbf_exists($module,$filename) )
    {
        my $found = 0;
        my $module_name = ref($module) || $module;
        foreach my $module_isa (Class::ISA::super_path($module_name))
        {
            if( mbf_exists($module_isa,$filename) )
            {
                $module = $module_isa;
                $found++;
                last;
            }
        }
        die "File not found: '$filename' for module '$module_name'"
            unless $found;
    }
    my $dir = mbf_dir($module);
    my $fullpath = catfile($dir,$filename);
    return $fullpath;
}


sub mbf_open($;$)
{
    my $module = shift;
    my $filename = shift;
    my $fullpath = mbf_path($module,$filename);
    open my $fh, '<', $fullpath
        or die "Could not open file '$filename': ".$@;
    return $fh;
}


sub mbf_read($;$)
{
    my $module = shift;
    my $filename = shift;
    my $fh = mbf_open($module,$filename);
    my $content = '';
    local $_;
    while(<$fh>){$content.=$_;}
    return $content;
}


1; # End of Module::Bundled::Files