NAME

       Metabase::Report - a base class for collections of Metabase facts

VERSION

       version 0.025

SYNOPSIS

         package MyReport;

         use Metabase::Report;
         our @ISA = qw/Metabase::Report/;
         __PACKAGE__->load_fact_classes;

         sub report_spec {
           return {
             'Fact::One' => 1,     # one of Fact::One
             'Fact::Two' => "0+",  # zero or more of Fact::Two
           }
         }

DESCRIPTION

       Metabase is a system for associating metadata with CPAN distributions.  The metabase can be used to store
       test reports, reviews, coverage analysis reports, reports on static analysis of coding style, or anything
       else for which datatypes are constructed.

       Metabase::Report is a base class for collections of Metabase::Fact objects that can be sent to or
       retrieved from a Metabase system.

       Metabase::Report is itself a subclass of Metabase::Fact and offers the same API, except as described
       below.

SUBCLASSING

       A subclass of Metabase::Report only requires one method, "report_spec".

ATTRIBUTES

       content

       The "content" attribute of a Report must be a reference to an array of Metabase::Fact subclass objects.

METHODS

       In addition to the standard "new" constructor, the following "open", "add" and "close" methods may be
       used to construct a report piecemeal, instead.

   open
         $report = Report::Subclass->open(
           id => 'AUTHORID/Foo-Bar-1.23.tar.gz',
         );

       Constructs a new, empty report. The 'id' attribute is required.  The 'refers_to' attribute is optional.
       The 'content' attribute may be provided, but see "add" below. No other attributes may be provided to
       "new".

   add
         $report->add( 'Fact::Subclass' => $content );

       Using the 'id' attribute of the report, this method constructs a new Fact from a class and a content
       argument.  The resulting Fact is appended to the Report's content array.

   close
         $report->close;

       This method validates the report based on all Facts added so far.

   facts
       This method returns a list of all the facts in the report.  In scalar context, it returns the number of
       facts in the report.

CLASS METHODS

   fact_classes
   load_fact_classes
       Loads each class listed in the report spec.

ABSTRACT METHODS

       Methods marked as 'required' must be implemented by a report subclass.  (The version in Metabase::Report
       will die with an error if called.)

       In the documentation below, the terms 'must, 'must not', 'should', etc. have their usual RFC 2119
       meanings.

       Methods MUST throw an exception if an error occurs.

   report_spec
       required

         $spec = Report::Subclass->report_spec;

       The "report_spec" method MUST return a hash reference that defines how many Facts of which types must be
       in the report for it to be considered valid.  Keys MUST be class names.  Values MUST be non-negative
       integers that indicate the number of Facts of that type that must be present for a report to be valid,
       optionally followed by a '+' character to indicate that the report may contain more than the given
       number.

       For example:

         {
           Fact::One => 1,     # one of Fact::One
           Fact::Two => "0+",  # zero or more of Fact::Two
         }

BUGS

       Please report any bugs or feature using the CPAN Request Tracker.  Bugs can be submitted through the web
       interface at <http://rt.cpan.org/Dist/Display.html?Queue=Metabase-Fact>

       When submitting a bug or request, please include a test-file or a patch to an existing test-file that
       illustrates the bug or desired feature.

AUTHORS

       •   David Golden <dagolden@cpan.org>

       •   Ricardo Signes <rjbs@cpan.org>

       •   H.Merijn Brand <hmbrand@cpan.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2016 by David Golden.

       This is free software, licensed under:

         The Apache License, Version 2.0, January 2004

perl v5.36.0                                       2022-10-14                              Metabase::Report(3pm)