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