view release on metacpan or  search on metacpan

local/man/man3/Glib::BookmarkFile.3pm  view on Meta::CPAN

'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 3"
.TH Glib::BookmarkFile 3 "2019-03-03" "perl v5.28.1" "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 (<DATA>);
\&
\&  $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_\|_
\&  <?xml version="1.0" encoding="UTF\-8"?>
\&  <xbel version="1.0"
\&        xmlns:bookmark="http://www.freedesktop.org/standards/desktop\-bookmarks"
\&        xmlns:mime="http://www.freedesktop.org/standards/shared\-mime\-info">
\&    <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">
\&      <title>Test File</title>
\&      <desc>Some test file</desc>
\&      <info>
\&        <metadata owner="http://freedesktop.org">
\&          <mime:mime\-type type="text/plain"/>
\&          <bookmark:applications>
\&            <bookmark:application name="Gedit" exec="gedit %u" timestamp="1143053640" count="1"/>
\&          </bookmark:applications>
\&        </metadata>
\&      </info>
\&    </bookmark>
\&  </xbel>
.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 \s-1GTK+\s0 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
\&\s-1XML\s0 Bookmark Exchange Language (\s-1XBEL\s0) document format, defining meta-data
such as the \s-1MIME\s0 type of the resource pointed by a bookmark, the list of
applications that have registered the same \s-1URI\s0 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 \*(L"%u\*(R" modifier, which will
be expanded to the bookmark's \s-1URI.\s0
.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)"