.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Module::Bundled::Files 3pm"
.TH Module::Bundled::Files 3pm "2022-12-07" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Module::Bundled::Files \- Access files bundled with Module
.SH "VERSION"
.IX Header "VERSION"
Version 0.03
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Access files installed with your module without needing to specify
an install location on the target filesystem.
.SS "Setup"
.IX Subsection "Setup"
In \fIBuild.PL\fR:
.PP
.Vb 4
\&  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
.Ve
.PP
Create files:
.PP
.Vb 8
\&  Build.PL
\&  lib/
\&    My/
\&      Module.pm
\&      Module/
\&        index.html
\&        data.txt
\&        form.tmpl
.Ve
.SS "Object-Oriented Interface"
.IX Subsection "Object-Oriented Interface"
.Vb 1
\&  use base qw{Module::Bundled::Files};
\&  
\&  if($self\->mbf_exists(\*(Aqdata.txt\*(Aq)){...}
\&  
\&  my $filename = $self\->mbf_path(\*(Aqdata.txt\*(Aq);
\&  # $filename = \*(Aq/usr/local/share/perl/5.8.7/My/Module/data.txt\*(Aq;
\&  open my $fh, \*(Aq<\*(Aq, $filename or die $@;
\&  
\&  my $fh = $self\->mbf_open(\*(Aqdata.txt\*(Aq);
\&  while(<$fh>)
\&  {
\&    ...
\&  }
\&  
\&  my $data = $self\->mbf_read(\*(Aqdata.txt\*(Aq);
.Ve
.SS "Non-Object-Oriented Interface"
.IX Subsection "Non-Object-Oriented Interface"
.Vb 2
\&  use Module::Bundled::Files qw{:all};
\&  my $object = new Other::Object;
\&
\&  if(mf_exists($other,\*(Aqotherfile.txt\*(Aq)){...}
\&
\&  my $filename = mbf_path($object,\*(Aqotherfile.txt\*(Aq);
\&
\&  open my $fh, \*(Aq<\*(Aq, $filename or die $@;
\&  
\&  my $fh = mbf_open($object,\*(Aqotherfile.txt\*(Aq);
\&  while(<$fh>)
\&  {
\&    ...
\&  }
\&  
\&  my $data = mbf_read($object,\*(Aqotherfile.txt\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides an simple method of accessing files that need to be 
bundled with a module.
.PP
For example, a module My::Module, which needs to access a separate file 
\&\fIdata.txt\fR.
.PP
In your development directory you would place your \fIdata.txt\fR in your 
\&\fIlib/My/Module/\fR directory.
.PP
.Vb 5
\&  lib/
\&    My/
\&      Module.pm
\&      Module/
\&        data.txt
.Ve
.PP
Using \fIadd_build_element(...)\fR in your \fIBuild.PL\fR file allows the 
\&\fIdata.txt\fR file to be installed in the same relative location.
.PP
The file(s) can then be accessed using the \fImbf_*\fR functions provided by
this module.
.SH "EXPORT"
.IX Header "EXPORT"
The following functions can be exported if you will not be using the
Object-Oriented Interface.
.PP
.Vb 7
\&  :all
\&    mbf_validate
\&    mbf_dir
\&    mbf_exists
\&    mbf_path
\&    mbf_open
\&    mbf_read
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "mbf_validate(\s-1FILENAME\s0)"
.IX Subsection "mbf_validate(FILENAME)"
Returns true if the filename does not contain illegal sequences (i.e. '..')
.PP
Dies if filename is invalid.
.SS "mbf_dir([\s-1MODULE\s0])"
.IX Subsection "mbf_dir([MODULE])"
Returns the path of the directory where all files would be installed.
.PP
The non-OO interface requires an object reference or module name as
the only parameter.
.SS "mbf_exists([\s-1MODULE,\s0] \s-1FILENAME\s0)"
.IX Subsection "mbf_exists([MODULE,] FILENAME)"
Returns true of the named file has been bundled with the module.
.PP
The non-OO interface requires an object reference or module name as
the first parameter.
.SS "mbf_path([\s-1MODULE,\s0] \s-1FILENAME\s0)"
.IX Subsection "mbf_path([MODULE,] FILENAME)"
Returns the full path to the named file.  Dies if the file does not exist.
.PP
Will look for file in inherited classes (by reading \f(CW@ISA\fR) if the file is 
not found for the derived class.  \f(CW@ISA\fR navigation is the same as per Perl
searching for methods.  See Class::ISA for more details.
.PP
The non-OO interface requires an object reference or module name as
the first parameter.
.SS "mbf_open([\s-1MODULE,\s0] \s-1FILENAME\s0)"
.IX Subsection "mbf_open([MODULE,] FILENAME)"
Returns an open file handle for the named file.  Dies if the file does not exist.
.PP
The non-OO interface requires an object reference or module name as
the first parameter.
.SS "mbf_read([\s-1MODULE,\s0] \s-1FILENAME\s0)"
.IX Subsection "mbf_read([MODULE,] FILENAME)"
Returns the content of the named file.  Dies if the file does not exist.
.PP
The non-OO interface requires an object reference or module name as
the first parameter.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Campbell, \f(CW\*(C`<kemitix@gmail.com>\*(C'\fR
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-module\-bundled\-files@rt.cpan.org\*(C'\fR, 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.
.PP
#=head1 \s-1ACKNOWLEDGEMENTS\s0
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2005 Paul Campbell, all rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.