Provided by: libmetabase-fact-perl_0.025-4_all bug

NAME

       Metabase::Fact - base class for Metabase Facts

VERSION

       version 0.025

SYNOPSIS

         # 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

       Metabase is a framework for associating content and 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 datatypes are constructed.

       Metabase::Fact is a base class for Facts (really opinions or analyses) 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 associate with them.  Metadata are generally for use in
       indexing, searching and managing Facts.

       •   "core metadata" describe universal properties of all Facts and are used to submit,
           store, manage and retrieve Facts within the Metabase framework.

       •   "resource metadata" describe index properties derived from the "resource" attribute.
           (As these can be regenerated from the "resource" -- which is part of "core metadata"
           -- they are not stored with a serialized Fact.)

       •   "content metadata" describe index properties derived from the "content" attribute.
           (As 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 valut 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 are either provided as arguments
       to the constructor or are 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.

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

   Generated during construction
       These attributes are generated automatically during the call to "new".

       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 an ISO 8601 UTC format
       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".

CLASS METHODS

   type
         $type = MyFact->type;

       The "type" accessor may also be called as a class method.

   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
       initialized the fact object (generally the output of "as_struct" from an older version),
       and should alter that hash in place.

   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
       objects 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, and 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.

   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.

   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) suffice.

ABSTRACT METHODS

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

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

       These methods MUST throw an exception if an error occurs.

   content_as_bytes
       required

         $string = $fact->content_as_bytes;

       This method MUST serialize a Fact's content as bytes in a scalar and return it.  The
       method for serialization is up to the individual fact class to determine.  Some common
       subclasses are available to handle serialization for common data types.  See
       Metabase::Fact::Hash and Metabase::Fact::String.

   content_from_bytes
       required

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

       Given a scalar, this method MUST regenerate and return the original content data
       structure.  It MUST accept either a string or string reference as an argument.  It MUST
       NOT overwrite the Fact's content attribute directly.

   content_metadata
       optional

         $content_meta = $fact->content_metadata;

       If provided, this method MUST return a hash reference with content-specific indexing
       metadata. The key MUST be the name of the field for indexing and SHOULD provide dimensions
       to differentiate one set of content from another.  Values MUST be simple scalars, not
       references.

       Here is 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, consisting of alphanumeric characters or
       underscores.  Hyphens and periods are allowed, but are not recommended.

   content_metadata_types
       optional

         my $typemap = $fact->content_metadata_types;

       This method is used to identify the datatypes of keys in the data structure provided by
       "content_metadata".  If provided, it MUST return a hash reference.  It SHOULD contain a
       key for every key that could appear in the data structure generated by "content_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 "content_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
         '//bool' -- indicates a boolean value where "1" is true and "0" is false

       Here is a hypothetical example of "content_metadata_types" for an image fact:

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

       Consumers of "content_metadata_types" SHOULD assume that any "content_metadata" key not
       found in the result of "content_metadata_types" is a '//str' resource.

   validate_content
       required

        eval { $fact->validate_content };

       This method SHOULD check for the validity of content within the Fact.  It MUST throw an
       exception if the fact content is invalid.  (The return value is ignored.)

   validate_resource
       optional

        eval { $fact->validate_resource };

       This method SHOULD check whether the resource type is relevant for the Fact subclass.  It
       SHOULD use Metabase::Resource to create a resource object and evaluate the resource object
       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" 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 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.

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.

   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>

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