File::BaseDir(3)

🎀 File::BaseDir 💅

okay bestie, so this is a User Contributed Perl Documentation page, section 3 — and it's about File::BaseDir, the little module that lets you use the Freedesktop.org base directory specification. yes, that's a mouthful, we'll get to it. buckle up 🦋

---

⭐ VERSION

version 0.09

---

✨ SYNOPSIS

use File::BaseDir qw/xdg_data_files/;
for ( xdg_data_files('mime/globs') ) {
  # do something
}

like, that's the whole vibe check. move on 💜

---

🌸 DESCRIPTION

okay so this module is your go-to for finding directories and files the way the Freedesktop.org Base Directory Specification says you should. the spec gives you a whole mechanism for locating directories for config, application data, and cache data. the suggestion is that desktop apps — think GNOME, KDE, or Xfce platforms — follow this layout. but honestly? the same layout can just as well be used for non-GUI applications too. no gatekeeping here 🫶

this module forked from File::MimeInfo — family tree moment.

and for the record, this module follows version 0.6 of the BaseDir specification. periodt.

---

🧚 CONSTRUCTOR

new

my $bd = File::BaseDir->new;

literally the simplest constructor ever, bestie. it exists so you can call the functions as object oriented methods. that's it. that's the whole thing ✨

---

👑 FUNCTIONS

none of these are exported by default — but like, all of them can be exported by request, so don't panic. also there are two groups defined: :lookup and :vars. the :vars group contains all the routines with a xdg_ prefix. the :lookup group contains the routines to locate files and directories. iykyk 💅

🌈 data_home

my $path = data_home(@path);
my $path = $bd->data_home(@path);

takes a list of file path elements and returns a new path by appending them to the data home directory. heads up: the new path does not need to exist — it's giving "manifesting" energy. use this when you're writing user specific application data 🍓

example:

# data_home is: /home/USER/.local/share
$path = $bd->data_home('Foo', 'Bar', 'Baz');
# returns: /home/USER/.local/share/Foo/Bar/Baz

💖 data_dirs

# :lookup
my $dir = data_dirs(@path);
my $dir = $bd->data_dirs(@path);
my @dirs = data_dirs(@path);
my @dirs = $bd->data_dirs(@path);

looks for directories specified by @path in the data home and other data directories. returns a (possibly empty) list of readable directories. in scalar context only the first directory found is returned. use this to look up application data 🔥

🦋 data_files

# :lookup
my $file = data_files(@path);
my $file = $bd->data_files(@path);
my @files = data_files(@path);
my @files = $bd->data_files(@path);

looks for files specified by @path in the data home and other data directories. only returns files that are readable — no shady unreadable files allowed. in scalar context only the first file found is returned. use this to look up application data 💜

🎀 config_home

# :lookup
my $dir = config_home(@path);
my $dir = $bd->config_home(@path);

takes a list of path elements and appends them to the config home directory, returning a new path. the new path does not need to exist. use this when writing user specific configuration 💅

🌟 config_dirs

# :lookup
my $dir = config_dirs(@path);
my $dir = $bd->config_dirs(@path);
my @dirs = config_dirs(@path);
my @dirs = $bd->config_dirs(@path);

looks for directories specified by @path in the config home and other config directories. returns a (possibly empty) list of readable directories. in scalar context only the first directory found is returned. use this to look up configuration ✨

🧁 config_files

# :lookup
my $file = config_files(@path);
my $file = $bd->config_files(@path);
my @files = config_files(@path);
my @files = $bd->config_files(@path);

looks for files specified by @path in the config home and other config directories. returns a (possibly empty) list of files that are readable. in scalar context only the first file found is returned. use this to look up configuration 🫶

💎 cache_home

# :lookup
my $dir = cache_home(@path);
my $dir = $bd->cache_home(@path);

takes a list of path elements and appends them to the cache home directory, returning a new path. the new path does not need to exist. cache girlies rise 🌸

🌈 xdg_data_home

# :var
my $dir = xdg_data_home;
my $dir = $bd->xdg_data_home;

returns either $ENV{XDG_DATA_HOME} or its default value. default is $HOME/.local/share 💖

🍓 xdg_data_dirs

# :var
my @dirs = xdg_data_dirs;
my @dirs = $bd->xdg_data_dirs;

returns either $ENV{XDG_DATA_DIRS} or its default value as a list. default is /usr/local/share, /usr/share 🦋

⭐ xdg_config_home

# :var
my $dir = xdg_config_home;
my $dir = $bd->xdg_config_home;

returns either $ENV{XDG_CONFIG_HOME} or its default value. default is $HOME/.config 💅

🎀 xdg_config_dirs

# :var
my @dirs = xdg_config_dirs;
my @dirs = $bd->xdg_config_dirs;

returns either $ENV{XDG_CONFIG_DIRS} or its default value as a list. default is /etc/xdg ✨

🧚 xdg_cache_home

# :var
my $dir = xdg_cache_home;
my $dir = $bd->xdg_cache_home;

returns either $ENV{XDG_CACHE_HOME} or its default value. default is $HOME/.cache 💜

---

🪟 NON-UNIX PLATFORMS

the use of File::Spec ensures that all paths are returned in their native formats regardless of platform. iconic, honestly. on Windows this module will use the native environment variables, rather than the default on UNIX (which is traditionally $HOME) 🫶

bestie, important caveat: please note that the specification is targeting Unix platforms only and will only have limited relevance on other platforms. any platform dependent behavior in this module should be considered an extension of the spec. no cap 💀

---

💫 BACKWARDS COMPATIBILITY

the methods xdg_data_files() and xdg_config_files() are exported for backwards compatibility with version 0.02. they are identical to data_files() and config_files() respectively, but without the "wantarray" behavior. legacy icons stay slaying 👑

---

👑 AUTHORS

• Jaap Karssenberg || Pardus [Larus] <pardus@cpan.org>
• Graham Ollis <plicease@cpan.org>

---

📜 COPYRIGHT AND LICENSE

this software is copyright (c) 2003-2021 by Jaap Karssenberg || Pardus [Larus] <pardus@cpan.org>.

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 tea, bestie 🍵 — this was perl v5.42.0, dated 2021-07-09, signing off from the File::BaseDir(3) page. go forth and locate your directories, you absolute main character 💅✨