NAME

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

VERSION

version 0.000008

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] - 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/ )

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

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, but Path::Tiny does not presently (Circa 0.72) work on Perl <5.8 (details on GitHub)

• 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 install

  • SMUELLER/Data-Dumper-2.128.tar.gz is newest version of Data::Dumper that works on 5.6.2, versions 2.130_03 to 2.154 presently fail.

  • OVID/Test-Differences-0.61.tar.gz is the newest version of Test::Differences that works on 5.6.2, versions 0.61_01 to 0.63 presently fail.

• Test::TempDir::Tiny is used a fair bit in tests as well, and as of 0.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.