/ 
Netscape-History-3.00
/ Netscape::History

NAME

Netscape::History - object class for accessing Netscape history database

SYNOPSIS

use Netscape::History;

$history = new Netscape::History();
while (defined($url = $history->next_url() ))
{
}

DESCRIPTION

The Netscape::History module implements an object class for accessing the history database maintained by the Netscape web browser. The history database keeps a list of all URLs you have visited, and is used by Netscape to change the color of URLs which you have previously visited, for example.

With this module, you can get at the URLs stored in a Netscape history file, delete URLs, and add new ones. With the associated Netscape::HistoryURL module you can access the information which is associated with each URL.

Please Note: the database format for the browser history was changed with Netscape 4. Previously only the time of most recent visit was available; now you can also get at the time of your first visit, the number of visits, the title of the referenced page, and another value.

PLEASE NOTE

In version 2.00 of this module, you had to set the $Netscape::History::NETSCAPE_VERSION variable to the major version number of the Netscape you were using, since there was a change in the information stored for each URL between versions 3 and 4. In a subsequent version we removed the need for the variable, thanks to a suggestion from Jimmy Aitken.

Previously, setting the variable would silently do nothing, from this version onwards it will result in an error.

CONSTRUCTOR

$history = new Netscape::History();

This creates a new instance of the Netscape::History object class. You can optionally pass the path to the history database as an argument to the constructor, as in:

$history = new Netscape::History('/home/bob/.netscape/history.db');

If you do not specify the file, then the constructor will use:

$HOME/.netscape/history.db

If the Netscape history database does not exist, a warning message will be generated, and the constructor will return undef.

METHODS

The Netscape::History class implements the following methods:

  • get_url - get a specific URL from your history

  • rewind - reset history database to first URL

  • next_url - get next URL from your history

  • delete_url - remove a URL from your history

  • add_url - add a URL to the history file

  • close - close the history database

Each of the methods is described separately below.

get_url - get a specific URL from your history

$url = $history->get_url( URL );

This method is used to extract information about a specific URL from your history database.

This method takes a URL (which could be just a text string, or an object of class URI::URL) and returns an instance of Netscape::HistoryURL.

next_url - get the next URL from your history database

$url = $history->next_url();

This method returns the next URL from your history database. If you want to process all URLs in the database, you should call the rewind method before looping over all URLs.

The URL returned is an instance of the Netscape::HistoryURL class, which works just like an instance of URI::URL, but provides an extra methods, as described in the documentation for Netscape::HistoryURL.

delete_url - remove a URL from the history database

$history->delete_url($url);

This method is used to remove a URL from your history database. The URL passed can be a simple text string with the URL, or an instance of Netscape::HistoryURL, URI::URL, or any other class which can be rendered into a string.

add_url - add a URL to the history database

$history->add_url( URL );

This method is used to add a URL to a history database. This might be useful if you are merging information from multiple history databases, for example.

If the URL passed is an instance of Netscape::HistoryURL, then the information available will be stored.

If the URL is specified as a text string, is derived from URI::URL, then a Netscape::HistoryURL will be created with the following:

LAST   = current time
FIRST  = current time
COUNT  = 1
EXPIRE = 1
TITLE  = ''

If the EXPIRE field is not set to 1, then it won't appear in Netscape's history window. Not really sure why :-)

rewind - reset internal URL pointer to first URL in history

$history->rewind();

This method is used to move the history database's internal pointer to the first URL in your history database. You don't need to bother with this if you have just created the object, but it doesn't harm anything if you do.

close - close the history database

$history->close();

This closes the history database. The destructor will do this automatically for you, so most of time you don't actually have to bother calling this method explicitly. Good programming style says you should though :-)

EXAMPLES

DISPLAY CONTENTS OF HISTORY

The following example illustrates use of this module, and the visit_time() method of the URLs returned. The program will list all URLs visited, along with visit time. The Date::Format module is used to format the visit time.

#!/usr/bin/perl -w

use Netscape::History;
use Date::Format;
use strict;

my $history;
my $url;

$history = new Netscape::History;
while (defined($url = $history->next_url() ))
{
    print "$url :\n";
    print "    First  : ", ctime($url->first_visit_time());
    print "    Last   : ", ctime($url->last_visit_time());
    print "    Count  : ", $url->visit_count(), "\n";
    print "    Expire : ", $url->expire(), "\n";
    print "    Title  : ", $url->title(), "\n";
}
$history->close();

MERGE TWO HISTORY FILES

The following example illustrates use of the add_url method to merge two history databases. We read all URLs from history2.db, and merge them into history1.db, overwriting any duplicates.

$history1 = new Netscape::History("history1.db");
$history2 = new Netscape::History("history2.db");
while (defined($url = $history2->next_url() ))
{
    $history1->add_url($url);
}
$history1->close();
$history2->close();

SEE ALSO

Netscape::HistoryURL

When you call the next_url method, you are returned instances of this class.

DB_File

The Netscape history file is just a Berkeley DB File, which we access using the DB_File module. You can use a different DB_File compatible library (such as DB_File::SV185) by running

use Netscape::History dblib => 'DB_File::SV185'

in which case you are only depending on the specified library and not DB_File.

URI::URL

The underlying class for Netscape::HistoryURL, which provides the mechanisms for manipulating URLs.

Date::Format

Functions for formatting time and date in strings.

AUTHOR

Neil Bowers <neilb@cre.canon.co.uk>, and Richard Taylor <rit@cre.canon.co.uk>.

COPYRIGHT

Copyright (c) 1997-1999 Canon Research Centre Europe. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.