.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Glib::BookmarkFile 3pm" .TH Glib::BookmarkFile 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Glib::BookmarkFile \- Parser for bookmark files .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& use Glib; \& \& $date .= $_ while (); \& \& $b = Glib::BookmarkFile\->new; \& $b\->load_from_data($data); \& $uri = \*(Aqfile:///some/path/to/a/file.txt\*(Aq; \& if ($b\->has_item($uri)) { \& $title = $b\->get_title($uri); \& $desc = $b\->get_description($uri); \& \& print "Bookmark for \`$uri\*(Aq ($title):\en"; \& print " $desc\en"; \& } \& 0; \& \& _\|_DATA_\|_ \& \& \& \& Test File \& Some test file \& \& \& \& \& \& \& \& \& \& .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" \&\fBGlib::BookmarkFile\fR lets you parse, edit or create files containing lists of bookmarks to resources pointed to by URIs, with some meta-data bound to them, following the Desktop Bookmark Specification. The recent files support inside GTK+ uses this type of files to store the list of recently used files. .PP The syntax of bookmark files is described in detail in the Desktop Bookmarks Specification, here is a quick summary: bookmark files use a subclass of the XML Bookmark Exchange Language (XBEL) document format, defining meta-data such as the MIME type of the resource pointed by a bookmark, the list of applications that have registered the same URI and the visibility of the bookmark. .SH METHODS .IX Header "METHODS" .SS "bookmarkfile = Glib::BookmarkFile\->\fBnew\fP" .IX Subsection "bookmarkfile = Glib::BookmarkFile->new" .ie n .SS "$bookmark_file\->\fBadd_application\fP ($uri, $name, $exec)" .el .SS "\f(CW$bookmark_file\fP\->\fBadd_application\fP ($uri, \f(CW$name\fP, \f(CW$exec\fP)" .IX Subsection "$bookmark_file->add_application ($uri, $name, $exec)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$name\fR (string or undef) .IP \(bu 4 \&\f(CW$exec\fR (string or undef) .PP Adds the application with \f(CW$name\fR and \f(CW$exec\fR to the list of applications that have registered a bookmark for \f(CW$uri\fR into \&\f(CW$bookmark_file\fR. .PP Every bookmark inside a \f(CW\*(C`Glib::BookmarkFile\*(C'\fR must have at least an application registered. Each application must provide a name, a command line useful for launching the bookmark, the number of times the bookmark has been registered by the application and the last time the application registered this bookmark. .PP If \f(CW$name\fR is undef, the name of the application will be the same returned by \fBGlib::get_application_name()\fR; if \f(CW$exec\fR is undef, the command line will be a composition of the program name as returned by \fBGlib::get_prgname()\fR and the "%u" modifier, which will be expanded to the bookmark's URI. .PP This function will automatically take care of updating the registrations count and timestamping in case an application with the same \f(CW$name\fR had already registered a bookmark for \&\f(CW$uri\fR inside the bookmark file. If no bookmark for \f(CW$uri\fR is found one is created. .ie n .SS "$bookmark_file\->\fBadd_group\fP ($uri, $group)" .el .SS "\f(CW$bookmark_file\fP\->\fBadd_group\fP ($uri, \f(CW$group\fP)" .IX Subsection "$bookmark_file->add_group ($uri, $group)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$group\fR (string) .PP Adds \f(CW$group\fR to the list of groups to which the bookmark for \f(CW$uri\fR belongs to. If no bookmark for \f(CW$uri\fR is found one is created. .ie n .SS "unix timestamp = $bookmark_file\->\fBget_added\fP ($uri)" .el .SS "unix timestamp = \f(CW$bookmark_file\fP\->\fBget_added\fP ($uri)" .IX Subsection "unix timestamp = $bookmark_file->get_added ($uri)" .IP \(bu 4 \&\f(CW$uri\fR (string) .ie n .SS "$bookmark_file\->\fBset_added\fP ($uri, $value)" .el .SS "\f(CW$bookmark_file\fP\->\fBset_added\fP ($uri, \f(CW$value\fP)" .IX Subsection "$bookmark_file->set_added ($uri, $value)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$value\fR (unix timestamp) .PP Sets the time the bookmark for \f(CW$uri\fR was added. If no bookmark for \f(CW$uri\fR is found one is created. .ie n .SS "($exec, $count, $stamp) = $bookmark_file\->\fBget_app_info\fP ($uri, $name)" .el .SS "($exec, \f(CW$count\fP, \f(CW$stamp\fP) = \f(CW$bookmark_file\fP\->\fBget_app_info\fP ($uri, \f(CW$name\fP)" .IX Subsection "($exec, $count, $stamp) = $bookmark_file->get_app_info ($uri, $name)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$name\fR (string) .PP Gets the registration information of \f(CW$name\fR for the bookmark for \&\f(CW$uri\fR. See \fBGlib::BookmarkFile::set_app_info()\fR for more information about the returned data. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "$bookmark_file\->\fBset_app_info\fP ($uri, $name, $exec, $count, $stamp)" .el .SS "\f(CW$bookmark_file\fP\->\fBset_app_info\fP ($uri, \f(CW$name\fP, \f(CW$exec\fP, \f(CW$count\fP, \f(CW$stamp\fP)" .IX Subsection "$bookmark_file->set_app_info ($uri, $name, $exec, $count, $stamp)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$name\fR (string) .IP \(bu 4 \&\f(CW$exec\fR (string) .IP \(bu 4 \&\f(CW$count\fR (integer) .IP \(bu 4 \&\f(CW$stamp\fR (unix timestamp) .PP Sets the meta-data of application \f(CW$name\fR inside the list of applications that have registered a bookmark for \f(CW$uri\fR inside \&\f(CW$bookmark_file\fR. .PP You should rarely use this method; use \fBGlib::BookmarkFile::add_application()\fR and \fBGlib::BookmarkFile::remove_application()\fR instead. .PP \&\f(CW$name\fR can be any UTF\-8 encoded string used to identify an application. \&\f(CW$exec\fR can have one of these two modifiers: "%f", which will be expanded as the local file name retrieved from the bookmark's URI; "%u", which will be expanded as the bookmark's URI. The expansion is done automatically when retrieving the stored command line using the \&\fBGlib::BookmarkFile::get_app_info()\fR method. \&\f(CW$count\fR is the number of times the application has registered the bookmark; if it is < 0, the current registration count will be increased by one, if it is 0, the application with \f(CW$name\fR will be removed from the list of registered applications. \&\f(CW$stamp\fR is the Unix time of the last registration, as returned by \fBtime()\fR; if it is \-1, the current time will be used. .PP If you try to remove an application by setting its registration count to zero, and no bookmark for \f(CW$uri\fR is found, \f(CW%FALSE\fR is returned and an exception is fired. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "list = $bookmark_file\->\fBget_applications\fP ($uri)" .el .SS "list = \f(CW$bookmark_file\fP\->\fBget_applications\fP ($uri)" .IX Subsection "list = $bookmark_file->get_applications ($uri)" .IP \(bu 4 \&\f(CW$uri\fR (string) .PP Retrieves the names of the applications that have registered the bookmark for \f(CW$uri\fR. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "$bookmark_file\->\fBget_description\fP ($uri)" .el .SS "\f(CW$bookmark_file\fP\->\fBget_description\fP ($uri)" .IX Subsection "$bookmark_file->get_description ($uri)" .IP \(bu 4 \&\f(CW$uri\fR (string) .PP Gets the description of the bookmark for \f(CW$uri\fR. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "$bookmark_file\->\fBset_description\fP ($uri, $description)" .el .SS "\f(CW$bookmark_file\fP\->\fBset_description\fP ($uri, \f(CW$description\fP)" .IX Subsection "$bookmark_file->set_description ($uri, $description)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$description\fR (string) .PP Sets the description of the bookmark for \f(CW$uri\fR. If no bookmark for \f(CW$uri\fR is found one is created. .ie n .SS "list = $bookmark_file\->\fBget_groups\fP ($uri)" .el .SS "list = \f(CW$bookmark_file\fP\->\fBget_groups\fP ($uri)" .IX Subsection "list = $bookmark_file->get_groups ($uri)" .IP \(bu 4 \&\f(CW$uri\fR (string) .PP Retrieves the list of group names of the bookmark for \f(CW$uri\fR. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "$bookmark_file\->\fBset_groups\fP ($uri, ...)" .el .SS "\f(CW$bookmark_file\fP\->\fBset_groups\fP ($uri, ...)" .IX Subsection "$bookmark_file->set_groups ($uri, ...)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&... (list) one or more group names .PP Sets a list of group names for the item with URI \f(CW$uri\fR. Each previously set group name list is removed. If no bookmark for \f(CW$uri\fR is found one is created. .ie n .SS "boolean = $bookmark_file\->\fBhas_application\fP ($uri, $name)" .el .SS "boolean = \f(CW$bookmark_file\fP\->\fBhas_application\fP ($uri, \f(CW$name\fP)" .IX Subsection "boolean = $bookmark_file->has_application ($uri, $name)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$name\fR (string) .PP Checks whether the bookmark for \f(CW$uri\fR inside \f(CW$bookmark_file\fR has been registered by application \f(CW$name\fR. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "boolean = $bookmark_file\->\fBhas_group\fP ($uri, $group)" .el .SS "boolean = \f(CW$bookmark_file\fP\->\fBhas_group\fP ($uri, \f(CW$group\fP)" .IX Subsection "boolean = $bookmark_file->has_group ($uri, $group)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$group\fR (string) .PP Checks whether \f(CW$group\fR appears in the list of groups to which the bookmark for \f(CW$uri\fR belongs to. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "boolean = $bookmark_file\->\fBhas_item\fP ($uri)" .el .SS "boolean = \f(CW$bookmark_file\fP\->\fBhas_item\fP ($uri)" .IX Subsection "boolean = $bookmark_file->has_item ($uri)" .IP \(bu 4 \&\f(CW$uri\fR (string) .PP Looks whether the bookmark file has a bookmark for \f(CW$uri\fR. .ie n .SS "($href, $mime_type) = $bookmark_file\->\fBget_icon\fP ($uri)" .el .SS "($href, \f(CW$mime_type\fP) = \f(CW$bookmark_file\fP\->\fBget_icon\fP ($uri)" .IX Subsection "($href, $mime_type) = $bookmark_file->get_icon ($uri)" .IP \(bu 4 \&\f(CW$uri\fR (string) .PP Gets the icon of the bookmark for \f(CW$uri\fR. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "$bookmark_file\->\fBset_icon\fP ($uri, $href, $mime_type)" .el .SS "\f(CW$bookmark_file\fP\->\fBset_icon\fP ($uri, \f(CW$href\fP, \f(CW$mime_type\fP)" .IX Subsection "$bookmark_file->set_icon ($uri, $href, $mime_type)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$href\fR (string or undef) .IP \(bu 4 \&\f(CW$mime_type\fR (string or undef) .PP Sets the icon for the bookmark for \f(CW$uri\fR. If \f(CW$href\fR is undef, unsets the currently set icon. .ie n .SS "boolean = $bookmark_file\->\fBget_is_private\fP ($uri)" .el .SS "boolean = \f(CW$bookmark_file\fP\->\fBget_is_private\fP ($uri)" .IX Subsection "boolean = $bookmark_file->get_is_private ($uri)" .IP \(bu 4 \&\f(CW$uri\fR (string) .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "$bookmark_file\->\fBset_is_private\fP ($uri, $is_private)" .el .SS "\f(CW$bookmark_file\fP\->\fBset_is_private\fP ($uri, \f(CW$is_private\fP)" .IX Subsection "$bookmark_file->set_is_private ($uri, $is_private)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$is_private\fR (boolean) .ie n .SS "$bookmark_file\->\fBload_from_data\fP ($buf)" .el .SS "\f(CW$bookmark_file\fP\->\fBload_from_data\fP ($buf)" .IX Subsection "$bookmark_file->load_from_data ($buf)" .IP \(bu 4 \&\f(CW$buf\fR (scalar) .PP Parses a string containing a bookmark file structure. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "($full_path) = $bookmark_file\->\fBload_from_data_dirs\fP ($file)" .el .SS "($full_path) = \f(CW$bookmark_file\fP\->\fBload_from_data_dirs\fP ($file)" .IX Subsection "($full_path) = $bookmark_file->load_from_data_dirs ($file)" .IP \(bu 4 \&\f(CW$file\fR (localized file name) .PP Parses a bookmark file, searching for it inside the data directories. If a file is found, it returns the full path. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "$bookmark_file\->\fBload_from_file\fP ($file)" .el .SS "\f(CW$bookmark_file\fP\->\fBload_from_file\fP ($file)" .IX Subsection "$bookmark_file->load_from_file ($file)" .IP \(bu 4 \&\f(CW$file\fR (localized file name) .PP Parses a bookmark file. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "string = $bookmark_file\->\fBget_mime_type\fP ($uri)" .el .SS "string = \f(CW$bookmark_file\fP\->\fBget_mime_type\fP ($uri)" .IX Subsection "string = $bookmark_file->get_mime_type ($uri)" .IP \(bu 4 \&\f(CW$uri\fR (string) .PP Gets the MIME type of the bookmark for \f(CW$uri\fR. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "$bookmark_file\->\fBset_mime_type\fP ($uri, $mime_type)" .el .SS "\f(CW$bookmark_file\fP\->\fBset_mime_type\fP ($uri, \f(CW$mime_type\fP)" .IX Subsection "$bookmark_file->set_mime_type ($uri, $mime_type)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$mime_type\fR (string) .PP Sets the MIME type of the bookmark for \f(CW$uri\fR. If no bookmark for \f(CW$uri\fR is found one is created. .ie n .SS "unix timestamp = $bookmark_file\->\fBget_modified\fP ($uri)" .el .SS "unix timestamp = \f(CW$bookmark_file\fP\->\fBget_modified\fP ($uri)" .IX Subsection "unix timestamp = $bookmark_file->get_modified ($uri)" .IP \(bu 4 \&\f(CW$uri\fR (string) .ie n .SS "$bookmark_file\->\fBset_modified\fP ($uri, $value)" .el .SS "\f(CW$bookmark_file\fP\->\fBset_modified\fP ($uri, \f(CW$value\fP)" .IX Subsection "$bookmark_file->set_modified ($uri, $value)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$value\fR (unix timestamp) .PP Sets the time the bookmark for \f(CW$uri\fR was last modified. If no bookmark for \f(CW$uri\fR is found one is created. .ie n .SS "$bookmark_file\->\fBmove_item\fP ($old_uri, $new_uri)" .el .SS "\f(CW$bookmark_file\fP\->\fBmove_item\fP ($old_uri, \f(CW$new_uri\fP)" .IX Subsection "$bookmark_file->move_item ($old_uri, $new_uri)" .IP \(bu 4 \&\f(CW$old_uri\fR (string) .IP \(bu 4 \&\f(CW$new_uri\fR (string or undef) .PP Changes the URI of a bookmark item from \f(CW$old_uri\fR to \f(CW$new_uri\fR. Any existing bookmark for \f(CW$new_uri\fR will be overwritten. If \f(CW$new_uri\fR is undef, then the bookmark is removed. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "$bookmark_file\->\fBremove_application\fP ($uri, $name)" .el .SS "\f(CW$bookmark_file\fP\->\fBremove_application\fP ($uri, \f(CW$name\fP)" .IX Subsection "$bookmark_file->remove_application ($uri, $name)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$name\fR (string) .PP Removes application registered with \f(CW$name\fR from the list of applications that have registered a bookmark for \f(CW$uri\fR inside \f(CW$bookmark_file\fR. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "$bookmark_file\->\fBremove_group\fP ($uri, $group)" .el .SS "\f(CW$bookmark_file\fP\->\fBremove_group\fP ($uri, \f(CW$group\fP)" .IX Subsection "$bookmark_file->remove_group ($uri, $group)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$group\fR (string) .PP Removes \f(CW$group\fR from the list of groups to which the bookmark for \f(CW$uri\fR belongs to. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "$bookmark_file\->\fBremove_item\fP ($uri)" .el .SS "\f(CW$bookmark_file\fP\->\fBremove_item\fP ($uri)" .IX Subsection "$bookmark_file->remove_item ($uri)" .IP \(bu 4 \&\f(CW$uri\fR (string) .PP Removes the bookmark for \f(CW$uri\fR from the bookmark file. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "integer = $bookmark_file\->\fBget_size\fP" .el .SS "integer = \f(CW$bookmark_file\fP\->\fBget_size\fP" .IX Subsection "integer = $bookmark_file->get_size" Gets the number of bookmarks inside the bookmark file. .ie n .SS "$bookmark_file\->\fBget_title\fP ($uri, $title)" .el .SS "\f(CW$bookmark_file\fP\->\fBget_title\fP ($uri, \f(CW$title\fP)" .IX Subsection "$bookmark_file->get_title ($uri, $title)" .IP \(bu 4 \&\f(CW$uri\fR (string) .PP Gets the title of the bookmark for \f(CW$uri\fR. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "$bookmark_file\->\fBset_title\fP ($uri, $title)" .el .SS "\f(CW$bookmark_file\fP\->\fBset_title\fP ($uri, \f(CW$title\fP)" .IX Subsection "$bookmark_file->set_title ($uri, $title)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$title\fR (string) .PP Sets the title of the bookmark for \f(CW$uri\fR. If no bookmark for \f(CW$uri\fR is found one is created. .ie n .SS "string = $bookmark_file\->\fBto_data\fP" .el .SS "string = \f(CW$bookmark_file\fP\->\fBto_data\fP" .IX Subsection "string = $bookmark_file->to_data" Returns the bookmark file as a string. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "$bookmark_file\->\fBto_file\fP ($file)" .el .SS "\f(CW$bookmark_file\fP\->\fBto_file\fP ($file)" .IX Subsection "$bookmark_file->to_file ($file)" .IP \(bu 4 \&\f(CW$file\fR (localized file name) .PP Saves the contents of a bookmark file into a file. The write operation is guaranteed to be atomic by writing the contents of the bookmark file to a temporary file and then moving the file to the target file. .PP May croak with a Glib::Error in $@ on failure. .ie n .SS "list = $bookmark_file\->\fBget_uris\fP" .el .SS "list = \f(CW$bookmark_file\fP\->\fBget_uris\fP" .IX Subsection "list = $bookmark_file->get_uris" Returns the URI of all the bookmarks in the bookmark file. .ie n .SS "unix timestamp = $bookmark_file\->\fBget_visited\fP ($uri)" .el .SS "unix timestamp = \f(CW$bookmark_file\fP\->\fBget_visited\fP ($uri)" .IX Subsection "unix timestamp = $bookmark_file->get_visited ($uri)" .IP \(bu 4 \&\f(CW$uri\fR (string) .ie n .SS "$bookmark_file\->\fBset_visited\fP ($uri, $value)" .el .SS "\f(CW$bookmark_file\fP\->\fBset_visited\fP ($uri, \f(CW$value\fP)" .IX Subsection "$bookmark_file->set_visited ($uri, $value)" .IP \(bu 4 \&\f(CW$uri\fR (string) .IP \(bu 4 \&\f(CW$value\fR (unix timestamp) .PP Sets the time the bookmark for \f(CW$uri\fR was last visited. If no bookmark for \f(CW$uri\fR is found one is created. .SH "SEE ALSO" .IX Header "SEE ALSO" Glib .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright (C) 2003\-2011 by the gtk2\-perl team. .PP This software is licensed under the LGPL. See Glib for a full notice.