Module...:Files(3pm)

👑 Module::Bundled::Files — the manual, but make it cute

okay bestie, so this is a page from the User Contributed Perl Documentation for Module::Bundled::Files(3pm). It's giving "how do I ship extra files with my module without losing my entire mind" energy, and honestly? iconic. let's go 💅

---

🌸 NAME 🌸

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

✨ VERSION ✨

Version 0.03

---

🦋 SYNOPSIS 🦋

Access files installed with your module without needing to specify an install location on the target filesystem. literally no more guessing where things landed. slay.

🎀 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 💜

This module provides an simple method of accessing files that need to be bundled with a module. (yes, the original says "an simple", we're keeping it, no cap)

For example, a module My::Module, which needs to access a separate 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. so it follows your module around like the loyal little file it is 🫶

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

---

🧚 EXPORT 🧚

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

• :all — exports the whole little squad:
  • 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. it will simply not tolerate that nonsense, bestie.

🌟 mbf_dir([MODULE]) 🌟

Returns the path of the directory where all files would be installed. it's giving "home address of your bundled files".

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. (yes, "true of" — the original said that, and we do not edit the ancestors)

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. so it's doing the whole family-tree detective work for you, iykyk.

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. it said what it said 😭

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

---

🍓 AUTHOR 🍓

Paul Campbell, <kemitix@gmail.com> — king behavior, honestly 👑

---

💀 BUGS 💀

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

(yes that line is just sitting there, commented out, living its best mysterious life. we don't ask questions. we simply include it. 🎀)

---

👑 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.

---

and that's the whole page, bestie! ✨🦋💖

cute little sign-off: this gem came from the User Contributed Perl Documentation shelf, riding along with perl v5.36.0, dated 2022-12-07. obsessed. periodt 💅🌸