# 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](https://metacpan.org/pod/Mojo::File::Share) is a dropin replacement for [File::ShareDir](https://metacpan.org/pod/File::ShareDir) based on [File::Share](https://metacpan.org/pod/File::Share). [Mojo::File::Share](https://metacpan.org/pod/Mojo::File::Share) has
three main differences from [File::Share](https://metacpan.org/pod/File::Share):
- ["dist\_dir"](#dist_dir) and ["dist\_file"](#dist_file) both return [Mojo::File](https://metacpan.org/pod/Mojo::File) objects.
- ["dist\_dir"](#dist_dir) and ["dist\_file"](#dist_file) have been enhanced even more to understand when the developer's
local `./share/` directory should be used.
[File::Share](https://metacpan.org/pod/File::Share) checks `%INC` to determine if the dist has been `use`d or `require`d, 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](https://metacpan.org/pod/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"](#dist_dir) or ["dist\_file"](#dist_file), [Mojo::File::Share](https://metacpan.org/pod/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"](#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"](#dist_dir) will use the package of the caller to determine the name of the distribution.
Returns the directory as a [Mojo::File](https://metacpan.org/pod/Mojo::File) returned by ["realpath" in Mojo::File](https://metacpan.org/pod/Mojo::File#realpath), or dies if it cannot be located or is not readable.
See ["DESCRIPTION"](#description) for an explanation on how ["dist\_dir"](#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"](#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"](#dist_file), use ["path" in Mojo::File](https://metacpan.org/pod/Mojo::File#path) 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"](#dist_file), the first argument is the distribution and the remainder
will be passed to ["child" in Mojo::File](https://metacpan.org/pod/Mojo::File#child) on the [Mojo::File](https://metacpan.org/pod/Mojo::File) directory returned by ["dist\_dir"](#dist_dir):
my $file = dist_file('Foo-Bar', 'path', 'to', 'file.txt');
Returns the file as a [Mojo::File](https://metacpan.org/pod/Mojo::File) returned by ["realpath" in Mojo::File](https://metacpan.org/pod/Mojo::File#realpath), or dies if it cannot be located or is not readable.
See ["DESCRIPTION"](#description) for an explanation on how ["dist\_file"](#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
