NAME

WWW::Link::Reporter - report information about a link back to a user

SYNOPSIS

    package WWW::Link::Reporter::somethingorother
    use WWW::Link::Reporter;
    sub broken {print "something..."; ... }
    sub not_found {print "or...; ... }
    sub redirected {print "other...; ... }
    sub okay ...
    sub not_perfect ....

DESCRIPTION

This class is really a base class upon which other classes can be built. These classes will allow feedback to users about what the status of various links is.

The class provides one facility in that it will gather some statistics on the links that are fed to it.

SUBCLASSES

Here is a list of the subclasses which come in the default distribution. Each one should have a more detailed description (but probably doesn't ;-)

Text

A simple text output listing which links are broken.

HTML

An HTML page with a list of the broken links.

RepairForm

Generates an HTML page which will drive fix-link.cgi (provided with this package) to fix links.

LongList

Runs ls -l on files which contain broken links giving a format which emacs can interpret for editing (see special emacs mode link-report-dired provided).

Compile

For use whilst checking links in a file online. Generates an emacs compile mode style listing which can be used to go directly to the line needing corrected in the editor.

Other subclasses can be created by overriding the built in methods (see below).

The default class supports storing an index object which could be used for getting information about the link. However it doesn't do anything with it.

METHODS

new WWW::Link::Reporter [$index]

New sets up a new reporter. If it is given a suitable index, then it will store this for later use during reporting.

$reporter->set_index ( $index )

We can set the index that we are using.

$reporter->examine ( $link )

The examine class calls appropriate methods of the reporter to give to give information about the link, depending on its status. By overriding the methods in the default class (see below) you can make any kind of report you wish. Individual method calls can be turned on or off using boolean variables in the object (again see below).

Normally there's no need to override this.

init

In this class init just re-initialises the statistics the class gathers. It is called automatically by the constructor. Generally it will be over-ridden by a sub class if needed.

dummy methods

  $s->okay $s->not_perfect $s->redirected $s->broken
  $s->unsupported $s->disallowed

These methods are designed to be overriden in derived classes. The appropriate function is called by $s->examine depending on the state of the link. These dummy simply increment a count of each kind of link. The one exception is unknown which also issues a warning.

broken

Is called when a link was found broken enough times that we consider it permenantly broken. Controlled $self->{"report_broken"}.

okay

Is called when there link has been checked and found to be okay. This is controlled by $self->{"report_okay"}. N.B. this will exclude links which have never been checked. Use not_checked for those.

damaged

Is called when a link was found broken, but not enough times for us to consider it permanently broken. Controlled by $self->{"report_not_perfect"}.

This link is exactly the kind of thing which the linkcontroller system was designed to avoid (links which have not been broken for long and will probably soon be repaired), so probably you don't want to use not_perfect unless for some reason you are reporting links which are okay or the user explicitly asks you to.

redirected

Is called when a redirect was returned by the server serving the resource. Controlled $self->{"report_redirected"}.

unsupported

Is called when for some reason a link couldn't be checked at all. This would typically be some unsupported scheme. Controlled $self->{"report_unsupported"}.

disallowed

Is called when checking of the link is disallowed. The status of the link its self cannot be known. $self->{"report_unsupported"}.

not_checked

Is called when for some reason a link hasn't yet been checked.

unknown

Is called when the status of a link is not understood by this module. This should normally be considered an error condition and this module produces a warning.

not_found

This method should be called from outside the module when a link which should be in the links database isn't there.

all_reports

This sets the flag about what we will report for every single kind of report and can be used to make a very noisy or a very quiet reporter.

default_reports

This sets a sensible set of default reporting as follows.

  $self->{"report_broken"} = 1;
  $self->{"report_okay"} = 0;
  $self->{"report_damaged"} = 0;
  $self->{"report_redirected"} = 1;
  $self->{"report_not_checked"} = 0;
  $self->{"report_disallowed"} = 1;
  $self->{"report_unsupported"} = 0;
  $self->{"report_unknown"} = 1;

You can override it no problem.

report_not_perfect()

this is a convenience function which turns on reports for all link apart from those which are okay.

report_good()

This sets reporting which should show all links which are probably not broken. Currently that defininition includes all redirected links and those that are unsupported etc. Excludes are broken links and ones where checking is disallowed.

Since this function is designed for automatic link page maintainainance, however, as any other ways of detecting broken links are discovered, those links will be excluded.

INDIVIDUAL REPORTS

The following functions allow individual reporting functions to be turned on or off if called with a value (1 turns the report on, 0 turns it off).

If called with no value they simply return the current status of that report.

• report_broken

• report_okay

• report_damaged

• report_redirected

• report_not_checked

• report_disallowed

• report_unsupported

cpanm WWW::Link

perl -MCPAN -e shell
install WWW::Link