X11::F...pEntry(3pm)

💖 X11::FreeDesktop::DesktopEntry — bestie's guide to .desktop files 💖

okay so this is a Perl manual page from the User Contributed Perl Documentation, and it's all about X11::FreeDesktop::DesktopEntry, iykyk. Let's get into it 🫶

---

✨ NAME ✨

X11::FreeDesktop::DesktopEntry — it's an interface to Freedesktop.org .desktop files. literally that's the whole vibe.

---

🌸 SYNOPSIS 🌸

use X11::FreeDesktop::DesktopEntry;

my $entry = X11::FreeDesktop::DesktopEntry->new_from_data($data);

print $entry->get_value('Name');

print $entry->Exec;

$entry->set_value('Name', 'Example Program');

print $entry->as_string;

$entry->reset;

look at her go 💅

---

🦋 DESCRIPTION 🦋

So this module hands you a whole object-oriented interface to files that follow the Freedesktop.org desktop entry spec. You can ask the file what values it has, change them around, and pull locale info too. it's giving very organized, very demure ✨

---

👑 CONSTRUCTOR 👑

X11::FreeDesktop::DesktopEntry does NOT have the standard new() constructor. and honestly? that's on purpose. It means subclasses can build their own backend-specific constructor without having to re-implement the whole constructor, which is a genuine pain to deal with. (for an example subclass that uses Gnome2::VFS as a backend, go peek at the PerlPanel::DesktopEntry module in the PerlPanel distribution — it's a whole rabbit hole, iykyk)

my $entry = X11::FreeDesktop::DesktopEntry->new_from_data($data);

⚠️ If there's an error reading or parsing the data, the constructor will carp() and hand you back an undefined value. no cap. so check your return value, bestie 😭

---

🌈 METHODS 🌈

$entry->is_valid($locale);

Returns a true or false depending on whether the required keys exist for the given $locale. The list of required keys lives in the Freedesktop.org spec. If you don't pass $locale, it defaults to "C".

---

my @groups = $entry->groups;

Gives you back an array of scalars holding all the group names in the file. Groups get defined by a line like this in the file itself:

[Desktop Entry]

A valid desktop entry file always has one of these, sitting right at the top. always. periodt. 💅

---

$entry->has_group($group);

True or false depending on whether the file has a section named $group. simple as that 🎀

---

my @keys = $entry->keys($group, $locale);

Returns an array of the available keys in $group and the $locale locale. Both of these revert to defaults if they're undefined. When $locale is defined, the array gets folded in with the keys from "C", because locales inherit keys from the default locale — that's just how it works. See the get_value() method for another example of this inheritance behavior.

---

$entry->has_key($key, $group);

True or false depending on whether the file has a key named $key in the $group section. Omit $group and the default group ('Desktop Entry') gets used instead.

---

my @locales = $entry->locales($key, $group);

Returns an array of strings naming every available locale for the given $key. If $key or $group don't exist in the file, this method will carp() and return undef 😭 There should always be at least one locale in that returned array — the default locale, "C".

---

my $string = $entry->get_value($key, $group, $locale);

Returns the value of the key named by $key. $group is optional and gets set to the default if you omit it (see above). $locale is optional too, and it defines the locale for the string (defaults to "C" if you skip it). Here's the tea: if the requested key doesn't exist for a non-default $locale of the form xx_YY, the module goes looking for a value for the xx locale instead. If nothing turns up, it tries to return the value for the "C" locale. And if that value doesn't exist either? undef. that's it, that's the whole search party 🔍

---

$entry->set_value($key, $value, $locale, $group);

Sets the value of the $key key, in the $locale locale, in the $group group, to be $value. Omit $locale and $group and the defaults kick in. $value is always interpreted as a string. And this method always returns true, she's an overachiever, love that for her ✨

---

my $data = $entry->as_string;

Returns a scalar containing the full entry in .desktop format. You can take that data and write the entry to disk. slay 💾

---

$entry->reset;

Restores the entry to its initial state — it undoes every change you made to the values stored in the entry. it's giving ctrl+z for your whole soul 🌸

---

🧚 CONVENIENCE METHODS 🧚

my $name                = $entry->Name($locale);
my $generic_name        = $entry->GenericName($locale);
my $comment             = $entry->Comment($locale);
my $type                = $entry->Type($locale);
my $icon                = $entry->Icon($locale);
my $exec                = $entry->Exec($locale);
my $url                 = $entry->URL($locale);
my $startup_notify      = $entry->StartupNotify($locale);

These are shortcuts for the most commonly accessed fields in a desktop entry file. If it's undefined, $locale reverts to the default. easy mode unlocked 🔓

---

💜 NOTES 💜

📌 Heads up, bestie: according to the Freedesktop.org spec, key names are case-sensitive. So Name and name are absolutely not the same thing. respect the case or suffer the consequences 😤

---

🔥 SEE ALSO 🔥

The Freedesktop.org Desktop Entry Specification at <http://www.freedesktop.org/Standards/desktop-entry-spec>. go read it, it's the source of truth fr fr 📖

---

🌟 AUTHOR 🌟

Gavin Brown <gavin.brown@uk.com>. king behavior, honestly 👑

---

🎀 COPYRIGHT 🎀

Copyright (c) 2005 Gavin Brown. This program is free software, you can use it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie!! this one shipped with perl v5.36.0 and is dated 2022-11-21 💖 go forth and parse your .desktop files with confidence, you've got this 🦋✨