Metaba...source(3pm)

💖 Metabase::Resource — a Perl manual page, bestie edition 💖

okay so you found the manual page for Metabase::Resource, a factory class for Metabase resource descriptors. It's a User Contributed Perl Documentation page, it lives in section 3pm of the manual, and it's serving version 0.025. Let's get into it 🫶

---

✨ VERSION ✨

version 0.025 — that's the one, no cap.

---

🎀 SYNOPSIS 🎀

my $resource = Metabase::Resource->new(
  'cpan:///distfile/RJBS/Metabase-Fact-0.001.tar.gz',
);

my $resource_meta = $resource->metadata;
my $typemap       = $resource->metadata_types;

that's literally the whole vibe right there. three lines and you're booked and busy 💅

---

🌸 DESCRIPTION 🌸

okay so Metabase is a framework for associating metadata with arbitrary resources. And when we say arbitrary, we mean it — a Metabase can store test reports, reviews, coverage analysis reports, reports on static analysis of coding style, or honestly anything else you've got a Metabase::Fact type constructed for. it's giving versatile 👑

Resources in Metabase are URI's that consist of a scheme plus scheme-specific information. For example, a standard URI framework for a CPAN distribution is defined by the URI::cpan class:

cpan:///distfile/RJBS/URI-cpan-1.000.tar.gz

Metabase::Resource is a factory class for resource descriptors. It gives you a common interface for extracting scheme-specific indexing metadata out of a scheme-specific resource subclass. lowkey the whole point of it tbh.

For example, the Metabase::Resource::cpan class will deconstruct the example above into a Metabase resource metadata structure with these elements:

type         => Metabase-Resource-cpan-distfile
dist_file    => RJBS/URI-cpan-1.000.tar.gz
cpan_id      => RJBS
dist_name    => URI-cpan
dist_version => 1.000

Only the type field is mandatory for all resources — everything else is specific to Metabase::Resource::cpan. so type is the main character and the rest are the supporting cast 💖

---

🦋 COMMON METHODS 🦋

new

my $resource = Metabase::Resource->new(
  'cpan:///distfile/RJBS/Metabase-Fact-0.001.tar.gz',
);

Takes a single resource string argument and constructs a new Resource object from a resource subtype determined by the URI scheme. If the required resource subclass isn't available, it throws an error. no silent fails here bestie 😭

resource

Returns the string used to initialize the resource object. that's it, that's the whole method.

scheme

Returns a string containing the scheme.

_cache (private)

Returns a hash reference for subclasses to use to store data derived from the content string. it's private, so like… don't touch unless you're the subclass okay 🙈

---

💫 OVERLOADING 💫

Resources have stringification overloaded to call content. And equality (==) plus inequality (!=) are overloaded to do string comparison instead. so it's not doing math on them, it's comparing them as strings. periodt.

---

👑 SUBCLASSING AND SUBCLASS METHODS 👑

Metabase::Resource relies on subclasses to implement scheme-specific parsing of the URI into relevant index metadata. it's a whole team effort fr fr.

Subclasses SHOULD NOT implement a new constructor, because the Metabase::Resource constructor will load the subclass, construct the object, bless the object into the subclass, and then call validate on the object. Subclasses MAY store structured data derived from the content string during validation.

Subclasses SHOULD use the content method to access the resource string, and the scheme method to access the scheme. Subclasses MAY use the _cache accessor to store derived metadata data. Subclasses MUST provide a metadata_types method to return data types for all elements stored in _cache.

All subclasses MUST implement the validate, metadata and metadata_types methods, as described below.

All methods MUST throw an exception if an error occurs. ⚠️

---

validate

$resource->validate

This method is called by the constructor. It SHOULD return true if the resource string is valid according to scheme-specific rules. It MUST die if the resource string is invalid. no vibes-based validation allowed, sorry 💀

---

metadata

$meta = $resource->metadata;

This method MUST return a hash reference with resource-specific indexing metadata for the Resource. The key MUST be the name of the field for indexing. The scheme key MUST be present, and the scheme value MUST be identical to the string from the scheme accessor. Other keys SHOULD provide dimensions to differentiate one resource from another in the context of scheme. If a scheme has subcategories, the key type SHOULD be used for the subcategory. Values MUST be simple scalars, not references. no nested data structures, bestie, we keep it flat 🍓

Here's a hypothetical example of a metadata function for a metabase user resource like 'metabase:user:ec2726a4-070c-11df-a2e0-0018f34ec37c':

sub metadata {
  my $self = shift;
  my ($uuid) = $self =~ m{\Ametabase:user:(.+)\z};
  return {
    scheme  => 'metabase',
    type    => 'user',
    user    => $uuid,
  }
}

Field names should be valid perl identifiers, consisting of alphanumeric characters or underscores. Hyphens and periods are allowed, but are not recommended. ikyk 😌

---

metadata_types

my $typemap = $resource->metadata_types;

This method is used to identify the datatypes of keys in the data structure provided by metadata. It MUST return a hash reference. It SHOULD contain a key for every key that could appear in the data structure generated by metadata, and provide a value corresponding to a datatype for each key. It MAY contain keys that do not always appear in the result of metadata.

Data types are loosely based on Data::RX. Type SHOULD be one of the following:

'//str' -- indicates a value that should be compared stringwise
'//num' -- indicates a value that should be compared numerically

Here's a hypothetical example of a metadata_types function for a metabase user resource like 'metabase:user:ec2726a4-070c-11df-a2e0-0018f34ec37c':

sub metadata_types {
  return {
    scheme  => '//str',
    type    => '//str',
    user    => '//str',
  }
}

Consumers of metadata_types SHOULD assume that any metadata key not found in the result of metadata_types is a '//str' resource. so if it's not in the map, it's a string, deal with it 💅

---

😭 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. that last part is not optional im begging 🙏

---

🌈 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

---

that's the whole page bestie, you ate it 💖 this was rendered from the perl v5.36.0 docs, dated 2022-10-14, and it came out of the User Contributed Perl Documentation section, page Metaba...source(3pm) (yes the name got truncated in the header, we love a mystery). go forth and index some resources 🎀✨