Firefox-Marionette/lib/Firefox/Marionette/Bookmark.pm
package Firefox::Marionette::Bookmark;
use strict;
use warnings;
use URI::URL();
use URI::data();
use Exporter();
*import = \&Exporter::import;
our @EXPORT_OK = qw(
BOOKMARK
FOLDER
MENU
MOBILE
ROOT
SEPARATOR
TAGS
TOOLBAR
UNFILED
);
our %EXPORT_TAGS = ( 'all' => \@EXPORT_OK, );
our $VERSION = '1.68';
# guids from toolkit/components/places/Bookmarks.sys.mjs
sub MENU { return 'menu________' }
sub MOBILE { return 'mobile______' }
sub ROOT { return 'root________' }
sub TAGS {
return 'tags________';
} # With bug 424160, tags will stop being bookmarks
sub TOOLBAR { return 'toolbar_____' }
sub UNFILED { return 'unfiled_____' }
# types from toolkit/components/places/nsINavBookmarksService.idl
sub BOOKMARK { return 1 }
sub FOLDER { return 2 }
sub SEPARATOR { return 3 }
my %mapping = (
guid => 'guid',
keyword => 'keyword',
url => 'url',
title => 'title',
type => 'type',
tags => 'tags',
index => 'index',
parent_guid => 'parentGuid',
date_added => 'dateAdded',
last_modified => 'lastModified',
icon_url => 'iconUrl',
icon => 'icon',
);
sub new {
my ( $class, %parameters ) = @_;
my $bookmark = bless {}, $class;
foreach my $name (
qw(parent_guid guid url title date_added last_modified type icon icon_url index tags keyword)
)
{
if ( defined $parameters{$name} ) {
$bookmark->{$name} = $parameters{$name};
}
if ( defined $parameters{ $mapping{$name} } ) {
$bookmark->{$name} = $parameters{ $mapping{$name} };
}
}
foreach my $name (qw(url icon_url)) {
if ( defined $bookmark->{$name} ) {
$bookmark->{$name} = URI::URL->new( $bookmark->{$name} );
}
}
foreach my $name (qw(icon)) {
if ( defined $bookmark->{$name} ) {
$bookmark->{$name} = URI::data->new( $bookmark->{$name} );
}
}
if ( !defined $bookmark->{type} ) {
if ( defined $bookmark->{url} ) {
$bookmark->{type} = BOOKMARK();
}
elsif ( defined $bookmark->{title} ) {
$bookmark->{type} = FOLDER();
}
}
if ( ( defined $bookmark->{guid} ) && ( $bookmark->{guid} eq ROOT() ) ) {
}
else {
$bookmark->{parent_guid} =
$bookmark->{parent_guid} ? $bookmark->{parent_guid} : MENU();
}
return $bookmark;
}
sub TO_JSON {
my ($self) = @_;
my $json = {};
foreach my $key ( sort { $a cmp $b } keys %{$self} ) {
if ( ( $key eq 'url' ) || ( $key eq 'icon_url' ) || ( $key eq 'icon' ) )
{
$json->{ $mapping{$key} } = $self->{$key}->as_string();
}
else {
$json->{ $mapping{$key} } = $self->{$key};
}
if ( ( $key eq 'date_added' ) || ( $key eq 'last_modified' ) ) {
$json->{ $mapping{$key} } =~ s/000$//smx;
}
}
return $json;
}
sub url {
my ($self) = @_;
return $self->{url};
}
sub title {
my ($self) = @_;
return $self->{title};
}
sub guid {
my ($self) = @_;
return $self->{guid};
}
sub type {
my ($self) = @_;
return $self->{type};
}
sub content_type {
my ($self) = @_;
if ( my $type = $self->type() ) {
if ( $type == BOOKMARK() ) {
return 'text/x-moz-place';
}
elsif ( $type == FOLDER() ) {
return 'text/x-moz-place-container';
}
elsif ( $type == SEPARATOR() ) {
return 'text/x-moz-place-separator';
}
}
return;
}
sub parent_guid {
my ($self) = @_;
return $self->{parent_guid};
}
sub date_added {
my ($self) = @_;
return $self->{date_added};
}
sub last_modified {
my ($self) = @_;
return $self->{last_modified};
}
sub idx {
my ($self) = @_;
return $self->{index};
}
sub icon {
my ($self) = @_;
return $self->{icon};
}
sub icon_url {
my ($self) = @_;
return $self->{icon_url};
}
sub tags {
my ($self) = @_;
if ( defined $self->{tags} ) {
return @{ $self->{tags} };
}
else {
return ();
}
}
sub keyword {
my ($self) = @_;
return $self->{keyword};
}
1; # Magic true value required at end of module
__END__
=head1 NAME
Firefox::Marionette::Bookmark - Represents a Firefox bookmark retrieved using the Marionette protocol
=head1 VERSION
Version 1.68
=head1 SYNOPSIS
use Firefox::Marionette();
use Firefox::Marionette::Bookmark qw(:all);
use Encode();
use v5.10;
my $firefox = Firefox::Marionette->new();
$firefox->import_bookmarks("/path/to/bookmarks.html");
foreach my $bookmark (reverse $firefox->bookmarks()) {
say "Bookmark guid is :" . $bookmark->guid();
say "Bookmark parent guid is :" . $bookmark->parent_guid();
say "Bookmark date added is :" . localtime($bookmark->date_added());
say "Bookmark last modified is :" . localtime($bookmark->last_modified());
say "Bookmark index is :" . $bookmark->idx();
if ($bookmark->type() == BOOKMARK()) {
say "Bookmark url :" . $bookmark->url();
say "Bookmark title is :" . Encode::encode('UTF-8', $bookmark->title(), 1) if ($bookmark->title());
say "Bookmark icon is :" . $bookmark->icon() if ($bookmark->icon());
say "Bookmark icon url is :" . $bookmark->icon_url() if ($bookmark->icon_url());
say "Bookmark keyword is :" . Encode::encode('UTF-8', $bookmark->keyword(), 1) if ($bookmark->keyword());
say "Bookmark tags are :" . Encode::encode('UTF-8', (join q[, ], $bookmark->tags())) if ($bookmark->tags());
} elsif ($bookmark->type() == FOLDER()) {
given ($bookmark->guid()) {
when (MENU() . q[]) { say "This is the menu folder" }
when (ROOT() . q[]) { say "This is the root folder" }
when (TAGS() . q[]) { say "This is the tags folder" }
when (TOOLBAR() . q[]) { say "This is the toolbar folder" }
when (UNFILED() . q[]) { say "This is the unfiled folder" }
when (MOBILE() . q[]) { say "This is the mobile folder" }
default { say "Folder title is :" . $bookmark->title() }
}
} else {
say "-" x 50;
}
}
=head1 DESCRIPTION
This module handles the implementation of a single Firefox bookmark using the Marionette protocol.
=head1 CONSTANTS
Constants are sourced from L<toolkit/components/places/Bookmarks.sys.mjs|https://hg.mozilla.org/mozilla-central/file/tip/toolkit/components/places/Bookmarks.sys.mjs>.
=head2 ROOT
returns the guid of the root of the bookmark hierarchy. This is equal to the string 'root________'.
=head2 MENU
return the guid for the menu folder. This is equal to the string 'menu________'.
=head2 TAGS
return the guid for the tags folder. This is equal to the string 'tags________'. With L<bug 424160|https://bugzilla.mozilla.org/show_bug.cgi?id=424160>, tags will stop being bookmarks.
=head2 TOOLBAR
return the guid for the toolbar folder. This is equal to the string 'toolbar_____'.
=head2 UNFILED
return the guid for the unfiled folder. This is equal to the string 'unfiled_____'.
=head2 MOBILE
return the guid for the mobile folder. This is equal to the string 'mobile______'.
=head2 BOOKMARK
returns the integer 1.
=head2 FOLDER
returns the integer 2.
=head2 SEPARATOR
returns the integer 3.
=head1 SUBROUTINES/METHODS
=head2 new
accepts a hash as a parameter. Allowed keys are below;
=over 4
=item * date_added. the time the bookmark was added in seconds since the UNIX epoch.
=item * icon - the favicon for the bookmark. It should be encoded as a L<data URI|URI::data>.
=item * icon_url - the url for the bookmark favicon. It should be encoded as a L<URL|URI::URL>.
=item * index - the index of the bookmark. This describes the bookmark's position in the hierarchy.
=item * guid - the unique identifier for the bookmark in Firefox. This key is optional. If the a bookmark is saved without a guid, firefox will generate a guid automatically.
=item * last_modified - the time the bookmark was last modified in seconds since the UNIX epoch.
=item * parent_guid - the guid of the parent folder in the bookmark hierarchy. The default parent guid will be the L<MENU|/MENU>.
=item * title - the title of the bookmark. This can be a L<folder name|/FOLDER> name or a L<bookmark|/BOOKMARK> title.
=item * type - an integer describing the type of this object. It can be a L<bookmark|/BOOKMARK>, a L<folder|/FOLDER> or a L<separator|/SEPARATOR>.
=item * url - the L<url|/url> of the bookmark. Only bookmarks with a type of L<BOOKMARK|/BOOKMARK> will have a L<url|/url> set.
=back
This method returns a new L<bookmark|Firefox::Marionette::Bookmark> object.
=head2 content_type
returns the content type of the bookmark (for example 'text/x-moz-place-container' for a folder).
=head2 date_added
returns the time the bookmark was added in seconds since the UNIX epoch.
=head2 icon
returns the favicon of the bookmark if known. It will be returned as a L<data URI|URI::data> object.
=head2 icon_url
returns the URL of the favicon of the bookmark if known. It will be returned as a L<URL|URI::URL> object.
=head2 idx
returns the index of the bookmark. This will be an integer.
=head2 guid
returns the guid of the bookmark. This will be a unique value for the hierarchy and 12 characters in length. There are special guids, which are the L<ROOT|/ROOT>, L<MENU|/MENU>, L<TOOLBAR|/TOOLBAR>, L<UNFILED|/UNFILED> and L<MOBILE|/MOBILE> guids.
=head2 keyword
returns the L<keyword|https://support.mozilla.org/en-US/kb/bookmarks-firefox#w_how-to-use-keywords-with-bookmarks> (if any) associated with the bookmark.
=head2 last_modified
returns the time the bookmark was last modified in seconds since the UNIX epoch.
=head2 parent_guid
returns the guid of the bookmark's parent.
=head2 tags
returns the L<tags|https://support.mozilla.org/en-US/kb/categorizing-bookmarks-make-them-easy-to-find> associated with the bookmark as a list.
=head2 title
returns the title of the bookmark. This can be for a folder or a bookmark.
=head2 TO_JSON
required to allow L<JSON serialisation|https://metacpan.org/pod/JSON#OBJECT-SERIALISATION> to work correctly. This method should not need to be called directly.
=head2 type
returns an integer describing the type of the bookmark. This can be L<BOOKMARK|/BOOKMARK>, L<FOLDER|/FOLDER> or L<SEPARATOR|/SEPARATOR>.
=head2 url
returns the URL of the bookmark. It will be returned as a L<URL|URI::URL> object.
=head1 DIAGNOSTICS
None.
=head1 CONFIGURATION AND ENVIRONMENT
Firefox::Marionette::Bookmark requires no configuration files or environment variables.
=head1 DEPENDENCIES
Firefox::Marionette::Bookmark requires the following non-core Perl modules
=over
=item *
L<URI::data|URI::data>
=item *
L<URI::URL|URI::URL>
=back
=head1 INCOMPATIBILITIES
None reported.
=head1 BUGS AND LIMITATIONS
To report a bug, or view the current list of bugs, please visit L<https://github.com/david-dick/firefox-marionette/issues>
=head1 AUTHOR
David Dick C<< <ddick@cpan.org> >>
=head1 LICENSE AND COPYRIGHT
Copyright (c) 2024, David Dick C<< <ddick@cpan.org> >>. All rights reserved.
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See L<perlartistic/perlartistic>.
=head1 DISCLAIMER OF WARRANTY
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.