Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

add generated meta files to repo

  • Loading branch information...
commit 92306a6bfb54e4fcfc46ce287efeeedfb1ac0b78 1 parent 5144822
@dagolden authored
Showing with 624 additions and 0 deletions.
  1. +141 −0 META.json
  2. +483 −0 README.pod
View
141 META.json
@@ -0,0 +1,141 @@
+{
+ "abstract" : "base class for Metabase Facts",
+ "author" : [
+ "David Golden <dagolden@cpan.org>",
+ "Ricardo Signes <rjbs@cpan.org>",
+ "H.Merijn Brand <hmbrand@cpan.org>"
+ ],
+ "dynamic_config" : 0,
+ "generated_by" : "Dist::Zilla version 4.300005, CPAN::Meta::Converter version 2.112621",
+ "license" : [
+ "apache_2_0"
+ ],
+ "meta-spec" : {
+ "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec",
+ "version" : "2"
+ },
+ "name" : "Metabase-Fact",
+ "no_index" : {
+ "directory" : [
+ "t",
+ "xt",
+ "examples",
+ "corpus"
+ ],
+ "package" : [
+ "DB"
+ ]
+ },
+ "prereqs" : {
+ "configure" : {
+ "requires" : {
+ "ExtUtils::MakeMaker" : "6.30"
+ }
+ },
+ "runtime" : {
+ "requires" : {
+ "CPAN::DistnameInfo" : 0,
+ "Carp" : 0,
+ "Data::GUID" : 0,
+ "Getopt::Long" : 0,
+ "JSON" : "2",
+ "Pod::Usage" : 0,
+ "overload" : 0,
+ "perl" : "5.006",
+ "strict" : 0,
+ "warnings" : 0
+ }
+ },
+ "test" : {
+ "requires" : {
+ "Cwd" : 0,
+ "File::Find" : 0,
+ "File::Spec" : 0,
+ "File::Temp" : "0.20",
+ "Test::Exception" : 0,
+ "Test::More" : "0.88"
+ }
+ }
+ },
+ "provides" : {
+ "Metabase::Fact" : {
+ "file" : "lib/Metabase/Fact.pm",
+ "version" : "0.021"
+ },
+ "Metabase::Fact::Hash" : {
+ "file" : "lib/Metabase/Fact/Hash.pm",
+ "version" : "0.021"
+ },
+ "Metabase::Fact::String" : {
+ "file" : "lib/Metabase/Fact/String.pm",
+ "version" : "0.021"
+ },
+ "Metabase::Report" : {
+ "file" : "lib/Metabase/Report.pm",
+ "version" : "0.021"
+ },
+ "Metabase::Resource" : {
+ "file" : "lib/Metabase/Resource.pm",
+ "version" : "0.021"
+ },
+ "Metabase::Resource::cpan" : {
+ "file" : "lib/Metabase/Resource/cpan.pm",
+ "version" : "0.021"
+ },
+ "Metabase::Resource::cpan::distfile" : {
+ "file" : "lib/Metabase/Resource/cpan/distfile.pm",
+ "version" : "0.021"
+ },
+ "Metabase::Resource::metabase" : {
+ "file" : "lib/Metabase/Resource/metabase.pm",
+ "version" : "0.021"
+ },
+ "Metabase::Resource::metabase::fact" : {
+ "file" : "lib/Metabase/Resource/metabase/fact.pm",
+ "version" : "0.021"
+ },
+ "Metabase::Resource::metabase::user" : {
+ "file" : "lib/Metabase/Resource/metabase/user.pm",
+ "version" : "0.021"
+ },
+ "Metabase::Resource::perl" : {
+ "file" : "lib/Metabase/Resource/perl.pm",
+ "version" : "0.021"
+ },
+ "Metabase::Resource::perl::commit" : {
+ "file" : "lib/Metabase/Resource/perl/commit.pm",
+ "version" : "0.021"
+ },
+ "Metabase::User::EmailAddress" : {
+ "file" : "lib/Metabase/User/EmailAddress.pm",
+ "version" : "0.021"
+ },
+ "Metabase::User::FullName" : {
+ "file" : "lib/Metabase/User/FullName.pm",
+ "version" : "0.021"
+ },
+ "Metabase::User::Profile" : {
+ "file" : "lib/Metabase/User/Profile.pm",
+ "version" : "0.021"
+ },
+ "Metabase::User::Secret" : {
+ "file" : "lib/Metabase/User/Secret.pm",
+ "version" : "0.021"
+ }
+ },
+ "release_status" : "stable",
+ "resources" : {
+ "bugtracker" : {
+ "mailto" : "bug-metabase-fact at rt.cpan.org",
+ "web" : "http://rt.cpan.org/Public/Dist/Display.html?Name=Metabase-Fact"
+ },
+ "homepage" : "https://github.com/dagolden/metabase-fact",
+ "repository" : {
+ "type" : "git",
+ "url" : "https://github.com/dagolden/metabase-fact.git",
+ "web" : "https://github.com/dagolden/metabase-fact"
+ }
+ },
+ "version" : "0.021"
+}
+
View
483 README.pod
@@ -0,0 +1,483 @@
+=head1 NAME
+
+Metabase::Fact - base class for Metabase Facts
+
+=head1 VERSION
+
+version 0.021
+
+=head1 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);
+
+=head1 DESCRIPTION
+
+L<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.
+
+=head2 Structure of a Fact object
+
+A Fact object associates a C<content> attribute with a C<resource> attribute
+and a C<creator> attribute.
+
+The C<resource> attribute must be in a URI format that can be validated via a
+L<Metabase::Resource> subclass. The C<content> attribute is an opaque scalar
+with subclass-specific meaning. The C<creator> attribute is a URI with a
+"metabase:user" scheme and type (see L<Metabase::Resource::metabase>).
+
+Facts have three sets of metadata associate with them. Metadata are generally
+for use in indexing, searching and managing Facts.
+
+=over
+
+=item *
+
+C<core metadata> describe universal properties of all Facts and are used
+to submit, store, manage and retrieve Facts within the Metabase framework.
+
+=item *
+
+C<resource metadata> describe index properties derived from the C<resource>
+attribute. (As these can be regenerated from the C<resource> -- which is part
+of C<core metadata> -- they are not stored with a serialized Fact.)
+
+=item *
+
+C<content metadata> describe index properties derived from the C<content>
+attribute. (As these can be regenerated from the C<content> -- which is part
+of C<core metadata> -- they are not stored with a serialized Fact.)
+
+=back
+
+Each of the three metadata sets has an associated accessor: C<core_metadata>,
+C<resource_metadata> and C<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: C<core_metadata_types>,
+C<resource_metadata_types> and C<content_metadata_types>.
+
+Data types are loosely based on L<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
+
+=head1 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 C<content>) are also part of C<core metadata>.
+
+=head2 Arguments provided to new
+
+=head3 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.
+
+=head3 resource (required)
+
+The canonical resource (URI) the Fact relates to. For CPAN distributions, this
+would be a C<cpan:///distfile/...> URI. (See L<URI::cpan>.) The associated
+accessor returns a Metabase::Resource subclass.
+
+=head3 creator (optional)
+
+A L<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's Profile. The C<set_creator> mutator may be
+called to set C<creator>, but only if it is not previously set. The associated
+accessor returns a Metabase::Resource subclass or C<undef> if the creator
+has not been set.
+
+=head3 guid (optional)
+
+The Fact object's Globally Unique IDentifier. This is generated automatically
+if not provided. Generally, users should not provide a C<guid> argument, but
+it is permitted for use in special cases where a non-random C<guid> is necessary.
+
+=head2 Generated during construction
+
+These attributes are generated automatically during the call to C<new>.
+
+=head3 type
+
+The class name, with double-colons converted to dashes to be more
+URI-friendly. e.g. C<Metabase::Fact> would be C<Metabase-Fact>.
+
+=head3 schema_version
+
+The C<schema_version> of the Fact subclass that created the object. This may or
+may not be the same as the current C<schema_version> of the class if newer
+versions of the class have been released since the object was created.
+
+=head3 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
+
+=head3 update_time
+
+When the fact was created, stored or otherwise updated, expressed an ISO 8601
+UTC format as with C<creation_time>. The C<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.
+
+=head3 valid
+
+A boolean value indicating whether the fact is considered valid. It defaults
+to true. The C<set_valid> method may be called to change the C<valid>
+property, for example, to mark a fact invalid rather than deleting it. The
+value of C<valid> is always normalized to return "1" for true and "0" for false.
+
+=head1 CONSTRUCTOR
+
+=head2 new
+
+ $fact = MyFact->new(
+ resource => 'AUTHORID/Foo-Bar-1.23.tar.gz',
+ content => $content_structure,
+ );
+
+Constructs a new Fact. The C<resource> and C<content> attributes are required.
+No other attributes should be provided to C<new> except C<creator>.
+
+=head1 CLASS METHODS
+
+=head2 type
+
+ $type = MyFact->type;
+
+The C<type> accessor may also be called as a class method.
+
+=head2 class_from_type
+
+ $class = MyFact->class_from_type( $type );
+
+A utility function to invert the operation of the C<type> method.
+
+=head2 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 C<default_schema_version> method. It will be passed the hashref
+of args being used to initialized the fact object (generally the output of
+C<as_struct> from an older version), and should alter that hash in place.
+
+=head2 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.
+
+=head1 PERSISTANCE METHODS
+
+The following methods are implemented by Metabase::Fact and subclasses
+generally should not need to override them.
+
+=head2 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 C<as_json>.
+
+=head2 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 C<from_json>.
+
+=head2 as_json
+
+This returns a JSON string containing the serialized object. Internally, it
+calls C<as_struct>.
+
+=head2 from_json
+
+This method regenerates a fact from a JSON string generated by
+C<as_json>. Internally, it calls C<from_struct>.
+
+=head2 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.
+
+=head2 from_struct
+
+ my $fact = Metabase::Fact->from_struct( $struct );
+
+This takes the output of the C<as_struct> method and reconstitutes a Fact
+object. If the class the struct represents is not loaded, C<from_struct>
+will attempt to load the class or will throw an error.
+
+=head1 OBJECT METHODS
+
+The following methods are implemented by Metabase::Fact and subclasses
+generally should not need to override them.
+
+=head2 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.
+
+=head2 core_metadata_types
+
+This returns a hashref of types for each core metadata element
+
+=head2 resource_metadata
+
+This method returns metadata describing the resource.
+
+=head2 resource_metadata_types
+
+This returns a hashref of types for each resource metadata element
+
+=head2 set_creator
+
+ $fact->set_creator($profile_uri);
+
+This method sets the C<creator> core metadata for the core metadata for the
+fact. If the fact's C<creator> is already set, an exception will be thrown.
+
+=head2 set_valid
+
+ $fact->set_valid(0);
+
+This method sets the C<valid> core metadata to a boolean value.
+
+=head2 touch
+
+ $fact->touch
+
+This method sets the C<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)
+suffic.
+
+=head1 ABSTRACT METHODS
+
+Methods marked as F<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 F<must>, F<must not>, F<should>, etc.
+have their usual RFC 2119 meanings.
+
+These methods MUST throw an exception if an error occurs.
+
+=head2 content_as_bytes
+
+B<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 L<Metabase::Fact::Hash> and L<Metabase::Fact::String>.
+
+=head2 content_from_bytes
+
+B<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.
+
+=head2 content_metadata
+
+B<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 C<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.
+
+=head2 content_metadata_types
+
+B<optional>
+
+ my $typemap = $fact->content_metadata_types;
+
+This method is used to identify the datatypes of keys in the data structure
+provided by C<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 C<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 C<content_metadata>.
+
+Data types are loosely based on L<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 C<content_metadata_types> for an image fact:
+
+ sub content_metadata_types {
+ return {
+ width => '//num',
+ height => '//num',
+ caption => '//str',
+ }
+ }
+
+Consumers of C<content_metadata_types> SHOULD assume that any
+C<content_metadata> key not found in the result of C<content_metadata_types> is
+a '//str' resource.
+
+=head2 validate_content
+
+B<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.)
+
+=head2 validate_resource
+
+B<optional>
+
+ eval { $fact->validate_resource };
+
+This method SHOULD check whether the resource type is relevant for the Fact
+subclass. It SHOULD use L<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 C<validate_resource> accepts any resource that can initialize
+a C<Metabase::Resource> object.
+
+=head1 BUGS
+
+Please report any bugs or feature using the CPAN Request Tracker.
+Bugs can be submitted through the web interface at
+L<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.
+
+=for :stopwords cpan testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata placeholders
+
+=head1 SUPPORT
+
+=head2 Bugs / Feature Requests
+
+Please report any bugs or feature requests through the issue tracker
+at L<http://rt.cpan.org/Public/Dist/Display.html?Name=Metabase-Fact>.
+You will be notified automatically of any progress on your issue.
+
+=head2 Source Code
+
+This is open source software. The code repository is available for
+public review and contribution under the terms of the license.
+
+L<https://github.com/dagolden/metabase-fact>
+
+ git clone https://github.com/dagolden/metabase-fact.git
+
+=head1 AUTHORS
+
+=over 4
+
+=item *
+
+David Golden <dagolden@cpan.org>
+
+=item *
+
+Ricardo Signes <rjbs@cpan.org>
+
+=item *
+
+H.Merijn Brand <hmbrand@cpan.org>
+
+=back
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is Copyright (c) 2012 by David Golden.
+
+This is free software, licensed under:
+
+ The Apache License, Version 2.0, January 2004
+
Please sign in to comment.
Something went wrong with that request. Please try again.