Glib::BookmarkFile(3pm)

User Contributed Perl Documentation

Glib::BookmarkFile(3pm)

NAME¶

Glib::BookmarkFile - Parser for bookmark files

SYNOPSIS¶

  use Glib;
  $date .= $_ while (<DATA>);
  $b = Glib::BookmarkFile->new;
  $b->load_from_data($data);
  $uri = 'file:///some/path/to/a/file.txt';
  if ($b->has_item($uri)) {
        $title = $b->get_title($uri);
        $desc  = $b->get_description($uri);
        print "Bookmark for `$uri' ($title):\n";
        print "  $desc\n";
  }
  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>

DESCRIPTION¶

Glib::BookmarkFile 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.

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.

METHODS¶

bookmarkfile = Glib::BookmarkFile->new¶

$bookmark_file->add_application ($uri, $name, $exec)¶

•: $uri (string)

•: $name (string or undef)

•: $exec (string or undef)

Adds the application with $name and $exec to the list of applications that have registered a bookmark for $uri into $bookmark_file.

Every bookmark inside a "Glib::BookmarkFile" 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.

If $name is undef, the name of the application will be the same returned by Glib::get_application_name(); if $exec is undef, the command line will be a composition of the program name as returned by Glib::get_prgname() and the "%u" modifier, which will be expanded to the bookmark's URI.

This function will automatically take care of updating the registrations count and timestamping in case an application with the same $name had already registered a bookmark for $uri inside the bookmark file. If no bookmark for $uri is found one is created.

$bookmark_file->add_group ($uri, $group)¶

•: $uri (string)

•: $group (string)

Adds $group to the list of groups to which the bookmark for $uri belongs to. If no bookmark for $uri is found one is created.

unix timestamp = $bookmark_file->get_added ($uri)¶

•: $uri (string)

$bookmark_file->set_added ($uri, $value)¶

•: $uri (string)

•: $value (unix timestamp)

Sets the time the bookmark for $uri was added. If no bookmark for $uri is found one is created.

($exec, $count, $stamp) = $bookmark_file->get_app_info ($uri, $name)¶

•: $uri (string)

•: $name (string)

Gets the registration information of $name for the bookmark for $uri. See Glib::BookmarkFile::set_app_info() for more information about the returned data.

May croak with a Glib::Error in $@ on failure.

$bookmark_file->set_app_info ($uri, $name, $exec, $count, $stamp)¶

•: $uri (string)

•: $name (string)

•: $exec (string)

•: $count (integer)

•: $stamp (unix timestamp)

Sets the meta-data of application $name inside the list of applications that have registered a bookmark for $uri inside $bookmark_file.

You should rarely use this method; use Glib::BookmarkFile::add_application() and Glib::BookmarkFile::remove_application() instead.

$name can be any UTF-8 encoded string used to identify an application. $exec 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 Glib::BookmarkFile::get_app_info() method. $count 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 $name will be removed from the list of registered applications. $stamp is the Unix time of the last registration, as returned by time(); if it is -1, the current time will be used.

If you try to remove an application by setting its registration count to zero, and no bookmark for $uri is found, %FALSE is returned and an exception is fired.

May croak with a Glib::Error in $@ on failure.

list = $bookmark_file->get_applications ($uri)¶

•: $uri (string)

Retrieves the names of the applications that have registered the bookmark for $uri.

May croak with a Glib::Error in $@ on failure.

$bookmark_file->get_description ($uri)¶

•: $uri (string)

Gets the description of the bookmark for $uri.

May croak with a Glib::Error in $@ on failure.

$bookmark_file->set_description ($uri, $description)¶

•: $uri (string)

•: $description (string)

Sets the description of the bookmark for $uri. If no bookmark for $uri is found one is created.

list = $bookmark_file->get_groups ($uri)¶

•: $uri (string)

Retrieves the list of group names of the bookmark for $uri.

May croak with a Glib::Error in $@ on failure.

$bookmark_file->set_groups ($uri, ...)¶

•: $uri (string)

•: ... (list) one or more group names

Sets a list of group names for the item with URI $uri. Each previously set group name list is removed. If no bookmark for $uri is found one is created.

boolean = $bookmark_file->has_application ($uri, $name)¶

•: $uri (string)

•: $name (string)

Checks whether the bookmark for $uri inside $bookmark_file has been registered by application $name.

May croak with a Glib::Error in $@ on failure.

boolean = $bookmark_file->has_group ($uri, $group)¶

•: $uri (string)

•: $group (string)

Checks whether $group appears in the list of groups to which the bookmark for $uri belongs to.

May croak with a Glib::Error in $@ on failure.

boolean = $bookmark_file->has_item ($uri)¶

•: $uri (string)

Looks whether the bookmark file has a bookmark for $uri.

($href, $mime_type) = $bookmark_file->get_icon ($uri)¶

•: $uri (string)

Gets the icon of the bookmark for $uri.

May croak with a Glib::Error in $@ on failure.

$bookmark_file->set_icon ($uri, $href, $mime_type)¶

•: $uri (string)

•: $href (string or undef)

•: $mime_type (string or undef)

Sets the icon for the bookmark for $uri. If $href is undef, unsets the currently set icon.

boolean = $bookmark_file->get_is_private ($uri)¶

•: $uri (string)

May croak with a Glib::Error in $@ on failure.

$bookmark_file->set_is_private ($uri, $is_private)¶

•: $uri (string)

•: $is_private (boolean)

$bookmark_file->load_from_data ($buf)¶

•: $buf (scalar)

Parses a string containing a bookmark file structure.

May croak with a Glib::Error in $@ on failure.

($full_path) = $bookmark_file->load_from_data_dirs ($file)¶

•: $file (localized file name)

Parses a bookmark file, searching for it inside the data directories. If a file is found, it returns the full path.

May croak with a Glib::Error in $@ on failure.

$bookmark_file->load_from_file ($file)¶

•: $file (localized file name)

Parses a bookmark file.

May croak with a Glib::Error in $@ on failure.

string = $bookmark_file->get_mime_type ($uri)¶

•: $uri (string)

Gets the MIME type of the bookmark for $uri.

May croak with a Glib::Error in $@ on failure.

$bookmark_file->set_mime_type ($uri, $mime_type)¶

•: $uri (string)

•: $mime_type (string)

Sets the MIME type of the bookmark for $uri. If no bookmark for $uri is found one is created.

unix timestamp = $bookmark_file->get_modified ($uri)¶

•: $uri (string)

$bookmark_file->set_modified ($uri, $value)¶

•: $uri (string)

•: $value (unix timestamp)

Sets the time the bookmark for $uri was last modified. If no bookmark for $uri is found one is created.

$bookmark_file->move_item ($old_uri, $new_uri)¶

•: $old_uri (string)

•: $new_uri (string or undef)

Changes the URI of a bookmark item from $old_uri to $new_uri. Any existing bookmark for $new_uri will be overwritten. If $new_uri is undef, then the bookmark is removed.

May croak with a Glib::Error in $@ on failure.

$bookmark_file->remove_application ($uri, $name)¶

•: $uri (string)

•: $name (string)

Removes application registered with $name from the list of applications that have registered a bookmark for $uri inside $bookmark_file.

May croak with a Glib::Error in $@ on failure.

$bookmark_file->remove_group ($uri, $group)¶

•: $uri (string)

•: $group (string)

Removes $group from the list of groups to which the bookmark for $uri belongs to.

May croak with a Glib::Error in $@ on failure.

$bookmark_file->remove_item ($uri)¶

•: $uri (string)

Removes the bookmark for $uri from the bookmark file.

May croak with a Glib::Error in $@ on failure.

integer = $bookmark_file->get_size¶

Gets the number of bookmarks inside the bookmark file.

$bookmark_file->get_title ($uri, $title)¶

•: $uri (string)

Gets the title of the bookmark for $uri.

May croak with a Glib::Error in $@ on failure.

$bookmark_file->set_title ($uri, $title)¶

•: $uri (string)

•: $title (string)

Sets the title of the bookmark for $uri. If no bookmark for $uri is found one is created.

string = $bookmark_file->to_data¶

Returns the bookmark file as a string.

May croak with a Glib::Error in $@ on failure.

$bookmark_file->to_file ($file)¶

•: $file (localized file name)

Saves the contents of a bookmark file into a file. The write operation is guaranteed to be atomical by writing the contents of the bookmark file to a temporary file and then moving the file to the target file.

May croak with a Glib::Error in $@ on failure.

list = $bookmark_file->get_uris¶

Returns the URI of all the bookmarks in the bookmark file.

unix timestamp = $bookmark_file->get_visited ($uri)¶

•: $uri (string)

$bookmark_file->set_visited ($uri, $value)¶

•: $uri (string)

•: $value (unix timestamp)

Sets the time the bookmark for $uri was last visited. If no bookmark for $uri is found one is created.

COPYRIGHT¶

This software is licensed under the LGPL. See Glib for a full notice.

2012-05-24

perl v5.14.2

Source file:	Glib::BookmarkFile.3pm.en.gz (from libglib-perl 3:1.260-1)
Source last updated:	2012-05-24T07:06:49Z
Converted to HTML:	2017-06-07T16:48:58Z

NAME¶

SYNOPSIS¶

DESCRIPTION¶

METHODS¶

bookmarkfile = Glib::BookmarkFile->new¶

$bookmark_file->add_application ($uri, $name, $exec)¶

$bookmark_file->add_group ($uri, $group)¶

unix timestamp = $bookmark_file->get_added ($uri)¶

$bookmark_file->set_added ($uri, $value)¶

($exec, $count, $stamp) = $bookmark_file->get_app_info ($uri, $name)¶

$bookmark_file->set_app_info ($uri, $name, $exec, $count, $stamp)¶

list = $bookmark_file->get_applications ($uri)¶

$bookmark_file->get_description ($uri)¶

$bookmark_file->set_description ($uri, $description)¶

list = $bookmark_file->get_groups ($uri)¶

$bookmark_file->set_groups ($uri, ...)¶

boolean = $bookmark_file->has_application ($uri, $name)¶

boolean = $bookmark_file->has_group ($uri, $group)¶

boolean = $bookmark_file->has_item ($uri)¶

($href, $mime_type) = $bookmark_file->get_icon ($uri)¶

$bookmark_file->set_icon ($uri, $href, $mime_type)¶

boolean = $bookmark_file->get_is_private ($uri)¶

$bookmark_file->set_is_private ($uri, $is_private)¶

$bookmark_file->load_from_data ($buf)¶

($full_path) = $bookmark_file->load_from_data_dirs ($file)¶

$bookmark_file->load_from_file ($file)¶

string = $bookmark_file->get_mime_type ($uri)¶

$bookmark_file->set_mime_type ($uri, $mime_type)¶

unix timestamp = $bookmark_file->get_modified ($uri)¶

$bookmark_file->set_modified ($uri, $value)¶

$bookmark_file->move_item ($old_uri, $new_uri)¶

$bookmark_file->remove_application ($uri, $name)¶

$bookmark_file->remove_group ($uri, $group)¶

$bookmark_file->remove_item ($uri)¶

integer = $bookmark_file->get_size¶

$bookmark_file->get_title ($uri, $title)¶

$bookmark_file->set_title ($uri, $title)¶

string = $bookmark_file->to_data¶

$bookmark_file->to_file ($file)¶

list = $bookmark_file->get_uris¶

unix timestamp = $bookmark_file->get_visited ($uri)¶

$bookmark_file->set_visited ($uri, $value)¶

SEE ALSO¶

COPYRIGHT¶