File::DesktopEntry - Object to handle .desktop files |
File::DesktopEntry - Object to handle .desktop files
use File::DesktopEntry; my $entry = File::DesktopEntry->new('firefox');
print "Using ".$entry->Name." to open http://perl.org\n"; $entry->run('http://perl.org');
This module is used to work with .desktop files. The format of these files is specified by the freedesktop ``Desktop Entry'' specification. This module can parse these files but also knows how to run the applciations defined by these files.
For this module version 1.0 of the specification was used.
This module was written to support the File::MimeInfo::Applications manpage.
Please remember: case is significant for the names of Desktop Entry keys.
You can set the global variable $File::DesktopEntry::VERBOSE
. If set the
module print a warning every time a command gets executed.
The global variable $File::DesktopEntry::LOCALE
tells you what the default
locale being used is. However, changing it will not change the default locale.
All methods that start with a capital are autoloaded as get(KEY)
where
key is the autoloaded method name.
new(FILE)
new(\$TEXT)
new(NAME)
When a name is given (a string without '/
', '\
' or '.
') a lookup is
done using File::BaseDir. If the file found in this lookup is not writable or
if no file was found, the XDG_DATA_HOME path will be used when writing.
lookup(NAME)
wants_uris( )
wants_list( )
system(@FILES)
run()
but using the system()
system call.
It only return after the application has ended.
exec(@FILES)
run()
but using the exec()
system call. This method
is expected not to return but to replace the current process with the
application you try to run.
On Windows this method doesn't always work the way you want it to
due to the fork()
emulation on this platform. Try using run()
or
system()
instead.
parse_Exec(@FILES)
It supports the following fields:
%f single file %F multiple files %u single url %U multiple urls %i Icon field prefixed by --icon %c Name field, possibly translated %k location of this .desktop file %% literal '%'
If necessary this method tries to convert between paths and URLs but this is not perfect.
Fields that are deprecated, but (still) supported by this module:
%d single directory %D multiple directories
The fields %n
, %N
, %v
and %m
are deprecated and will cause a
warning if $VERBOSE
is used. Any other unknown fields will cause an error.
The fields %F
, %U
, %D
and %i
can only occur as seperate words
because they expand to multiple arguments.
Also see LIMITATIONS.
get(KEY)
get(GROUP, KEY)
When KEY does not contain a language code you get the translation in the
current locale if available or a sensible default. The request a specific
language you can add the language part. E.g. $entry->get('Name[nl_NL]')
can return either the value of the 'Name[nl_NL]', the 'Name[nl]' or the 'Name'
key in the Desktop Entry file. Exact language parsing order can be found in the
spec. To force you get the untranslated key use either 'Name[C]' or
'Name[POSIX]'.
set(KEY =
VALUE, ...)>set(GROUP, KEY =
VALUE, ...)>Unlike the get()
call languages are not handled automatically for set()
.
KEY should include the language part if you want to set a translation.
E.g. $entry->set("Name[nl_NL]" => "Tekst Verwerker")
will set a Dutch
translation for the Name key. Using either ``Name[C]'' or ``Name[POSIX]'' will
be equivalent with not giving a language argument.
When setting the the Exec key without specifying a group it will be parsed and quoted correctly as required by the spec. You can use quoted arguments to include whitespace in a argument, escaping whitespace does not work. To circumvent this quoting explicitly give the group name 'Desktop Entry'.
text()
read(FILE)
read(\$SCALAR)
If you gave a file, text buffer or name to the constructor this method will be called automatically.
read_fh(IO)
write(FILE)
The keys Name and Type are required. Type can be either Application
,
Link
or Directory
. For an application set the optional key Exec
. For
a link set the URL
key.
Methods supported for backwards compatibility with 0.02.
new_from_file(FILE)
new(FILE)
.
new_from_data(TEXT)
new(\$TEXT)
.
get_value(NAME, GROUP, LANG)
get(GROUP, "NAME[LANG]")
.
LANG defaults to 'C', GROUP is optional.
This module has a few bit of code to make it save on Windows. It handles
file://
uri a bit different and it uses the Win32::Process manpage. On other
platforms your mileage may vary.
Please note that the specification is targeting Unix platforms only and will only have limited relevance on other platforms. Any platform dependend behavior in this module should be considerd an extension of the spec.
If you try to exec a remote file with an application that can only handle files
on the local file system we should -according to the spec- download the file to
a temp location. This is not supported. Use the wants_uris()
method to check
if an application supports urls.
The values of the various Desktop Entry keys are not parsed (except for the Exec key). This means that booleans will be returned as the strings ``true'' and ``false'' and lists will still be ``;'' seperated.
If the icon is given as name and not as path it should be resolved for the %i
code in the Exec key. We need a seperate module for the icon spec to deal with
this.
Files are read and writen using utf8, this is not available on perl versions before 5.8. As a result for older perl versions translations in UTF-8 will not be translated properly.
According to the spec comments can contain any encoding. However since this module read files as utf8, invalid UTF-8 characters in a comment will cause an error.
There is no support for Legacy-Mixed Encoding. Everybody is using utf8 now ... right ?
Jaap Karssenberg (Pardus) <pardus@cpan.org>
Copyright (c) 2005, 2007 Jaap G Karssenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
http://www.freedesktop.org/wiki/Specifications/desktop-entry-spec
the File::BaseDir manpage and the File::MimeInfo::Applications manpage
the X11::FreeDesktop::DesktopEntry manpage
File::DesktopEntry - Object to handle .desktop files |