NAME

    File::XDG - Basic implementation of the XDG base directory
    specification

VERSION

    version 0.09_01

SYNOPSIS

     use File::XDG;
     
     my $xdg = File::XDG->new(name => 'foo');
     
     # user config
     my $path = $xdg->config_home;
     
     # user data
     my $path = $xdg->data_home;
     
     # user cache
     my $path = $xdg->cache_home;
     
     # system $config
     my @dirs = $xdg->config_dirs_list;
     
     # system data
     my @dirs = $xdg->data_dirs_list;

DESCRIPTION

    This module provides a basic implementation of the XDG base directory
    specification as exists by the Free Desktop Organization (FDO). It
    supports all XDG directories except for the runtime directories, which
    require session management support in order to function.

CONSTRUCTOR

 new

     my $xdg = File::XDG->new( %args );

    Returns a new instance of a File::XDG object. This must be called with
    an application name as the "name" argument.

    Takes the following named arguments:

    api

      The API version to use.

      api = 0

	The default and original API version.

      api = 1

	Currently experimental API version. This will issue a warning when
	invoked until version 1.00 is released. At this point the version 1
	API will be stable.

    name

      Name of the application for which File::XDG is being used.

    path_class

      The path class to return

      File::Spec

	All methods that return a file will return a string generated by
	File::Spec.

      Path::Class

	This is the default with api = 0. All methods that return a file
	will return an instance of Path::Class::File and all methods that
	return a directory will return an instance of Path::Class::Dir.

      Path::Tiny

	This is the default with api = 1. All methods that return a file
	will return an instance of Path::Tiny.

      CODEREF

	If a code reference is passed in then this will be called in order
	to construct the path class. This allows rolling your own customer
	path class objects. Example:

         my $xdg = File::XDG->new(
           name => 'foo',
           # equivalent to path_class => 'Path::Tiny'
           path_class => sub { Path::Tiny->new(@_),
         );

      ARRAY

	Similar to passing a code reference, an array reference with two
	code references means the first code reference will be used for
	file paths and the second will be used for directory paths. This is
	for path classes that differentiate between files and directories.

         # equivalent to path_class => 'Path::Class'
         my $xdg = File::XDG->new(
           name => 'foo',
           path_class => [
             sub { Path::Class::File->new(@_) ),
             sub { Path::Class::Dir->new(@_) },
           ],
         );

METHODS

 data_home

     my $path = $xdg->data_home;

    Returns the user-specific data directory for the application as a path
    class object.

 config_home

     my $path = $xdg->config_home;

    Returns the user-specific configuration directory for the application
    as a path class object.

 cache_home

     my $path = $xdg->cache_home;

    Returns the user-specific cache directory for the application as a path
    class object.

 data_dirs

     my $dirs = $xdg->data_dirs;

    Returns the system data directories, not modified for the application.
    Per the specification, the returned string is :-delimited, except on
    Windows where it is ;-delimited.

    For portability "data_dirs_list" is preferred.

 data_dirs_list

    [version 0.06]

     my @dirs = $xdg->data_dirs_list;

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

 config_dirs

     my $dirs = $xdg->config_dirs;

    Returns the system config directories, not modified for the
    application. Per the specification, the returned string is :-delimited,
    except on Windows where it is ;-delimited.

    For portability "config_dirs_list" is preferred.

 config_dirs_list

    [version 0.06]

     my @dirs = $xdg->config_dirs_list;

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

 lookup_data_file

     # api = 0
     my $path = $xdg->lookup_data_file($subdir, $filename);

    Looks up the data file by searching for ./$subdir/$filename relative to
    all base directories indicated by $XDG_DATA_HOME and $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.

     # api = 1
     my $path = $xdg->lookup_data_File($filename);

    Looks up the data file by searching for ./$name/$filename (where $name
    is provided by the constructor) relative to all base directories
    indicated by $XDG_DATA_HOME and $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.

 lookup_config_file

     # api = 0
     my $path = $xdg->lookup_config_file($subdir, $filename);

    Looks up the configuration file by searching for ./$subdir/$filename
    relative to all base directories indicated by $XDG_CONFIG_HOME and
    $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.

     # api = 1
     my $path = $xdg->lookup_config_file($filename);

    Looks up the configuration file by searching for ./$name/$filename
    (where $name is provided by the constructor) relative to all base
    directories indicated by $XDG_CONFIG_HOME and $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.

SEE ALSO

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

CAVEATS

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

    MSWin32 (Strawberry Perl, Visual C++ Perl, etc)

      The spec requires : as the path separator, but use of this character
      is essential for absolute path names in Windows, so the Windows Path
      separator ; 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
      %LOCALAPPDATA%. Arguably the data and config base directory should be
      %APPDATA%, but cache should definitely be in %LOCALAPPDATA%, and we
      chose to use just one base directory for simplicity.

SEE ALSO

    Path::Class

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

    Path::Tiny

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

    Path::Spec

      Core Perl library for working with file and directory paths.

    File::BaseDir

      Provides similar functionality to this module with a different
      interface.

AUTHOR

    Original author: Síle Ekaterin Aman

    Current maintainer: Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2012-2021 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.

