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

README.hacking -- notes for contributors
----------------------------------------

CODING STYLE

Not all old code has been cleaned up, but going forward, please follow these
conventions:

* 2-space indentation with spaces, not tabs

DEPENDENCIES DURING DEVELOPMENT (AKA USING MYLIB)

It can be annoying to manage dependencies during development when testing
metabase distributions as they often depend on other metabase distributions
also under development.

There are a few options
(1) set PERL5LIB to include all metabase project files
(2) continually install all metabase project files while developing
(3) use "-Mylib" and the .mylib file

For (3), install the "ylib" module from CPAN.  Then, when you invoke "perl
-Mylib", all directories listed in the .mylib file will be added to @INC.  For
Makefile.PL, you'll need to make sure that -Mylib is used by perl as invoked
in the Makefile:

  $ perl -Mylib Makefile.PL PERL="`which perl` -Mylib"