view release on metacpan or  search on metacpan

lib/File/XDG.pm  view on Meta::CPAN

For portability L</config_dirs_list> is preferred.

=head2 config_dirs_list

[version 0.06]

 my @dirs = $xdg->config_dirs_list;

Returns the system config directories as a list of path class objects.

=head2 exe_dir

[version 0.10]

 my $exe = $xdg->exe_dir;

Returns the user-specific executable files directory C<$HOME/.local/bin>, if it exists.  If it
does not exist then C<undef> will be returned.  This directory I<should> be added to the C<PATH>
according to the spec.

=head2 lookup_data_file

 my $xdg = File::XDG->new( name => $name, api => 1 ); # recommended
 my $path = $xdg->lookup_data_File($filename);

Looks up the data file by searching for C<./$name/$filename> (where C<$name> is
provided by the constructor) relative to all base directories indicated by
C<$XDG_DATA_HOME> and C<$XDG_DATA_DIRS>. If an environment variable is either
not set or empty, its default value as defined by the specification is used
instead. Returns a path class object.

 my $xdg = File::XDG->new( name => $name ); # back compat only
 my $path = $xdg->lookup_data_file($subdir, $filename);

Looks up the data file by searching for C<./$subdir/$filename> relative to all base
directories indicated by C<$XDG_DATA_HOME> and C<$XDG_DATA_DIRS>. If an environment
variable is either not set or empty, its default value as defined by the
specification is used instead. Returns a path class object.

=head2 lookup_config_file

 my $xdg = File::XDG->new( name => $name, api => 1 ); # recommended
 my $path = $xdg->lookup_config_file($filename);

Looks up the configuration file by searching for C<./$name/$filename> (where C<$name> is
provided by the constructor) relative to all base directories indicated by
C<$XDG_CONFIG_HOME> and C<$XDG_CONFIG_DIRS>. If an environment variable is
either not set or empty, its default value as defined by the specification
is used instead. Returns a path class object.

 my $xdg = File::XDG->new( name => $name ); # back compat only
 my $path = $xdg->lookup_config_file($subdir, $filename);

Looks up the configuration file by searching for C<./$subdir/$filename> relative to
all base directories indicated by C<$XDG_CONFIG_HOME> and C<$XDG_CONFIG_DIRS>. If an
environment variable is either not set or empty, its default value as defined
by the specification is used instead. Returns a path class object.

=head1 SEE ALSO

L<XDG Base Directory specification, version 0.7|http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>

=head1 CAVEATS

This module intentionally and out of necessity does not follow the spec on the following platforms:

=over 4

=item C<MSWin32> (Strawberry Perl, Visual C++ Perl, etc)

The spec requires C<:> as the path separator, but use of this character is essential for absolute path names in
Windows, so the Windows Path separator C<;> is used instead.

There are no global data or config directories in windows so the data and config directories are empty list instead of
the default UNIX locations.

The base directory instead of being the user's home directory is C<%LOCALAPPDATA%>.  Arguably the data and config
base directory should be C<%APPDATA%>, but cache should definitely be in C<%LOCALAPPDATA%>, and we chose to use just one
base directory for simplicity.

=back

=head1 SEE ALSO

=over 4

=item L<Path::Class>

Portable native path class used by this module used by default (api = 0) and optionally (api = 1).

=item L<Path::Tiny>

Smaller lighter weight path class used optionally (api = 0) and by default (api = 1).

=item L<Path::Spec>

Core Perl library for working with file and directory paths.

=item L<File::BaseDir>

Provides similar functionality to this module with a different interface.

=back

=head1 AUTHOR

Original author: Síle Ekaterin Aman

Current maintainer: Graham Ollis E<lt>plicease@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2012-2022 by Síle Ekaterin Aman.

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

=cut