gitpan / test-file-sharedir Goto Github PK

NAME
    Test::File::ShareDir - Create a Fake ShareDir for your modules for
    testing.

VERSION
    version 1.000005

SYNOPSIS
        use Test::More;

        # use FindBin; optional

        use Test::File::ShareDir
            # -root => "$FindBin::Bin/../" # optional,
            -share => {
                -module => { 'My::Module' => 'share/MyModule' }
                -dist   => { 'My-Dist'    => 'share/somefolder' }
            };

        use My::Module;

        use File::ShareDir qw( module_dir dist_dir );

        module_dir( 'My::Module' ) # dir with files from $dist/share/MyModule

        dist_dir( 'My-Dist' ) # dir with files from $dist/share/somefolder

DESCRIPTION
    This module only has support for creating 'new' style share dirs and are
    NOT compatible with old File::ShareDirs.

    For this reason, unless you have File::ShareDir 1.00 or later installed,
    this module will not be usable by you.

SIMPLE INTERFACE
    Starting with version 0.4.0, there are a few extra interfaces you can
    use.

    These will probably be more useful, and easier to grok, because they
    don't have a layer of indirection in order to simultaneously support
    both "Module" and "Dist" "ShareDir"'s.

  Simple Exporter Interfaces
   "Test::File::ShareDir::Dist"
    "Test::File::ShareDir::Dist" provides a simple export interface for
    making "TempDir" "ShareDir"'s from a given path:

        use Test::File::ShareDir::Dist { "Dist-Name" => "share/" };

    This will automatically create a "ShareDir" for "Dist-Name" in a
    "TempDir" based on the contents of "CWD/share/"

    See "Test::File::ShareDir::Dist" for details.

   "Test::File::ShareDir::Module"
    "Test::File::ShareDir::Module" provides a simple export interface for
    making "TempDir" "ShareDir"'s from a given path:

        use Test::File::ShareDir::Module { "Module::Name" => "share/" };

    This will automatically create a "ShareDir" for "Module::Name" in a
    "TempDir" based on the contents of "CWD/share/"

    See "Test::File::ShareDir::Module" for details.

  Simple Object Oriented Interfaces
   "Test::File::ShareDir::Object::Dist"
    "Test::File::ShareDir::Object::Dist" provides a simple object oriented
    interface for making "TempDir" "ShareDir"'s from a given path:

        use Test::File::ShareDir::Object::Dist;

        my $obj = Test::File::ShareDir::Object::Dist->new( dists => { "Dist-Name" => "share/" } );
        $obj->install_all_dists;
        $obj->add_to_inc;

    This will automatically create a "ShareDir" for "Dist-Name" in a
    "TempDir" based on the contents of "CWD/share/"

    See "Test::File::ShareDir::Object::Dist" for details.

   "Test::File::ShareDir::Object::Module"
    "Test::File::ShareDir::Object::Module" provides a simple object oriented
    interface for making "TempDir" "ShareDir"'s from a given path:

        use Test::File::ShareDir::Object::Module;

        my $obj = Test::File::ShareDir::Object::Module->new( modules => { "Module::Name" => "share/" } );
        $obj->install_all_modules;
        $obj->add_to_inc;

    This will automatically create a "ShareDir" for "Module::Name" in a
    "TempDir" based on the contents of "CWD/share/"

    See "Test::File::ShareDir::Object::Module" for details.

IMPORTING
  -root
    This parameter is the prefix the other paths are relative to.

    If this parameter is not specified, it defaults to the Current Working
    Directory ( "CWD" ).

    In versions prior to 0.3.0, this value was mandatory.

    The rationale behind using "CWD" as the default value is as follows.

    *   Most users of this module are likely to be using it to test
        distributions

    *   Most users of this module will be using it in "$project/t/" to load
        files from "$project/share/"

    *   Most "CPAN" tools run tests with "CWD" = $project

    Therefor, defaulting to "CWD" is a reasonably sane default for most
    people, but where it is not it can still be overridden.

      -root => "$FindBin::Bin/../" # resolves to project root from t/ regardless of Cwd.

  -share
    This parameter is mandatory, and contains a "hashref" containing the
    data that explains what directories you want shared.

      -share =>  { ..... }

   -module
    "-module" contains a "hashref" mapping Module names to path names for
    module_dir style share dirs.

      -share => {
        -module => { 'My::Module' => 'share/mymodule/', }
      }

      ...

      module_dir('My::Module')

    Notedly, it is a "hashref", which means there is a limitation of one
    share dir per module. This is simply because having more than one share
    dir per module makes no sense at all.

   -dist
    "-dist" contains a "hashref" mapping Distribution names to path names
    for dist_dir style share dirs. The same limitation applied to "-module"
    applies here.

      -share => {
        -dist => { 'My-Dist' => 'share/mydist' }
      }
      ...
      dist_dir('My-Dist')

AUTHOR
    Kent Fredric <[email protected]>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2014 by Kent Fredric <[email protected]>.

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