Metabase::Fact(3pm)

📦
version 0.025 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Metabase::Fact — the base class for Metabase Facts. It's a Perl module, from the User Contributed Perl Documentation, and it's about to become your whole personality. 🫶

✨ VERSION ✨

version 0.025

🌸 SYNOPSIS 🌸

Defining the fact class:

# defining the fact class
package MyFact;
use Metabase::Fact::Hash;
our @ISA = qw/Metabase::Fact::Hash/;

# using the fact class
my $fact = TestReport->new(
  resource   => 'RJBS/Metabase-Fact-0.001.tar.gz',
  content    => {
    status => 'FAIL',
    time   => 3029,
  },
);

$client->send_fact($fact);

🦋 DESCRIPTION 🦋

okay so bestie, listen. Metabase is a whole framework for associating content and metadata with arbitrary resources. Like, arbitrary arbitrary. You can use a Metabase to store test reports, reviews, coverage analysis reports, reports on static analysis of coding style — or literally anything else where you've built datatypes for it. The range is giving versatility. 👑

Metabase::Fact is the base class for Facts — and when they say "facts" they mean opinions or analyses, no cap — that can be sent to or retrieved from a Metabase repository.

🎀 Structure of a Fact object 🎀

A Fact object associates a content attribute with a resource attribute and a creator attribute.

  • The resource attribute must be in a URI format that can be validated via a Metabase::Resource subclass.
  • The content attribute is an opaque scalar with subclass-specific meaning.
  • The creator attribute is a URI with a metabase:user scheme and type (see Metabase::Resource::metabase).

Facts have three sets of metadata associated with them. Metadata are generally for use in indexing, searching and managing Facts. Think of them as the Facts' little entourage. 💅

  • "core metadata" describe universal properties of all Facts, and they're used to submit, store, manage and retrieve Facts within the Metabase framework.
  • "resource metadata" describe index properties derived from the resource attribute. (Since these can be regenerated from the resource — which is itself part of core metadata — they are not stored with a serialized Fact.)
  • "content metadata" describe index properties derived from the content attribute. (Since these can be regenerated from the content — which is part of core metadata — they are not stored with a serialized Fact.)

Each of the three metadata sets has an associated accessor: core_metadata, resource_metadata and content_metadata.

Each of the three sets also has an accessor that returns a hashref with a data type for each possible element in the set: core_metadata_types, resource_metadata_types and content_metadata_types.

Data types are loosely based on Data::RX. For example:

'//str'  -- indicates a value that should be compared stringwise
'//num'  -- indicates a value that should be compared numerically
'//bool' -- indicates a value that is true or false

When searching on metadata, you must join the set name to the metadata element name with a period character. For example:

core.guid
core.creator
core.resource
resource.scheme
content.size
content.score

💜 ATTRIBUTES 💜

Unless otherwise noted, all attributes are read-only, and they're either provided as arguments to the constructor or generated during construction. All attributes (except content) are also part of core metadata.

🌈 Arguments provided to new 🌈

content — required 💖

A reference to the actual information associated with the fact. The exact form of the content is up to each Fact class to determine. Your class, your rules.

resource — required 💖

The canonical resource (URI) the Fact relates to. For CPAN distributions, this would be a cpan:///distfile/... URI. (See URI::cpan.) The associated accessor returns a Metabase::Resource subclass.

creator — optional 🌸

A Metabase::User::Profile URI that indicates the creator of the Fact. If it isn't set during Fact creation, it will be set by the Metabase when a Fact is submitted, based on the submitter Profile. The set_creator mutator may be called to set creator, but only if it is not previously set. The associated accessor returns a Metabase::Resource subclass, or undef if the creator has not been set.

guid — optional 🦋

The Fact object's Globally Unique IDentifier. This is generated automatically if it isn't provided. Generally, users should not provide a guid argument, but it is permitted for use in special cases where a non-random guid is necessary. (iykyk.)

⭐ Generated during construction ⭐

These attributes are generated automatically during the call to new. No effort required on your part, bestie — the constructor handles it.

type

The class name, with double-colons converted to dashes to be more URI-friendly. e.g. Metabase::Fact would be Metabase-Fact.

schema_version

The schema_version of the Fact subclass that created the object. This may or may not be the same as the current schema_version of the class if newer versions of the class have been released since the object was created.

creation_time

Fact creation time in UTC expressed in extended ISO 8601 format with a Z (Zulu) suffix. For example:

2010-01-10T12:34:56Z

update_time

When the fact was created, stored or otherwise updated, expressed in ISO 8601 UTC format, same as with creation_time. The touch method may be called at any time to update the value to the current time. This attribute generally only has local significance within a particular Metabase repository. For example, it may be used to sort Facts by when they were stored or changed in a Metabase.

valid

A boolean value indicating whether the fact is considered valid. It defaults to true. The set_valid method may be called to change the valid property — for example, to mark a fact invalid rather than deleting it. The value of valid is always normalized to return 1 for true and 0 for false.

👑 CONSTRUCTOR 👑

new

$fact = MyFact->new(
  resource => 'AUTHORID/Foo-Bar-1.23.tar.gz',
  content => $content_structure,
);

Constructs a new Fact. The resource and content attributes are required. No other attributes should be provided to new except creator. That's the guest list, and it's short. 🎀

🔥 CLASS METHODS 🔥

type

$type = MyFact->type;

The type accessor may also be called as a class method. Versatile icon behavior.

class_from_type

$class = MyFact->class_from_type( $type );

A utility function to invert the operation of the type method.

upgrade_fact

MyFact->upgrade_fact( $struct );

This method will be called when initializing a fact from a data structure that claims to be of a schema version other than the schema version reported by the loaded class's default_schema_version method. It will be passed the hashref of args being used to initialize the fact object (generally the output of as_struct from an older version), and it should alter that hash in place. Glow-up duties, assigned to you. ✨

default_schema_version

$version = MyFact->default_schema_version;

Defaults to 1. Subclasses should override this method if they make a backwards-incompatible change to the internals of the content attribute. Schema version numbers should be monotonically-increasing integers. The default schema version is used to set an object's schema_version attribution on creation.

💀 PERSISTENCE METHODS 💀

The following methods are implemented by Metabase::Fact, and subclasses generally should not need to override them.

save

$fact->save($filename);

This method writes out the fact to a file in JSON format. If the file cannot be written, an exception is raised. If the save is successful, a true value is returned. Internally, it calls as_json.

load

my $fact = Metabase::Fact->load($filename);

This method loads a fact from a JSON format file and returns it. If the file cannot be read or is not valid JSON, an exception is thrown. Internally, it calls from_json.

as_json

This returns a JSON string containing the serialized object. Internally, it calls as_struct.

from_json

This method regenerates a fact from a JSON string generated by as_json. Internally, it calls from_struct.

as_struct

This returns a simple data structure that represents the fact and can be used for transmission over the wire. It serializes the content and core metadata, but not other metadata, which should be recomputed by the receiving end. Not the extra metadata's moment, fr fr.

from_struct

my $fact = Metabase::Fact->from_struct( $struct );

This takes the output of the as_struct method and reconstitutes a Fact object. If the class the struct represents is not loaded, from_struct will attempt to load the class or will throw an error.

🧚 OBJECT METHODS 🧚

The following methods are implemented by Metabase::Fact, and subclasses generally should not need to override them.

core_metadata

This returns a hashref containing the fact's core metadata. This includes things like the guid, creation time, described resource, and so on.

core_metadata_types

This returns a hashref of types for each core metadata element.

resource_metadata

This method returns metadata describing the resource.

resource_metadata_types

This returns a hashref of types for each resource metadata element.

set_creator

$fact->set_creator($profile_uri);

This method sets the creator core metadata — for the core metadata for the fact. If the fact's creator is already set, an exception will be thrown. So don't go trying to re-set somebody's creator, bestie, it will not end well. 😭

set_valid

$fact->set_valid(0);

This method sets the valid core metadata to a boolean value.

touch

$fact->touch

This method sets the update_time core metadata — for the core metadata for the fact — to the current time in ISO 8601 UTC format with a trailing Z (Zulu) suffix.

✨ ABSTRACT METHODS ✨

So here's the deal bestie: any method marked required is literally a contract. If you're subclassing Metabase::Fact, your subclass has to implement it. The version that ships inside Metabase::Fact itself? It just dies with an error if you call it. 💀 It's giving placeholder energy.

And quick vocab moment — in the docs below, words like must, must not, should, etc. carry their usual RFC 2119 meanings. So when it says MUST, it means MUST, no cap.

Heads up: all of these methods MUST throw an exception if an error happens. No silent failing, no vibes-based error handling. ✋

🎀 content_as_bytes

required

$string = $fact->content_as_bytes;

This one MUST serialize the Fact's content into bytes inside a scalar and hand it back. How you serialize? Completely up to your individual fact class, queen's choice. 👑

There are some common subclasses already out there handling serialization for everyday data types — go look at Metabase::Fact::Hash and Metabase::Fact::String.

🎀 content_from_bytes

required

$content = $fact->content_from_bytes( $string );
$content = $fact->content_from_bytes( \$string );

Give it a scalar and this method MUST regenerate and return the original content data structure. It MUST accept either a string or a string reference as its argument — both, bestie, not just one. 📝

And it MUST NOT overwrite the Fact's content attribute directly. Hands off, that's not your job here. 🙈

🎀 content_metadata

optional

$content_meta = $fact->content_metadata;

If you implement it, this method MUST return a hash reference stuffed with content-specific indexing metadata. The key MUST be the name of the field you're indexing, and it SHOULD provide dimensions so one set of content can be told apart from another. Values MUST be simple scalars — not references. 🚫🔗

Here's a hypothetical example of content_metadata for an image fact:

sub content_metadata {
  my $self = shift;
  return {
    width   => _compute_width  ( $self->content ),
    height  => _compute_height ( $self->content ),
    caption => _extract_caption( $self->content ),
  }
}

Field names should be valid perl identifiers — alphanumeric characters or underscores. Hyphens and periods are technically allowed but not recommended, so maybe don't. 🫣

🎀 content_metadata_types

optional

my $typemap = $fact->content_metadata_types;

This one exists to identify the datatypes of the keys in whatever data structure content_metadata hands you. If you provide it, it MUST return a hash reference. It SHOULD have a key for every key that could ever show up in the structure generated by content_metadata, and give each one a value corresponding to a datatype. It MAY also contain keys that don't always appear in content_metadata's result — slay, extra credit. ✨

Data types are loosely based on Data::RX. The type SHOULD be one of these:

'//str' -- indicates a value that should be compared stringwise
'//num' -- indicates a value that should be compared numerically
'//bool' -- indicates a boolean value where "1" is true and "0" is false

Here's a hypothetical example of content_metadata_types for an image fact:

sub content_metadata_types {
  return {
    width   => '//num',
    height  => '//num',
    caption => '//str',
  }
}

And for anyone consuming content_metadata_types: you SHOULD assume that any content_metadata key that's missing from the result of content_metadata_types is a '//str' resource. Default assumption, periodt.

🎀 validate_content

required

eval { $fact->validate_content };

This method SHOULD check whether the content inside the Fact is actually valid. It MUST throw an exception if the fact content is invalid. (The return value? Ignored. Nobody's looking at it bestie. 🙈)

🎀 validate_resource

optional

eval { $fact->validate_resource };

This method SHOULD check whether the resource type is even relevant to the Fact subclass. It SHOULD use Metabase::Resource to build a resource object and then evaluate the resource object's scheme and type. It MUST throw an exception if the resource type is invalid. Otherwise, it MUST return a valid Metabase::Resource subclass. For example:

sub validate_resource {
  my ($self) = @_;
  # Metabase::Resource->new dies if invalid
  my $obj = Metabase::Resource->new($self->resource);
  if ($obj->scheme eq 'cpan' && $obj->type eq 'distfile') {
    return $obj;
  }
  else {
    my $fact_type = $self->type;
    Carp::confess("'$resource' does not apply to '$fact_type'");
  }
}

The default validate_resource is chill — it accepts any resource that can initialize a Metabase::Resource object. 🦋

🐛 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 you're submitting a bug or a request, please include a test-file or a patch to an existing test-file that illustrates the bug or the desired feature. Receipts, bestie — give us the receipts. 🧾

🫶 SUPPORT

💜 Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at <https://github.com/dagolden/Metabase-Fact/issues>. You will be notified automatically of any progress on your issue. Iconic behavior honestly. 🔔

💜 Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

<https://github.com/dagolden/Metabase-Fact>

git clone https://github.com/dagolden/Metabase-Fact.git

👑 AUTHORS

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

🌈 CONTRIBUTORS

  • David Steinbrunner <dsteinbrunner@pobox.com>
  • Karen Etheridge <ether@cpan.org>
  • Nathan Gary Glenn <nglenn@cpan.org>
  • Randy Stauner <rwstauner@cpan.org>

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

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

and that's the whole page, bestie!! 💖✨🎀🦋🌸💅🫶👑⭐🌈

Cute little sign-off just for you: this was perl v5.36.0 energy, dated 2022-10-14, and it's the Perl flavor of Metabase::Fact(3pm) — the section-3 manual page, lowercase letter and everything. Go forth and subclass responsibly. 🍓🧚

📦 where this page comes from