NAME
    File::ShareDir::ProjectDistDir - Simple set-and-forget using of a
    '/share' directory in your projects root

VERSION
    version 0.4.3

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.

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.