File::XDG(3pm)

📦
version 1.03 · 6 versions
, in ubuntu resolute, ubuntu stonking

💖 File::XDG — Basic implementation of the XDG base directory specification ✨

okay bestie, welcome to the File::XDG manual, User Contributed Perl Documentation edition 🫶 this is the one where your app finally figures out where it's supposed to put its files instead of dumping everything in $HOME like a gremlin. no cap.

VERSION: version 1.03 💅

🌸 SYNOPSIS 🌸

use File::XDG 1.00;

my $xdg = File::XDG->new( name => 'foo', api => 1 );

# 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;

look at that. immaculate. ✨

🦋 DESCRIPTION 🦋

so this module is a basic implementation of the XDG base directory specification — the one that exists by the Free Desktop Organization (FDO). it supports all XDG directories except for the runtime directories, because those ones need session management support in order to actually function. it's giving "we'd love to, but that's a whole other thing" 😭

💅 CONSTRUCTOR 💅

new 👑

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

Returns a new instance of a File::XDG object. You must call this with an application name as the name argument — no name, no vibes, no object. 🎀

Takes the following named arguments:

api [version 0.09]

The API version to use.

  • api = 0 — The default and original API version. For backward compatibility only. (respectfully, legacy 💀)
  • api = 1 — Recommended stable API version for all new code. 👑

name

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

path_class [version 0.09]

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(@_) },
  ],
);

strict [version 0.10]

More strictly follow the XDG base directory specification. In particular:

  • On Windows a an exception will be thrown when creating the File::XDG object because the spec cannot correctly be implemented.

Historically this module has made some useful assumptions like using ";" instead of ":" for the path separator character. This breaks the spec.

  • On some systems, this module will look in system specific locations for the runtime_home. This is useful, but technically violates the spec, so under strict mode the runtime_home method will only return a path if one can be found via the spec.
strict mode is the "we are following the rules, even the annoying ones" era. iconic honestly. 🌈

✨ 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.

state_home 💜

my $path = $xdg->state_home;

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

runtime_home 🌙

[version 0.10]

my $dir = $xdg->runtime_home;

Returns the directory for user-specific non-essential runtime files and other file objects (such as sockets, named pipes, etc) for the application.

This is not always provided, if not available, this method will return undef. 😭

Under strict mode, this method will only rely on the XDG_RUNTIME_DIR to find this directory. Under non-strict mode, system specific methods may be used, if the environment variable is not set:

  • Linux systemd — The path /run/user/UID will be used, if it exists, and fulfills the requirements of the spec.

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.

exe_dir 🚀

[version 0.10]

my $exe = $xdg->exe_dir;

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

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 "./$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.

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 "./$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.

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 "./$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.

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 "./$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.

👀 SEE ALSO 👀

⚠️ CAVEATS ⚠️

okay so this next part is the "we're being honest with you" section 🫶 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.

not the Windows slander 😭 it's fine it's fine it's a spec thing. we love you Windows bestie.

💖 SEE ALSO (the second one, yes there are two) 💖

  • 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>

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.

and that's the whole page, bestie!! 🎀 this was perl v5.40.0, dated 2024-09-08, and it's the File::XDG(3pm) manual — go put your files in the right directories, you absolute main character 💅✨🦋

📦 where this page comes from