NAME

Mojo::File::Share - Better local share directory support with Mojo::File

STATUS

SYNOPSIS

package Foo::Bar;
use Mojo::File::Share qw(dist_dir dist_file);

# defaults to using calling package to determine dist_dir
my $dist_dir = dist_dir();
my $collection = $dist_dir->list_tree; # is a Mojo::File

# same as above, but specifies dist explicitly
my $dist_dir = dist_dir('Foo-Bar');

# with one argument, calling package is used for dist
my $file = dist_file('file.txt');
say $file->slurp; # is a Mojo::File

# same as above, but specifies dist explicitly
my $file = dist_file('Foo-Bar', 'file.txt');

# use path so there is only one arg and default dist is used
my $file = dist_file(path('path', 'to', 'file.txt'));

# or specify dist and path is not necessary
my $file = dist_file('Foo-Bar', 'path', 'to', 'file.txt');

DESCRIPTION

Mojo::File::Share is a dropin replacement for File::ShareDir based on File::Share. Mojo::File::Share has three main differences from File::Share:

• "dist_dir" and "dist_file" both return Mojo::File objects.

• "dist_dir" and "dist_file" have been enhanced even more to understand when the developer's local ./share/ directory should be used.

  File::Share checks %INC to determine if the dist has been used or required, and then it checks for the share directory relative to the dist's .pm file location. This is good for a lot of local development, but it is not good for using in tests if you want to access the share directory but haven't loaded the dist. Mojo::File::Share does the above check, and then if that doesn't work, it checks the current working directory for the existence of lib/$path_to_dist.pm and the existence of a share directory, and returns that share directory if both conditions are true. This removes the need a lot of the time to do something like this in your tests:

  $File::ShareDir::DIST_SHARE{'Foo-Bar'} = path('share')->realpath;

• If no dist is provided to "dist_dir" or "dist_file", Mojo::File::Share will default to using the calling package as the dist.

NOTE: module_dist and module_file are not supported.

FUNCTIONS

dist_dir

# defaults to using calling package to determine dist_dir
# package Foo::Bar becomes dist Foo-Bar
my $dist_dir = dist_dir();
my $collection = $dist_dir->list_tree; # is a Mojo::File

# specify dist explicitly
my $dist_dir = dist_dir('Foo-Bar');

The "dist_dir" function takes a single parameter of the name of an installed (CPAN or otherwise) distribution, and locates either the local share directory, if one exists, or the shared data directory created at install time for it. If no distribution is provided, "dist_dir" will use the package of the caller to determine the name of the distribution.

Returns the directory as a Mojo::File returned by "realpath" in Mojo::File, or dies if it cannot be located or is not readable.

See "DESCRIPTION" for an explanation on how "dist_dir" works better for local development and local distributions.

dist_file

# with one argument, calling package is used for dist
my $file = dist_file('file.txt');
say $file->slurp; # is a Mojo::File

# same as above, but specifies dist explicitly
my $file = dist_file('Foo-Bar', 'file.txt');

# use path so there is only one arg and default dist is used
my $file = dist_file(path('path', 'to', 'file.txt'));

# or specify dist and path is not necessary
my $file = dist_file('Foo-Bar', 'path', 'to', 'file.txt');

The "dist_file" function takes one more more parameters. If one parameter is provided, the distribution will be determined using the caller's package name. Then the provided argument will be used to find a file within the share directory for that distribution. When you want to pass multiple arguments for the file path and you want to have the distribution determined by "dist_file", use "path" in Mojo::File to wrap multiple arguments into one:

# use path so there is only one arg and default dist based on the calling package is used
my $file = dist_file(path('path', 'to', 'file.txt'));

If more than one argument is provided to "dist_file", the first argument is the distribution and the remainder will be passed to "child" in Mojo::File on the Mojo::File directory returned by "dist_dir":

my $file = dist_file('Foo-Bar', 'path', 'to', 'file.txt');

Returns the file as a Mojo::File returned by "realpath" in Mojo::File, or dies if it cannot be located or is not readable.

See "DESCRIPTION" for an explanation on how "dist_file" works better for local development and local distributions.

LICENSE

Copyright (C) srchulo.

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

AUTHOR

srchulo <srchulo@cpan.org>