File::DesktopEntry(3pm)

1File::DesktopEntry(3) User Contributed Perl DocumentationFile::DesktopEntry(3)
2
3
4

NAME

6       File::DesktopEntry - Object to handle .desktop files
7

SYNOPSIS

9           use File::DesktopEntry;
10
11           my $entry = File::DesktopEntry->new('firefox');
12
13           print "Using ".$entry->Name." to open http://perl.org\n";
14           $entry->run('http://perl.org');
15

DESCRIPTION

17       This module is designed to work with .desktop files. The format of
18       these files is specified by the freedesktop "Desktop Entry"
19       specification. This module can parse these files but also knows how to
20       run the applications defined by these files.
21
22       For this module version 1.0 of the specification was used.
23
24       This module was written to support File::MimeInfo::Applications.
25
26       Please remember: case is significant for the names of Desktop Entry
27       keys.
28

VARIABLES

30       You can set the global variable $File::DesktopEntry::VERBOSE. If set
31       the module prints a warning every time a command gets executed.
32
33       The global variable $File::DesktopEntry::LOCALE tells you what the
34       default locale being used is. However, changing it will not change the
35       default locale.
36

AUTOLOAD

38       All methods that start with a capital are autoloaded as "get(KEY)"
39       where key is the autoloaded method name.
40

METHODS

42       "new(FILE)"
43       "new(\$TEXT)"
44       "new(NAME)"
45           Constructor. FILE, NAME or TEXT are optional arguments.
46
47           When a name is given (a string without '"/"', '"\"' or '"."') a
48           lookup is done using File::BaseDir. If the file found in this
49           lookup is not writable or if no file was found, the XDG_DATA_HOME
50           path will be used when writing.
51
52       "lookup(NAME)"
53           Returns a filename for a desktop entry with desktop file id NAME.
54
55       "wants_uris( )"
56           Returns true if the Exec string for this desktop entry specifies
57           that the application uses URIs instead of paths. This can be used
58           to determine whether an application uses a VFS library.
59
60       "wants_list( )"
61           Returns true if the Exec string for this desktop entry specifies
62           that the application can handle multiple arguments at once.
63
64       "run(@FILES)"
65           Forks and runs the application specified in this Desktop Entry with
66           arguments FILES as a background process. Returns the pid.
67
68           The child process fails when this is not a Desktop Entry of type
69           Application or if the Exec key is missing or invalid.
70
71           If the desktop entry specifies that the program needs to be
72           executed in a terminal the $TERMINAL environment variable is used.
73           If this variable is not set "xterm -e" is used as default.
74
75           (On Windows this method returns a Win32::Process object.)
76
77       "system(@FILES)"
78           Like "run()" but using the "system()" system call.  It only return
79           after the application has ended.
80
81       "exec(@FILES)"
82           Like "run()" but using the "exec()" system call. This method is
83           expected not to return but to replace the current process with the
84           application you try to run.
85
86           On Windows this method doesn't always work the way you want it to
87           due to the "fork()" emulation on this platform. Try using "run()"
88           or "system()" instead.
89
90       "parse_Exec(@FILES)"
91           Expands the Exec format in this desktop entry with. Returns a
92           properly quoted string in scalar context or a list of words in list
93           context. Dies when the Exec key is invalid.
94
95           It supports the following fields:
96
97               %f    single file
98               %F    multiple files
99               %u    single url
100               %U    multiple urls
101               %i    Icon field prefixed by --icon
102               %c    Name field, possibly translated
103               %k    location of this .desktop file
104               %%    literal '%'
105
106           If necessary this method tries to convert between paths and URLs
107           but this is not perfect.
108
109           Fields that are deprecated, but (still) supported by this module:
110
111               %d    single directory
112               %D    multiple directories
113
114           The fields %n, %N, %v and %m are deprecated and will cause a
115           warning if $VERBOSE is used. Any other unknown fields will cause an
116           error.
117
118           The fields %F, %U, %D and %i can only occur as separate words
119           because they expand to multiple arguments.
120
121           Also see "LIMITATIONS".
122
123       "get(KEY)"
124       "get(GROUP, KEY)"
125           Get a value for KEY from GROUP. If GROUP is not specified 'Desktop
126           Entry' is used. All values are treated as string, so e.g. booleans
127           will be returned as the literal strings "true" and "false".
128
129           When KEY does not contain a language code you get the translation
130           in the current locale if available or a sensible default. The
131           request a specific language you can add the language part. E.g.
132           "$entry->get('Name[nl_NL]')" can return either the value of the
133           'Name[nl_NL]', the 'Name[nl]' or the 'Name' key in the Desktop
134           Entry file. Exact language parsing order can be found in the spec.
135           To force you get the untranslated key use either 'Name[C]' or
136           'Name[POSIX]'.
137
138       "set(KEY => VALUE, ...)"
139       "set(GROUP, KEY => VALUE, ...)"
140           Set values for one or more keys. If GROUP is not given "Desktop
141           Entry" is used.  All values are treated as strings, backslashes,
142           newlines and tabs are escaped.  To set a boolean key you need to
143           use the literal strings "true" and "false".
144
145           Unlike the "get()" call languages are not handled automatically for
146           "set()".  KEY should include the language part if you want to set a
147           translation.  E.g. "$entry->set("Name[nl_NL]" => "Tekst
148           Verwerker")" will set a Dutch translation for the Name key. Using
149           either "Name[C]" or "Name[POSIX]" will be equivalent with not
150           giving a language argument.
151
152           When setting the Exec key without specifying a group it will be
153           parsed and quoted correctly as required by the spec. You can use
154           quoted arguments to include whitespace in a argument, escaping
155           whitespace does not work.  To circumvent this quoting explicitly
156           give the group name 'Desktop Entry'.
157
158       "text()"
159           Returns the (modified) text of the file.
160
161       "read(FILE)"
162       "read(\$SCALAR)"
163           Read Desktop Entry data from file or memory buffer.  Without
164           argument defaults to file given at constructor.
165
166           If you gave a file, text buffer or name to the constructor this
167           method will be called automatically.
168
169       "read_fh(IO)"
170           Read Desktop Entry data from filehandle or IO object.
171
172       "write(FILE)"
173           Write the Desktop Entry data to FILE. Without arguments it writes
174           to the filename given to the constructor if any.
175
176           The keys Name and Type are required. Type can be either
177           "Application", "Link" or "Directory". For an application set the
178           optional key "Exec". For a link set the "URL" key.
179
180   Backwards Compatibility
181       Methods supported for backwards compatibility with 0.02.
182
183       "new_from_file(FILE)"
184           Alias for "new(FILE)".
185
186       "new_from_data(TEXT)"
187           Alias for "new(\$TEXT)".
188
189       "get_value(NAME, GROUP, LANG)"
190           Identical to "get(GROUP, "NAME[LANG]")".  LANG defaults to 'C',
191           GROUP is optional.
192

NON-UNIX PLATFORMS

194       This module has a few bits of code to make it work on Windows. It
195       handles "file://" uri a bit different and it uses Win32::Process. On
196       other platforms your mileage may vary.
197
198       Please note that the specification is targeting Unix platforms only and
199       will only have limited relevance on other platforms. Any platform-
200       dependent behavior in this module should be considered an extension of
201       the spec.
202

LIMITATIONS

204       If you try to exec a remote file with an application that can only
205       handle files on the local file system we should -according to the spec-
206       download the file to a temp location. This is not supported. Use the
207       "wants_uris()" method to check if an application supports urls.
208
209       The values of the various Desktop Entry keys are not parsed (except for
210       the Exec key). This means that booleans will be returned as the strings
211       "true" and "false" and lists will still be ";" separated.
212
213       If the icon is given as name and not as path it should be resolved for
214       the %i code in the Exec key. We need a separate module for the icon
215       spec to deal with this.
216
217       According to the spec comments can contain any encoding. However since
218       this module read files as utf8, invalid UTF-8 characters in a comment
219       will cause an error.
220
221       There is no support for Legacy-Mixed Encoding. Everybody is using utf8
222       now ... right ?
223

AUTHOR

225       Jaap Karssenberg (Pardus) <pardus@cpan.org>
226
227       Maintained by Michiel Beijen <michielb@cpan.org>
228
229       Copyright (c) 2005, 2007 Jaap G Karssenberg. All rights reserved.
230

LICENSE

232       This program is free software; you can redistribute it and/or modify it
233       under the same terms as Perl itself.
234