1Glib::BookmarkFile(3) User Contributed Perl DocumentationGlib::BookmarkFile(3)
2
3
4

NAME

6       Glib::BookmarkFile -  Parser for bookmark files
7

SYNOPSIS

9         use Glib;
10
11         $date .= $_ while (<DATA>);
12
13         $b = Glib::BookmarkFile->new;
14         $b->load_from_data($data);
15         $uri = 'file:///some/path/to/a/file.txt';
16         if ($b->has_item($uri)) {
17               $title = $b->get_title($uri);
18               $desc  = $b->get_description($uri);
19
20               print "Bookmark for `$uri' ($title):\n";
21               print "  $desc\n";
22         }
23         0;
24
25         __DATA__
26         <?xml version="1.0" encoding="UTF-8"?>
27         <xbel version="1.0"
28               xmlns:bookmark="http://www.freedesktop.org/standards/desktop-bookmarks"
29               xmlns:mime="http://www.freedesktop.org/standards/shared-mime-info">
30           <bookmark href="file:///tmp/test-file.txt" added="2006-03-22T18:54:00Z" modified="2006-03-22T18:54:00Z" visited="2006-03-22T18:54:00Z">
31             <title>Test File</title>
32             <desc>Some test file</desc>
33             <info>
34               <metadata owner="http://freedesktop.org">
35                 <mime:mime-type type="text/plain"/>
36                 <bookmark:applications>
37                   <bookmark:application name="Gedit" exec="gedit %u" timestamp="1143053640" count="1"/>
38                 </bookmark:applications>
39               </metadata>
40             </info>
41           </bookmark>
42         </xbel>
43

DESCRIPTION

45       Glib::BookmarkFile lets you parse, edit or create files containing
46       lists of bookmarks to resources pointed to by URIs, with some meta-data
47       bound to them, following the Desktop Bookmark Specification.  The
48       recent files support inside GTK+ uses this type of files to store the
49       list of recently used files.
50
51       The syntax of bookmark files is described in detail in the Desktop
52       Bookmarks Specification, here is a quick summary: bookmark files use a
53       subclass of the XML Bookmark Exchange Language (XBEL) document format,
54       defining meta-data such as the MIME type of the resource pointed by a
55       bookmark, the list of applications that have registered the same URI
56       and the visibility of the bookmark.
57

METHODS

59   bookmarkfile = Glib::BookmarkFile->new
60   $bookmark_file->add_application ($uri, $name, $exec)
61       ·   $uri (string)
62
63       ·   $name (string or undef)
64
65       ·   $exec (string or undef)
66
67       Adds the application with $name and $exec to the list of applications
68       that have registered a bookmark for $uri into $bookmark_file.
69
70       Every bookmark inside a "Glib::BookmarkFile" must have at least an
71       application registered.  Each application must provide a name, a
72       command line useful for launching the bookmark, the number of times the
73       bookmark has been registered by the application and the last time the
74       application registered this bookmark.
75
76       If $name is undef, the name of the application will be the same
77       returned by Glib::get_application_name(); if $exec is undef, the
78       command line will be a composition of the program name as returned by
79       Glib::get_prgname() and the "%u" modifier, which will be expanded to
80       the bookmark's URI.
81
82       This function will automatically take care of updating the
83       registrations count and timestamping in case an application with the
84       same $name had already registered a bookmark for $uri inside the
85       bookmark file.  If no bookmark for $uri is found one is created.
86
87   $bookmark_file->add_group ($uri, $group)
88       ·   $uri (string)
89
90       ·   $group (string)
91
92       Adds $group to the list of groups to which the bookmark for $uri
93       belongs to.  If no bookmark for $uri is found one is created.
94
95   unix timestamp = $bookmark_file->get_added ($uri)
96       ·   $uri (string)
97
98   $bookmark_file->set_added ($uri, $value)
99       ·   $uri (string)
100
101       ·   $value (unix timestamp)
102
103       Sets the time the bookmark for $uri was added.  If no bookmark for $uri
104       is found one is created.
105
106   ($exec, $count, $stamp) = $bookmark_file->get_app_info ($uri, $name)
107       ·   $uri (string)
108
109       ·   $name (string)
110
111       Gets the registration information of $name for the bookmark for $uri.
112       See Glib::BookmarkFile::set_app_info() for more information about the
113       returned data.
114
115       May croak with a Glib::Error in $@ on failure.
116
117   $bookmark_file->set_app_info ($uri, $name, $exec, $count, $stamp)
118       ·   $uri (string)
119
120       ·   $name (string)
121
122       ·   $exec (string)
123
124       ·   $count (integer)
125
126       ·   $stamp (unix timestamp)
127
128       Sets the meta-data of application $name inside the list of applications
129       that have registered a bookmark for $uri inside $bookmark_file.
130
131       You should rarely use this method; use
132       Glib::BookmarkFile::add_application() and
133       Glib::BookmarkFile::remove_application() instead.
134
135       $name can be any UTF-8 encoded string used to identify an application.
136       $exec can have one of these two modifiers: "%f", which will be expanded
137       as the local file name retrieved from the bookmark's URI; "%u", which
138       will be expanded as the bookmark's URI. The expansion is done
139       automatically when retrieving the stored command line using the
140       Glib::BookmarkFile::get_app_info() method.  $count is the number of
141       times the application has registered the bookmark; if it is < 0, the
142       current registration count will be increased by one, if it is 0, the
143       application with $name will be removed from the list of registered
144       applications.  $stamp is the Unix time of the last registration, as
145       returned by time(); if it is -1, the current time will be used.
146
147       If you try to remove an application by setting its registration count
148       to zero, and no bookmark for $uri is found, %FALSE is returned and an
149       exception is fired.
150
151       May croak with a Glib::Error in $@ on failure.
152
153   list = $bookmark_file->get_applications ($uri)
154       ·   $uri (string)
155
156       Retrieves the names of the applications that have registered the
157       bookmark for $uri.
158
159       May croak with a Glib::Error in $@ on failure.
160
161   $bookmark_file->get_description ($uri)
162       ·   $uri (string)
163
164       Gets the description of the bookmark for $uri.
165
166       May croak with a Glib::Error in $@ on failure.
167
168   $bookmark_file->set_description ($uri, $description)
169       ·   $uri (string)
170
171       ·   $description (string)
172
173       Sets the description of the bookmark for $uri.  If no bookmark for $uri
174       is found one is created.
175
176   list = $bookmark_file->get_groups ($uri)
177       ·   $uri (string)
178
179       Retrieves the list of group names of the bookmark for $uri.
180
181       May croak with a Glib::Error in $@ on failure.
182
183   $bookmark_file->set_groups ($uri, ...)
184       ·   $uri (string)
185
186       ·   ... (list) one or more group names
187
188       Sets a list of group names for the item with URI $uri.  Each previously
189       set group name list is removed.  If no bookmark for $uri is found one
190       is created.
191
192   boolean = $bookmark_file->has_application ($uri, $name)
193       ·   $uri (string)
194
195       ·   $name (string)
196
197       Checks whether the bookmark for $uri inside $bookmark_file has been
198       registered by application $name.
199
200       May croak with a Glib::Error in $@ on failure.
201
202   boolean = $bookmark_file->has_group ($uri, $group)
203       ·   $uri (string)
204
205       ·   $group (string)
206
207       Checks whether $group appears in the list of groups to which the
208       bookmark for $uri belongs to.
209
210       May croak with a Glib::Error in $@ on failure.
211
212   boolean = $bookmark_file->has_item ($uri)
213       ·   $uri (string)
214
215       Looks whether the bookmark file has a bookmark for $uri.
216
217   ($href, $mime_type) = $bookmark_file->get_icon ($uri)
218       ·   $uri (string)
219
220       Gets the icon of the bookmark for $uri.
221
222       May croak with a Glib::Error in $@ on failure.
223
224   $bookmark_file->set_icon ($uri, $href, $mime_type)
225       ·   $uri (string)
226
227       ·   $href (string or undef)
228
229       ·   $mime_type (string or undef)
230
231       Sets the icon for the bookmark for $uri.  If $href is undef, unsets the
232       currently set icon.
233
234   boolean = $bookmark_file->get_is_private ($uri)
235       ·   $uri (string)
236
237       May croak with a Glib::Error in $@ on failure.
238
239   $bookmark_file->set_is_private ($uri, $is_private)
240       ·   $uri (string)
241
242       ·   $is_private (boolean)
243
244   $bookmark_file->load_from_data ($buf)
245       ·   $buf (scalar)
246
247       Parses a string containing a bookmark file structure.
248
249       May croak with a Glib::Error in $@ on failure.
250
251   ($full_path) = $bookmark_file->load_from_data_dirs ($file)
252       ·   $file (localized file name)
253
254       Parses a bookmark file, searching for it inside the data directories.
255       If a file is found, it returns the full path.
256
257       May croak with a Glib::Error in $@ on failure.
258
259   $bookmark_file->load_from_file ($file)
260       ·   $file (localized file name)
261
262       Parses a bookmark file.
263
264       May croak with a Glib::Error in $@ on failure.
265
266   string = $bookmark_file->get_mime_type ($uri)
267       ·   $uri (string)
268
269       Gets the MIME type of the bookmark for $uri.
270
271       May croak with a Glib::Error in $@ on failure.
272
273   $bookmark_file->set_mime_type ($uri, $mime_type)
274       ·   $uri (string)
275
276       ·   $mime_type (string)
277
278       Sets the MIME type of the bookmark for $uri.  If no bookmark for $uri
279       is found one is created.
280
281   unix timestamp = $bookmark_file->get_modified ($uri)
282       ·   $uri (string)
283
284   $bookmark_file->set_modified ($uri, $value)
285       ·   $uri (string)
286
287       ·   $value (unix timestamp)
288
289       Sets the time the bookmark for $uri was last modified.  If no bookmark
290       for $uri is found one is created.
291
292   $bookmark_file->move_item ($old_uri, $new_uri)
293       ·   $old_uri (string)
294
295       ·   $new_uri (string or undef)
296
297       Changes the URI of a bookmark item from $old_uri to $new_uri.  Any
298       existing bookmark for $new_uri will be overwritten.  If $new_uri is
299       undef, then the bookmark is removed.
300
301       May croak with a Glib::Error in $@ on failure.
302
303   $bookmark_file->remove_application ($uri, $name)
304       ·   $uri (string)
305
306       ·   $name (string)
307
308       Removes application registered with $name from the list of applications
309       that have registered a bookmark for $uri inside $bookmark_file.
310
311       May croak with a Glib::Error in $@ on failure.
312
313   $bookmark_file->remove_group ($uri, $group)
314       ·   $uri (string)
315
316       ·   $group (string)
317
318       Removes $group from the list of groups to which the bookmark for $uri
319       belongs to.
320
321       May croak with a Glib::Error in $@ on failure.
322
323   $bookmark_file->remove_item ($uri)
324       ·   $uri (string)
325
326       Removes the bookmark for $uri from the bookmark file.
327
328       May croak with a Glib::Error in $@ on failure.
329
330   integer = $bookmark_file->get_size
331       Gets the number of bookmarks inside the bookmark file.
332
333   $bookmark_file->get_title ($uri, $title)
334       ·   $uri (string)
335
336       Gets the title of the bookmark for $uri.
337
338       May croak with a Glib::Error in $@ on failure.
339
340   $bookmark_file->set_title ($uri, $title)
341       ·   $uri (string)
342
343       ·   $title (string)
344
345       Sets the title of the bookmark for $uri.  If no bookmark for $uri is
346       found one is created.
347
348   string = $bookmark_file->to_data
349       Returns the bookmark file as a string.
350
351       May croak with a Glib::Error in $@ on failure.
352
353   $bookmark_file->to_file ($file)
354       ·   $file (localized file name)
355
356       Saves the contents of a bookmark file into a file.  The write operation
357       is guaranteed to be atomic by writing the contents of the bookmark file
358       to a temporary file and then moving the file to the target file.
359
360       May croak with a Glib::Error in $@ on failure.
361
362   list = $bookmark_file->get_uris
363       Returns the URI of all the bookmarks in the bookmark file.
364
365   unix timestamp = $bookmark_file->get_visited ($uri)
366       ·   $uri (string)
367
368   $bookmark_file->set_visited ($uri, $value)
369       ·   $uri (string)
370
371       ·   $value (unix timestamp)
372
373       Sets the time the bookmark for $uri was last visited.  If no bookmark
374       for $uri is found one is created.
375

SEE ALSO

377       Glib
378
380       Copyright (C) 2003-2011 by the gtk2-perl team.
381
382       This software is licensed under the LGPL.  See Glib for a full notice.
383
384
385
386perl v5.30.0                      2019-07-29             Glib::BookmarkFile(3)
Impressum