NAME

Asset::Pack - Easily pack assets into Perl Modules that can be fat-packed

VERSION

version 0.000001

SYNOPSIS

#!/usr/bin/env perl
use Asset::Pack;
# lib/MyApp/Asset/FooJS.pm will embed assets/foo.js
write_module('assets/foo.js','MyApp::Asset::FooJS','lib');
# Or better still, this discovers them all and namespaces under MyApp::Asset
find_and_pack('assets', 'MyApp::Asset");
# It also writes MyApp::Asset which is an index file

DESCRIPTION

This module allows you to construct Perl modules containing the content of arbitrary files, which may then be installed or fat-packed.

In most cases, this module is not what you want, and you should use a File::ShareDir based system instead, but File::ShareDir based systems are inherently not fat-pack friendly.

However, if you need embedded, single-file applications, aggregating not only Perl Modules, but templates, JavaScript and CSS, this tool will make some of your work easier.

If anything fails it throws an exception. This is meant for scripts that will be tended by a human (or analyzed if it fails as part of a build).

FUNCTIONS

write_module

write_module($source, $module, $libdir?, $metadata?)

write_module("./foo.js", "Foo::Bar", "./")
# ./Foo/Bar.pm now contains a uuencoded copy of foo.js

Given a source asset path, a module name and a library directory, packs the source into a module named $module and saves it in the right place relative to $libdir

Later, getting the file is simple:

use Foo::Bar;
print $Foo::Bar::content; # File Content is a string.

options:

$source - A path describing where the asset is found

$module - A target name for the generated module

$libdir [optional] - A target directory to serve as a base for modules.

Defaults to ./lib.

$metadata [optional] - A HashRef payload of additional data to store in the module.

write_index

write_index($index, $module, $libdir?, $metadata? )

write_index({ "A" => "X.js" }, "Foo::Bar", "./");

Creates a file index. This allows creation of a map of:

"Module::Name" => "/Source/Path"

Entries that will be available in a constructed module as follows:

use Module::Name;
$Module::Name::index->{ "Module::Name" } # A String Path

These generated files do NOT have a __DATA__ section

options:

$source - A path describing where the asset is found

$module - A target name for the generated module

$libdir [optional] - A target directory to serve as a base for modules.

Defaults to ./lib.

$metadata [optional] - A HashRef payload of additional data to store in the module.

find_and_pack

find_and_pack( $root_dir, $namespace_prefix, $libdir ) -> Hash

Creates copies of all the contents of $root_dir and constructs ( or reconstructs ) the relevant modules using $namespace_prefix and stores them in $libdir ( which defaults to ./lib/ )

Returns a hash detailing operations and results:

{
  ok        => [ { module => ..., file => ... }, ... ],
  unchanged => [ { module => ..., file => ... }, ... ],
  fail      => [ { module => ..., file => ..., error => ... }, ... ],
}

options:

$root_dir - The base path where the assets to be packed are stored

$namespace_prefix - A module name like My::Asset which will be used as the parent for generated modules.

$libdir [optional] - The target directory to generate the Modules in.

Defaults to ./lib.

SEE ALSO

• App::FatPacker

  App::FatPacker is the primary module Asset::Pack is targeted at. AssetPack creates Perl Modules in a format compatible with App::FatPacker to enable embedding arbitrary resources in your single-file application.

• App::Implode

  App::Implode is like App::FatPacker, except uses Carton and cpanfile's to build your app tree. This should be compatible with Asset::Pack and bugs involving it will certainly be looked into.

• App::FatPacker::Simple

  Again, Similar in intent to App::FatPacker, offering a few different features, but is more manually operated. This module may work in conjunction with it.

• Module::FatPack

  Similar goals as App::FatPacker, but not quite so well engineered. This code will probably work with that, but is at this time officially unsupported.

• Module::DataPack

  This is basically a clone of Module::FatPack except has the blobs stored in your scripts __DATA__ section instead of being a hash of strings.

  Given this module also exploits __DATA__, there may be potential risks involved with this module. And as such, this is not presently officially supported, nor has it been tested.

• Data::Embed

  Data::Embed is probably more similar than all the rest listed to what Asset::Pack does, except: it doesn't use built-in Perl mechanics, will probably not be FatPacker friendly, and its implementation relies on Data::Embed being present to extract embedded data.

  Whereas Asset::Pack is implemented as a simple Perl Module building utility, which generates independent files which will perform like native Perl Module's when used.

AUTHOR

James Laver <james.laver@gmail.com>

CONTRIBUTOR

Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by James Laver on time generously donated by Anomalio.

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