Why not adopt me?
NAME
Asset::Pack - Easily pack assets into Perl Modules that can be fat-packed
VERSION
version 0.000007
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
require MyApp::Asset;
# ::examplejs was built from ./assets/example.js
# $filename => example.js
my $filename = $MyApp::Asset::index->{'MyApp::Asset::examplejs'};
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] - AHashRef
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] - AHashRef
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/
)
Since 0.000002: Also generates an "index" file ( See write_index
) at the name $namespace_prefix
.
Returns a hash detailing operations and results:
{
ok => [ { module => ..., file => ... }, ... ],
unchanged => [ { module => ..., file => ... }, ... ],
fail => [ { module => ..., file => ..., error => ... }, ... ],
}
Index updates will be in above list except with index => 1
instead of file =>
options:
$root_dir
- The base path where the assets to be packed are stored$namespace_prefix
- A module name likeMy::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
is the primary moduleAsset::Pack
is targeted at.AssetPack
createsPerl Modules
in a format compatible withApp::FatPacker
to enable embedding arbitrary resources in your single-file application. -
App::Implode
is likeApp::FatPacker
, except usesCarton
andcpanfile
's to build your app tree. This should be compatible withAsset::Pack
and bugs involving it will certainly be looked into. -
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. -
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. -
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
is probably more similar than all the rest listed to whatAsset::Pack
does, except: it doesn't use built-inPerl
mechanics, will probably not beFatPacker
friendly, and its implementation relies onData::Embed
being present to extract embedded data.Whereas
Asset::Pack
is implemented as a simplePerl Module
building utility, which generates independent files which will perform like nativePerl Module
's when used.
PERL LEGACY SUPPORT
At present, this distribution only works on Perl >=5.8
. ( Though the files it generates should work as-is on 5.6
)
This is mostly due to its dependencies:
Path::Tiny
is used extensively for mechanics, butPath::Tiny
does not presently (Circa0.72
) work onPerl <5.8
(details onGitHub
)Test::Differences
is used a fair bit in tests, and it won't auto-install on 5.6. But careful selection of dependencies will get you a working installSMUELLER/Data-Dumper-2.128.tar.gz
is newest version of Data::Dumper that works on5.6.2
, versions2.130_03
to2.154
presently fail.OVID/Test-Differences-0.61.tar.gz
is the newest version of Test::Differences that works on5.6.2
, versions0.61_01
to0.63
presently fail.
Test::TempDir::Tiny
is used a fair bit in tests as well, and as of0.005-TRIAL
,5.6
support is still lacking, albeit support is intended
The maintainer of this module will however accept patches to get closer to full 5.6 support where it makes sense to, at the request of interested parties.
AUTHOR
James Laver <james.laver@gmail.com>
CONTRIBUTOR
Kent Fredric <kentnl@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2017 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.