NAME

Netscape::Bookmarks::Category - manipulate, or create Netscape Bookmarks files

SYNOPSIS

  use Netscape::Bookmarks;

  #parse an existing file
  my $bookmarks = new Netscape::Bookmarks $bookmarks_file;

  #print a Netscape compatible file
  print $bookmarks->as_string;

DESCRIPTION

The Netscape bookmarks file has several basic components:

        title
        folders (henceforth called categories)
        links
        aliases
        separators

On disk, Netscape browsers store this information in HTML. In the browser, it is displayed under the "Bookmarks" menu. The data can be manipulated through the browser interface.

This module allows one to manipulate the bookmarks file programmatically. One can parse an existing bookmarks file, manipulate the information, and write it as a bookmarks file again. Furthermore, one can skip the parsing step to create a new bookmarks file and write it in the proper format to be used by a Netscape browser.

The Bookmarks.pm module simply parses the bookmarks file passed to it as the only argument to the constructor:

        my $bookmarks = new Netscape::Bookmarks $bookmarks_file;

The returned object is a Netscape::Bookmarks::Category object, since the bookmark file is simply a collection of categories that contain any of the components listed above. The top level (i.e. root) category is treated specially and defines the title of the bookmarks file.

METHODS

Netscape::Bookmarks::Category->new( \%hash )

The new method creates a Category. It takes a hash reference that specifies the properties of the category. The valid keys in that hash are

        folded                  collapsed state of the category ( 1 or 0 )
        title
        add_date
        description

$category->add( $object )

The add() function adds an element to a category. The element must be a Alias, Link, Category, or Separator object. Returns TRUE or FALSE.

$category->remove_element( $object )

Removes the given object from the Category by calling the object's remove() method.

Returns the number of objects removed from the Category.

$category->remove()

Performs any clean up necessary to remove this object from the Bookmarks tree. Although this method does not recursively remove objects which it contains, it probably should.

$category->title( [ TITLE ] )

Returns title to the category. With a defined argument TITLE, it replaces the current title.

$category->id()

Returns the ID of the category. This is an arbitrary, unique number.

$category->description( [ DESCRIPTION ] )

Returns the description of the category. With a defined argument DESCRIPTION, it replaces the current description.

$category->folded( $object )

Returns the folded state of the category (TRUE or FALSE). If the category is "folded", Netscape shows a collapsed folder for this category.

$category->add_date()

Returns the ADD_DATE attribute of the category.

$category->last_modified()

Returns the LAST_MODIFIED attribute of the category.

$category->personal_toolbar_folder()

Returns the PERSONAL_TOOLBAR_FOLDER attribute of the category.

$category->elements()

In scalar context returns an array reference to the elements in the category. In list context returns a list of the elements in the category.

$category->count()

Returns a count of the number of objects in the Category.

$category->categories()

Returns a list of the Category objects in the category.

$category->links()

Returns a list of the Link objects in the category.

$category->as_headline()

Returns an HTML string representation of the category, but not the elements of the category.

$category->recurse( CODE, [ LEVEL ] )

This method performs a depth-first traversal of the Bookmarks tree and executes the CODE reference at each node.

The CODE reference receives two arguments - the object on which it should operate and its level in the tree.

$category->introduce( VISITOR, [ LEVEL ] )

This method performs a depth-first traversal of the Bookmarks tree and introduces the visitor object to each object.

This is different from recurse() which only calls its CODEREF on nodes. The VISITOR operates on nodes and vertices. The VISITOR must have a visit() method recognizable by can(). This method does not trap errors in the VISITOR.

See Netscape::Bookmarks::AcceptVisitor for details on Visitors.

$category->sort_elements( [ CODE ] )

Sorts the elements in the category using the provided CODE reference. If you do not specify a CODE reference, the elements are sorted by title (with the side effect of removing Separators from the Category).

This function does not recurse, although you can use the recurse() method to do that.

Since the built-in sort() uses the package variables $a and $b, your sort subroutine has to make sure that it is accessing the right $a and $b, which are the ones in the package Netscape::Bookmarks::Category. You can start your CODE reference with a package declaration to ensure the right thing happens:

        my $sub = sub {
                package Netscape::Bookmarks::Category;

                $b->title cmp $a->title;
                };

        $category->sort_elements( $sub );

If you know a better way to do this, please let me know. :)

$category->as_string()

Returns an HTML string representation of the category as the top level category, along with all of the elements of the category and the Categories that it contains, recursively.

$obj->write_file( FILENAME )

UNIMPLEMENTED!

AUTHOR

brian d foy <bdfoy@cpan.org>

COPYRIGHT AND LICENSE

Copyright © 2002-2018, brian d foy <bdfoy@cpan.org>. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

SEE ALSO

Netscape::Bookmarks