X11::FreeDesktop::DesktopEntry - 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
new() 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
PerlPanel::DesktopEntry 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
carp() and return an undefined value.
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 '
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:
A valid desktop entry file will always have one of these, at the top.
Returns true or false depending on whether the file has a section with the name of
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', since locales inherit keys from the default locale. See the
get_value() method for another example of this inheritance.
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
$group don't exist in the file, this method will
carp() and return undef. There should always be at least one locale in the returned array - the default locale, '
my $string = $entry->get_value($key, $group, $locale);
Returns the value of the key named by
$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' if omitted). If the requested key does not exist for a non-default
$locale of the form
xx_YY, then the module will search for a value for the
xx locale. If nothing is found, this method will attempt to return the value for the '
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
$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.
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@example.com>.
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.