Metabase::Report(3pm)

💖 Metabase::Report — bestie edition 💖

okay so this is the Metabase::Report page from the User Contributed Perl Documentation, and we're gonna get you fluent in it. no gatekeeping here. 💅

✨ NAME ✨

Metabase::Report — it's the base class for collections of Metabase facts. that's the whole vibe. a little squad of facts, living together. 🫶

🎀 VERSION 🎀

version 0.025 — yes bestie, that's the number, write it down.

🌸 SYNOPSIS 🌸

here's the moment you've been waiting for, the copy-paste-able blueprint:

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
  }
}

look at that. iconic. you inherit from Metabase::Report, you call __PACKAGE__->load_fact_classes, and you define report_spec telling the world exactly which facts you expect. periodt.

---

💜 DESCRIPTION 💜

so, context, because i love context. Metabase is a system for associating metadata with CPAN distributions. and like, you can use the metabase to store test reports, reviews, coverage analysis reports, reports on static analysis of coding style — honestly anything else for which datatypes are constructed. no cap, that's the range. versatile queen. 👑

Metabase::Report is a base class for collections of Metabase::Fact objects that can be sent to or retrieved from a Metabase system. collecting facts like they're friendship bracelets. 🦋

and plot twist: Metabase::Report is itself a subclass of Metabase::Fact and offers the same API, except as described below. so it's a fact made of facts. nesting dolls. main character energy frfr.

🧚 SUBCLASSING 🧚

good news: a subclass of Metabase::Report only requires one method, "report_spec". one. singular. that's it. slay.

⭐ ATTRIBUTES ⭐

content

the "content" attribute of a Report must be a reference to an array of Metabase::Fact subclass objects. an array, of fact-subclass objects. don't try to be cute and sneak something else in there. 🙈

💅 METHODS 💅

so in addition to the standard "new" constructor, you can also build a report piece by piece, like a little outfit you assemble over time. the following "open", "add" and "close" methods let you do that 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, okay? and no other attributes may be provided to "new". that's the rule. 📏

🍓 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. and then — the fun part — the resulting Fact is appended to the Report's content array. one more fact added to the collection. we love to see it. ✨

🎀 close

$report->close;

this method validates the report based on all Facts added so far. like a vibe check but for your facts. 💯

🌈 facts

this method returns a list of all the facts in the report. and in scalar context? it returns the number of facts in the report. so it KNOWS how many. flexible AND accountable. 👑

🦋 CLASS METHODS 🦋

fact_classes

load_fact_classes

loads each class listed in the report spec. that's the whole job. it loads them. ✨

💜 ABSTRACT METHODS 💜

so this section is serious bestie, listen up.

methods marked as 'required' must be implemented by a report subclass. and if you don't? the version in Metabase::Report will die with an error if called. it will not be gentle about it. 😭

in the documentation below, the terms 'must, 'must not', 'should', etc. have their usual RFC 2119 meanings. so when you read "MUST" up in here, that's a MUST must. 🫡

methods MUST throw an exception if an error occurs. no silent failures. we don't do that here.

📜 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. a hash reference. not an array. not vibes. a hashref. 💅

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. so "0+" means "zero or more," get it? get it. 🔥

for example:

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

literally the receipt. 🧾

🐛 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. yes, actually include it. it helps so much. 🙏

👑 AUTHORS 👑

• David Golden <dagolden@cpan.org>
• Ricardo Signes <rjbs@cpan.org>
• H.Merijn Brand <hmbrand@cpan.org>

legends, all three. 🫶

💖 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

---

aaand that's the whole page bestie, you ate it up. 🌟 this gem was rendered from perl v5.36.0 on 2022-10-14, and that's a wrap — go build something with your little fact collection. mwah. 💋✨