NAME

       Metabase::Resource - factory class for Metabase resource descriptors

VERSION

       version 0.025

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;

DESCRIPTION

       Metabase is a framework for associating metadata with arbitrary resources.  A Metabase can be used to
       store test reports, reviews, coverage analysis reports, reports on static analysis of coding style, or
       anything else for which Metabase::Fact types are constructed.

       Resources in Metabase are URI's that consist of a scheme and 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 provide a common interface to extract
       scheme-specific indexing metadata from a scheme-specific resource subclass.

       For example, the Metabase::Resource::cpan class will deconstruct the example above this into a Metabase
       resource metadata structure with the following 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.  The other fields are all specific to
       Metabase::Resource::cpan.

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.  Throws an error if the required resource subclass is not available.

   resource
       Returns the string used to initialize the resource object.

   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.

OVERLOADING

       Resources have stringification overloaded to call "content".  Equality (==) and inequality (!=) are
       overloaded to perform string comparison instead.

SUBCLASSING AND SUBCLASS METHODS

       Metabase::Resource relies on subclasses to implement scheme-specific parsing of the URI into relevant
       index metadata.

       Subclasses SHOULD NOT implement a "new" constructor, as 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.

   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.

       Here is 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.

   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 is 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.

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