NAME

XDG::BaseDirectory - locate shared data and configuration

SYNOPSIS

    use XDG::BaseDirectory;
    my $bd = XDG::BaseDirectory.new

    for $bd.load-config-paths('mydomain.org', 'MyProg', 'Options') -> $d {
        say $d;
    }

    # Directories can be made available as terms as well
    use XDG::BaseDirectory :terms;
    say config-home;

DESCRIPTION

The freedesktop.org Base Directory specification provides a way for applications to locate shared data and configuration:

http://standards.freedesktop.org/basedir-spec/

This module can be used to load and save from and to these directories.

The interface is loosely based on that of the pyxdg module, however all methods that return a string path in that module return an IO::Path here.

METHODS

data-home

This reflects the base path where local data should be stored. Can be over-ridden by the environment variable XDG_DATA_HOME.

data-dirs

This returns a list of the locations where data can be read from, it can be over-ridden by the colon separated environment variable XDG_DATA_DIRS but will always prefer data-home.

config-home

Reflects the location where application should be saved to to. Can be over-ridden by the enviroment variable XDG_CONFIG_HOME.

config-dirs

returns a list of directorys from which configuration can be read, it will always prefer config-home but the defaults can be over-ridden by the environment variable XDG_CONFIG_DIRS which can be a list separated by colons.

cache-home

Returns the path where application cache data should be saved. This can be over-ridden by the environment variable XDG_CACHE_HOME.

runtime-dir

Returns the directory where user specific, run-time files (and other filesystem objects such as sockets and named pipes,) should be placed. The directory will not persist between logins and reboots of the system. For this to work correctly the system should be managing the directory and set the environment variable XDG_RUNTIME_DIR, however if this is not the case the behaviour will be emulated in a less secure fashion and a warning will be emitted.

save-config-path(Str *@resource)

Ensure <config-home>/<resource>/ exists, and return its path. 'resource' should normally be the name of your application. Use this when SAVING configuration settings. Use the config-dirs variable for loading.

save-data-path(Str *@resource)

Ensure <data-home>/<resource>/ exists, and return its path. 'resource' is the name of some shared resource. Use this when updating a shared (between programs) database. Use the data-dirs variable for loading.

load-config-paths

Returns an iterator which gives each directory named 'resource' in the configuration search path. Information provided by earlier directories should take precedence over later ones (ie, the user's config dir comes first).

load-first-config(Str *@resource) returns IO::Path

Returns the first result from load-config-paths, or None if there is nothing to load.

load-data-paths(Str *@resource)

Returns an iterator which gives each directory named 'resource' in the shared data search path. Information provided by earlier directories should take precedence over later ones.

Terms

When XDG::BaseDirectory is used with the :terms tag, the following properties of a generic XDG::BaseDirectory object are exported as eponymous terms:

• data-home

• data-dirs

• config-home

• config-dirs

• cache-home

• runtime-dir

Example:

    use XDG::BaseDirectory :terms;

    say "Put config files into " ~ config-home ~ ", please.";

You can over-ride the default XDG::BaseDirectory object used in these terms by assigning to the dynanic variabled $*XDG:

   use XDG::BaseDirectory :terms;

   my $*XDG = XDG::BaseDirectory.new( config-home => "foo".IO );

   ....

   say config-home; # -> "foo";