Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Test::File::ShareDir(3User Contributed Perl DocumentatiTest::File::ShareDir(3)

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

VERSION
       version 1.001002

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
       "Test::File::ShareDir" is some low level	plumbing to enable a
       distribution to perform tests while consuming its own "share"
       directories in a	manner similar to how they will	be once	installed.

       This allows "File::ShareDir" to see the latest version of content
       instead of simply whatever is installed on whichever target system you
       happen to be testing on.

       Note: 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->register;

       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->register;

       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.

SCOPE LIMITED UTILITIES
       "Test::File::ShareDir" provides a few utility functions to aide in
       temporarily adjusting "ShareDir"	behavior.

	   use Test::File::ShareDir qw(	with_dist_dir with_module_dir );

	   with_dist_dir({ 'Dist-Name' => 'Some/Path' }, sub {
	     # dist_dir() now behaves differently here
	   });
	   with_module_dir({ 'Module::Name' => 'Some/Path' }, sub {
	     # module_dir() now	behaves	differently here
	   });

       See "EXPORTABLE FUNCTIONS" for details.

IMPORTING
       Since 1.001000, there are 2 ways	of passing arguments to	"import"

	 use Foo { -root => ...	options	}, qw( functions to import );
	 use Foo -optname => option, -optname => option, qw( functions to import );

       Both should work, but the former	might be less prone to accidental
       issues.

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

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

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

       o   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')

EXPORTABLE FUNCTIONS
   with_dist_dir
       Sets up a "ShareDir" environment	with limited context.

	 # with_dist_dir(\%config, \&sub);
	 with_dist_dir(	{ 'Dist-Name' => 'share/' } => sub {

	     # File::ShareDir resolves to a copy of share/ in this context.

	 } );

       %config can contain anything "Test::File::ShareDir::Dist" accepts.

       "-root":	Defaults to $CWD
       "$distName": Declare $distName's	"ShareDir".

       Since 1.001000

   with_module_dir
       Sets up a "ShareDir" environment	with limited context.

	 # with_module_dir(\%config, \&sub);
	 with_module_dir( { 'Module::Name' => 'share/' } => sub	{

	     # File::ShareDir resolves to a copy of share/ in this context.

	 } );

       %config can contain anything "Test::File::ShareDir::Module" accepts.

       "-root":	Defaults to $CWD
       "$moduleName": Declare $moduleName's "ShareDir".

       Since 1.001000

THANKS
       Thanks to the "#distzilla" crew for ideas,suggestions, code review and
       debugging, even though not all of it made it into releases.

       o   DOLMEN <cpan:///author/dolmen>

       o   ETHER <cpan:///author/ether>

       o   HAARG <cpan:///author/haarg>

       o   RJBS	<cpan:///author/rjbs>

AUTHOR
       Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2017 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.

perl v5.24.1			  2017-03-01	       Test::File::ShareDir(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | SIMPLE INTERFACE | SCOPE LIMITED UTILITIES | IMPORTING | EXPORTABLE FUNCTIONS | THANKS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Test::File::ShareDir&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help