An interface to freedesktop.org .desktop files.
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;
This module provides an object-oriented interface to files that comply with the Freedesktop.org desktop entry specification. You can query the file for available values, modify them, and also get locale information as well.
X11::FreeDesktop::DesktopEntry doesn't have the standard \*(C`new()\*(C' constructor. This allows subclasses to implement their own backend-specific constructor without needing to re-implement the constructor, which can be a pain (for an example subclass that uses Gnome2::VFS as a backend, see the \*(C`PerlPanel::DesktopEntry\*(C' module in the PerlPanel distribution).
my $entry = X11::FreeDesktop::DesktopEntry->new_from_data($data);
If there is an error reading or parsing the data, the constructor will \*(C`carp()\*(C' and return an undefined value.
$entry->is_valid($locale);
Returns a true or false valid depending on whether the required keys exist for the given $locale. A list of the required keys can be found in the Freedesktop.org specification. If $locale is omitted, it will default to '\*(C`C\*(C''.
my @groups = $entry->groups;
This returns an array of scalars containing the group names included in the file. Groups are defined by a line like the following in the file itself:
[Desktop Entry]
A valid desktop entry file will always have one of these, at the top.
$entry->has_group($group);
Returns true or false depending on whether the file has a section with the name of $group.
my @keys = $entry->keys($group, $locale);
Returns an array of the available keys in $group and the $locale locale. Both these values revert to defaults if they're undefined. When $locale is defined, the array will be folded in with the keys from '\*(C`C\*(C'', since locales inherit keys from the default locale. See the \*(C`get_value()\*(C' method for another example of this inheritance.
$entry->has_key($key, $group);
Returns true or false depending on whether the file has a key with the name of $key in the $group section. If $group is omitted, then the default group ('Desktop Entry') will be used.
my @locales = $entry->locales($key, $group);
Returns an array of strings naming all the available locales for the given $key. If $key or $group don't exist in the file, this method will \*(C`carp()\*(C' and return undef. There should always be at least one locale in the returned array - the default locale, '\*(C`C\*(C''.
my $string = $entry->get_value($key, $group, $locale);
Returns the value of the key named by $key. $group is optional, and will be set to the default if omitted (see above). $locale is also optional, and defines the locale for the string (defaults to '\*(C`C\*(C'' if omitted). If the requested key does not exist for a non-default $locale of the form \*(C`xx_YY\*(C', then the module will search for a value for the \*(C`xx\*(C' locale. If nothing is found, this method will attempt to return the value for the '\*(C`C\*(C'' locale. If this value does not exist, this method will return undef.
$entry->set_value($key, $value, $locale, $group);
This method sets the value of the $key key in the $locale locale and $group group to be $value. If $locale and $group are omitted, the defaults are used. $value is always interpreted as a string. This method always returns true.
my $data = $entry->as_string;
This method returns a scalar containing the full entry in .desktop format. This data can then be used to write the entry to disk.
$entry->reset;
This method restores the entry to its initial state - it undoes any changes made to the values stored in the entry.
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 methods are shortcuts for the mostly commonly accessed fields from a desktop entry file. If undefined, $locale reverts to the default.
Please note that according to the Freedesktop.org spec, key names are case-sensitive.
The Freedesktop.org Desktop Entry Specification at <http://www.freedesktop.org/Standards/desktop-entry-spec>.
Gavin Brown <[email protected]>.
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.