Provided by: libfile-sharedir-projectdistdir-perl_0.5.2-1_all 
NAME
File::ShareDir::ProjectDistDir - Simple set-and-forget using of a '/share' directory in
your projects root
VERSION
version 0.5.2
SYNOPSIS
package An::Example::Package;
use File::ShareDir::ProjectDistDir;
# during development, $dir will be $projectroot/share
# but once installed, it will be wherever File::Sharedir thinks it is.
my $dir = dist_dir('An-Example')
Project layout requirements:
$project/
$project/lib/An/Example/Package.pm
$project/share/ # files for package 'An-Example' go here.
You can use a directory name other than 'share' ( Assuming you make sure when you install
that, you specify the different directory there also ) as follows:
use File::ShareDir::ProjectDistDir ':all', defaults => {
projectdir => 'templates',
};
METHODS
import
use File::ShareDir::ProjectDistDir (@args);
This uses "Sub::Exporter" to do the heavy lifting, so most usage of this module can be
maximised by understanding that first.
• ":all"
->import( ':all' , .... )
Import both "dist_dir" and "dist_file"
• "dist_dir"
->import('dist_dir' , .... )
Import the dist_dir method
• "dist_dir"
->import('dist_file' , .... )
Import the dist_file method
• "projectdir"
->import( .... , projectdir => 'share' )
Specify what the project directory is as a path relative to the base of your
distributions source, and this directory will be used as a "ShareDir" simulation path
for the exported methods During development.
If not specified, the default value 'share' is used.
• "filename"
->import( .... , filename => 'some/path/to/foo.pm' );
Generally you don't want to set this, as its worked out by caller() to work out the
name of the file its being called from. This file's path is walked up to find the
'lib' element with a sibling of the name of your "projectdir".
• "distname"
->import( .... , distname => 'somedistname' );
Specifying this argument changes the way the functions are emitted at installed
"runtime", so that instead of taking the standard arguments File::ShareDir does, the
specification of the "distname" in those functions is eliminated.
i.e:
# without this flag
use File::ShareDir::ProjectDistDir qw( :all );
my $dir = dist_dir('example');
my $file = dist_file('example', 'path/to/file.pm' );
# with this flag
use File::ShareDir::ProjectDistDir ( qw( :all ), distname => 'example' );
my $dir = dist_dir();
my $file = dist_file('path/to/file.pm' );
• "defaults"
->import( ... , defaults => {
filename => ....,
projectdir => ....,
});
This is mostly an alternative syntax for specifying "filename" and "projectdir", which
is mostly used internally, and their corresponding other values are packed into this
one.
Sub::Exporter tricks of note.
Make your own sharedir util
package Foo::Util;
sub import {
my ($caller_class, $caller_file, $caller_line ) = caller();
if ( grep { /share/ } @_ ) {
require File::ShareDir::ProjectDistDir;
File::ShareDir::ProjectDistDir->import(
filename => $caller_file,
dist_dir => { distname => 'myproject' , -as => 'share' },
dist_dir => { distname => 'otherproject' , -as => 'other_share' , projectdir => 'share2' },
-into => $caller_class,
);
}
}
....
package Foo;
use Foo::Util qw( share );
my $dir = share();
my $other_dir => other_share();
build_dist_dir
use File::ShareDir::ProjectDirDir ( : all );
# this calls
my $coderef = File::ShareDir::ProjectDistDir->build_dist_dir(
'dist_dir' => {},
{ defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } }
);
use File::ShareDir::ProjectDirDir ( qw( :all ), distname => 'example-dist' );
# this calls
my $coderef = File::ShareDir::ProjectDistDir->build_dist_dir(
'dist_dir' => {},
{ distname => 'example-dist', defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } }
);
use File::ShareDir::ProjectDirDir
dist_dir => { distname => 'example-dist', -as => 'mydistdir' },
dist_dir => { distname => 'other-dist', -as => 'otherdistdir' };
# This calls
my $coderef = File::ShareDir::ProjectDistDir->build_dist_dir(
'dist_dir',
{ distname => 'example-dist' },
{ defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } },
);
my $othercoderef = File::ShareDir::ProjectDistDir->build_dist_dir(
'dist_dir',
{ distname => 'other-dist' },
{ defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } },
);
# And leverages Sub::Exporter to create 2 subs in your package.
Generates the exported 'dist_dir' method. In development environments, the generated
method will return a path to the development directories 'share' directory. In non-
development environments, this simply returns "File::ShareDir::dist_dir".
As a result of this, specifying the Distribution name is not required during development,
however, it will start to matter once it is installed. This is a potential avenues for
bugs if you happen to name it wrong.
build_dist_file
use File::ShareDir::ProjectDirDir ( : all );
# this calls
my $coderef = File::ShareDir::ProjectDistDir->build_dist_file(
'dist_file' => {},
{ defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } }
);
use File::ShareDir::ProjectDirDir ( qw( :all ), distname => 'example-dist' );
# this calls
my $coderef = File::ShareDir::ProjectDistDir->build_dist_file(
'dist_file' => {},
{ distname => 'example-dist', defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } }
);
use File::ShareDir::ProjectDirDir
dist_file => { distname => 'example-dist', -as => 'mydistfile' },
dist_file => { distname => 'other-dist', -as => 'otherdistfile' };
# This calls
my $coderef = File::ShareDir::ProjectDistDir->build_dist_file(
'dist_file',
{ distname => 'example-dist' },
{ defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } },
);
my $othercoderef = File::ShareDir::ProjectDistDir->build_dist_file(
'dist_file',
{ distname => 'other-dist' },
{ defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } },
);
# And leverages Sub::Exporter to create 2 subs in your package.
Generates the 'dist_file' method.
In development environments, the generated method will return a path to the development
directories 'share' directory. In non-development environments, this simply returns
"File::ShareDir::dist_file".
Caveats as a result of package-name as stated in "build_dist_dir" also apply to this
method.
SIGNIFICANT CHANGES
0.5.0 - Heuristics and Return type changes
New "devdir" heuristic
Starting with 0.5.0, instead of using our simple "lib/../share" pattern heuristic, a more
advanced heuristic is used from the new "Path::FindDev" and "Path::IsDev".
This relies on a more "concrete" marker somewhere at the top of your development tree, and
more importantly, checks for the existence of specific files that are not likely to occur
outside a project root.
"lib" and "share" based heuristics were a little fragile, for a few reasons:
• "lib" can, and does appear all over UNIX file systems, for purposes other than
development project roots.
For instance, have a look in "/usr/"
/usr/bin
/usr/lib
/usr/share ## UHOH.
This would have the very bad side effect of anything installed in "/usr/lib" thinking
its "in development".
Fortunately, nobody seems to have hit this specific bug, which I suspect is due only
to "/usr/lib" being a symbolic link on most x86_64 systems.
• "lib" is also reasonably common within "CPAN" package names.
For instance:
lib::abs
Which means you'll have a hierarchy like:
$PREFIX/lib/lib/abs
All you need for something to go horribly wrong would be for somebody to install a
"CPAN" module named:
share::mystuff
Or similar, and instantly, you have:
$PREFIX/lib/lib/
$PREFIX/lib/share/
Which would mean any module calling itself "lib::*" would be unable to use this
module.
So instead, as of 0.5.0, the heuristic revolves around certain specific files being in the
"dev" directory.
Which is hopefully a more fault resilient mechanism.
New Return Types
Starting with 0.5.0, the internals are now based on "Path::Tiny" instead of "Path::Class",
and as a result, there may be a few glitches in transition.
Also, previously you could get a "Path::Class::*" object back from "dist_dir" and
"dist_file" by importing it as such:
use File::ShareDir::ProjectDistDir
qw( dist_dir dist_file ),
defaults => { pathclass => 1 };
Now you can also get "Path::Tiny" objects back, by passing:
use File::ShareDir::ProjectDistDir
qw( dist_dir dist_file ),
defaults => { pathtiny => 1 };
For the time being, you can still get Path::Class objects back, but its likely to be
deprecated in future.
( In fact, I may even make 2 specific sub-classes of "PDD" for people who want objects
back, as it will make the "API" and the code much cleaner )
AUTHOR
Kent Fredric <kentnl@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2013 by Kent Fredric <kentnl@cpan.org>.
This is free software; you can redistribute it and/or modify it under the same terms as
the Perl 5 programming language system itself.