NAME

Perl::Metrics::Plugin - Base class for Perl::Metrics Plugins

SYNOPSIS

  # Implement a simple metrics package which counts up the
  # use of each type of magic variable.
  package Perl::Metrics::Plugin::Magic;
  
  use base 'Perl::Metrics::Plugin';
  
  # Creates the metric 'all_magic'.
  # The total number of magic variables. 
  sub metric_all_magic {
      my ($self, $Document) = @_;
      return scalar grep { $_->isa('PPI::Token::Magic') }
                    $Document->tokens;
  }
  
  # The number of $_ "scalar_it" magic vars
  sub metric_scalar_it {
      my ($self, $Document) = @_;
      return scalar grep { $_->content eq '$_' }
                    grep { $_->isa('PPI::Token::Magic') }
                    $Document->tokens;
  }
  
  # ... and so on, and so forth.
  
  1;

DESCRIPTION

The Perl::Metrics system does not in and of itself generate any actual metrics data, it merely acts as a processing and storage engine.

The generation of the actual metrics data is done via metrics packages, which as implemented as Perl::Metrics::Plugin sub-classes.

Implementing Your Own Metrics Package

Implementing a metrics package is pretty easy.

First, create a Perl::Metrics::Plugin::Something package, inheriting from Perl::Metrics::Plugin.

The create a subroutine for each metric, named metric_$name.

For each subroutine, you will be passed the plugin object itself, and the PPI::Document object to generate the metric for.

Return the metric value from the subroutine. And add as many metric_ methods as you wish. Methods not matching the pattern /^metric_(.+)$/ will be ignored, and you may use them for whatever support methods you wish.

METHODS

new

The new constructor is quite trivial at this point, and is provided merely as a convenience. You don't really need to think about this.

class

A convenience method to get the class for the plugin object, to avoid having to use ref directly (and making the intent of any code a little clearer).

metrics

The metrics method provides the list of metrics that are provided by the metrics package. By default, this list is automatically generated for you scanning for metric_$name methods that reside in the immediate package namespace.

Returns a reference to a HASH where the keys are the metric names, and the values are the "version" of the metric (for versioned metrics), or undef if the metric is not versioned.

process_index

The process_index method will cause the metrics plugin to scan every single file entry in the database, and run any an all metrics required to bring to the database up to complete coverage for that plugin.

This process may take some time for large indexes.

process_file $File

The process_file method takes as argument a single Perl::Metrics::File and run any and all metrics required to bring that file up to complete coverage for the plugin.

SUPPORT

Bugs should be reported via the CPAN bug tracker at

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Perl-Metrics

For other issues, contact the author.

AUTHOR

Adam Kennedy <adamk@cpan.org>

SEE ALSO

Perl::Metrics, PPI

COPYRIGHT

Copyright 2005 - 2008 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

cpanm Perl::Metrics

perl -MCPAN -e shell
install Perl::Metrics