File::UserDirs(3)

💖 File::UserDirs 💖

okay so this is a Perl manual page from the User Contributed Perl Documentation section — the module is called File::UserDirs and it is genuinely the most helpful little thing. it's here to help you find extra media and documents directories 🎀

---

✨ NAME ✨

File::UserDirs — find extra media and documents directories 🗂️

🌸 VERSION 🌸

version 0.09 — yes bestie, it's on 0.09, and it slays.

🦋 SYNOPSIS 🦋

the whole vibe in three lines:

use File::UserDirs qw(:all);
print xdg_desktop_dir; # e.g. /home/user/Desktop

that's it. that's the whole thing. no cap. 💅

💜 DESCRIPTION 💜

so like — this module is your go-to for tracking down the directories that the Freedesktop.org xdg-user-dirs software kinda-sorta-formally specifies. it gives you a whole mechanism to locate those extra directories for your media and documents files. it's giving "organized friend who actually knows where the Downloads folder is" energy ✨

🧚 FUNCTIONS 🧚

bestie listen — these can be exported on request. and there's also the group :all defined, which exports all the methods. yes, all of them. the whole squad 🫶

🌈 xdg_desktop_dir

my $dir = xdg_desktop_dir;

returns the desktop directory. unless the user has changed it, this is the directory Desktop in the home directory. iconic default behavior, honestly. 💻

🍓 xdg_documents_dir

my $dir = xdg_documents_dir;

returns the documents directory. unless the user has changed it, this is the home directory. 🏠

🎀 xdg_download_dir

my $dir = xdg_download_dir;

returns the download directory. unless the user has changed it, this is the home directory. 📥

🦋 xdg_music_dir

my $dir = xdg_music_dir;

returns the music directory. unless the user has changed it, this is the home directory. 🎧

🌸 xdg_pictures_dir

my $dir = xdg_pictures_dir;

returns the pictures directory. unless the user has changed it, this is the home directory. 📸

👑 xdg_publicshare_dir

my $dir = xdg_publicshare_dir;

returns the public share directory. unless the user has changed it, this is the home directory. 🌍

⭐ xdg_templates_dir

my $dir = xdg_templates_dir;

returns the templates directory. unless the user has changed it, this is the home directory. 📄

🔥 xdg_videos_dir

my $dir = xdg_videos_dir;

returns the videos directory. unless the user has changed it, this is the home directory. 🎬

💀 notice how almost every single one defaults to the home directory? yeah. that's the move. the desktop one is the only diva who defaults to an actual subdirectory (Desktop). main character energy tbh.

😭 DIAGNOSTICS 😭

• "xdg-user-dir" failed to start: %s — oh no. the executable xdg-user-dir could not be run, most likely because it was not installed. check DEPENDENCIES below, bestie, don't leave me hanging 🙈

🧵 CONFIGURATION AND ENVIRONMENT 🧵

so the user can specify where these directories live in the file $XDG_CONFIG_HOME/user-dirs.dirs. it's a shell file that sets a bunch of environment variables. cute, right? ✨

now — if you want to find the exact pathname from Perl, you run this:

use File::BaseDir qw(config_home);
print config_home('user-dirs.dirs');

literally so handy. iykyk. 🫶

🎀 Example customised user-dirs.dirs

here's what a fully customized one looks like — look at all these absolute queens reorganizing their whole filesystem:

XDG_DESKTOP_DIR="$HOME/Workspace"
XDG_DOCUMENTS_DIR="$HOME/Files"
XDG_DOWNLOAD_DIR="$HOME/Files/Downloads"
XDG_MUSIC_DIR="$HOME/Files/Audio"
XDG_PICTURES_DIR="$HOME/Files/Images"
XDG_PUBLICSHARE_DIR="$HOME/public_html"
XDG_TEMPLATES_DIR="$HOME/Files/Document templates"
XDG_VIDEOS_DIR="$HOME/Files/Video"

okay but "$HOME/Files/Document templates" with the space in it?? bold. we love a folder name with a space. 😌

💅 DEPENDENCIES 💅

this module requires the executable xdg-user-dir from the package xdg-user-dirs. you literally cannot run without it, fr fr.

source code is available from <http://cgit.freedesktop.org/xdg/xdg-user-dirs/> — go grab it if you don't have it 💖

🌟 AUTHORS 🌟

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

two legends. we stan. 👑

🎀 COPYRIGHT AND LICENSE 🎀

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

and it's free software — you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. periodt. 💜

---

and that's the whole page, bestie! 🦋 this one shipped as perl v5.42.2 on 2023-07-03 — so go forth, find those directories, and remember: the home directory default is not a bug, it's a lifestyle. 💖✨🎀