.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Metabase::Fact 3pm" .TH Metabase::Fact 3pm "2022-10-14" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Metabase::Fact \- base class for Metabase Facts .SH "VERSION" .IX Header "VERSION" version 0.025 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& # 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 => \*(AqRJBS/Metabase\-Fact\-0.001.tar.gz\*(Aq, \& content => { \& status => \*(AqFAIL\*(Aq, \& time => 3029, \& }, \& ); \& \& $client\->send_fact($fact); .Ve .SH "DESCRIPTION" .IX Header "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. .PP Metabase::Fact is a base class for Facts (really opinions or analyses) that can be sent to or retrieved from a Metabase repository. .SS "Structure of a Fact object" .IX Subsection "Structure of a Fact object" A Fact object associates a \f(CW\*(C`content\*(C'\fR attribute with a \f(CW\*(C`resource\*(C'\fR attribute and a \f(CW\*(C`creator\*(C'\fR attribute. .PP The \f(CW\*(C`resource\*(C'\fR attribute must be in a \s-1URI\s0 format that can be validated via a Metabase::Resource subclass. The \f(CW\*(C`content\*(C'\fR attribute is an opaque scalar with subclass-specific meaning. The \f(CW\*(C`creator\*(C'\fR attribute is a \s-1URI\s0 with a \&\*(L"metabase:user\*(R" scheme and type (see Metabase::Resource::metabase). .PP Facts have three sets of metadata associate with them. Metadata are generally for use in indexing, searching and managing Facts. .IP "\(bu" 4 \&\f(CW\*(C`core metadata\*(C'\fR describe universal properties of all Facts and are used to submit, store, manage and retrieve Facts within the Metabase framework. .IP "\(bu" 4 \&\f(CW\*(C`resource metadata\*(C'\fR describe index properties derived from the \f(CW\*(C`resource\*(C'\fR attribute. (As these can be regenerated from the \f(CW\*(C`resource\*(C'\fR \*(-- which is part of \f(CW\*(C`core metadata\*(C'\fR \*(-- they are not stored with a serialized Fact.) .IP "\(bu" 4 \&\f(CW\*(C`content metadata\*(C'\fR describe index properties derived from the \f(CW\*(C`content\*(C'\fR attribute. (As these can be regenerated from the \f(CW\*(C`content\*(C'\fR \*(-- which is part of \f(CW\*(C`core metadata\*(C'\fR \*(-- they are not stored with a serialized Fact.) .PP Each of the three metadata sets has an associated accessor: \f(CW\*(C`core_metadata\*(C'\fR, \&\f(CW\*(C`resource_metadata\*(C'\fR and \f(CW\*(C`content_metadata\*(C'\fR. .PP Each of the three sets also has an accessor that returns a hashref with a data type for each possible element in the set: \f(CW\*(C`core_metadata_types\*(C'\fR, \&\f(CW\*(C`resource_metadata_types\*(C'\fR and \f(CW\*(C`content_metadata_types\*(C'\fR. .PP Data types are loosely based on Data::RX. For example: .PP .Vb 3 \& \*(Aq//str\*(Aq \-\- indicates a value that should be compared stringwise \& \*(Aq//num\*(Aq \-\- indicates a value that should be compared numerically \& \*(Aq//bool\*(Aq \-\- indicates a valut that is true or false .Ve .PP When searching on metadata, you must join the set name to the metadata element name with a period character. For example: .PP .Vb 6 \& core.guid \& core.creator \& core.resource \& resource.scheme \& content.size \& content.score .Ve .SH "ATTRIBUTES" .IX Header "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 \f(CW\*(C`content\*(C'\fR) are also part of \f(CW\*(C`core metadata\*(C'\fR. .SS "Arguments provided to new" .IX Subsection "Arguments provided to new" \fIcontent (required)\fR .IX Subsection "content (required)" .PP A reference to the actual information associated with the fact. The exact form of the content is up to each Fact class to determine. .PP \fIresource (required)\fR .IX Subsection "resource (required)" .PP The canonical resource (\s-1URI\s0) the Fact relates to. For \s-1CPAN\s0 distributions, this would be a \f(CW\*(C`cpan:///distfile/...\*(C'\fR \s-1URI.\s0 (See URI::cpan.) The associated accessor returns a Metabase::Resource subclass. .PP \fIcreator (optional)\fR .IX Subsection "creator (optional)" .PP A Metabase::User::Profile \s-1URI\s0 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 \f(CW\*(C`set_creator\*(C'\fR mutator may be called to set \f(CW\*(C`creator\*(C'\fR, but only if it is not previously set. The associated accessor returns a Metabase::Resource subclass or \f(CW\*(C`undef\*(C'\fR if the creator has not been set. .PP \fIguid (optional)\fR .IX Subsection "guid (optional)" .PP The Fact object's Globally Unique IDentifier. This is generated automatically if not provided. Generally, users should not provide a \f(CW\*(C`guid\*(C'\fR argument, but it is permitted for use in special cases where a non-random \f(CW\*(C`guid\*(C'\fR is necessary. .SS "Generated during construction" .IX Subsection "Generated during construction" These attributes are generated automatically during the call to \f(CW\*(C`new\*(C'\fR. .PP \fItype\fR .IX Subsection "type" .PP The class name, with double-colons converted to dashes to be more URI-friendly. e.g. \f(CW\*(C`Metabase::Fact\*(C'\fR would be \f(CW\*(C`Metabase\-Fact\*(C'\fR. .PP \fIschema_version\fR .IX Subsection "schema_version" .PP The \f(CW\*(C`schema_version\*(C'\fR of the Fact subclass that created the object. This may or may not be the same as the current \f(CW\*(C`schema_version\*(C'\fR of the class if newer versions of the class have been released since the object was created. .PP \fIcreation_time\fR .IX Subsection "creation_time" .PP Fact creation time in \s-1UTC\s0 expressed in extended \s-1ISO 8601\s0 format with a \&\*(L"Z\*(R" (Zulu) suffix. For example: .PP .Vb 1 \& 2010\-01\-10T12:34:56Z .Ve .PP \fIupdate_time\fR .IX Subsection "update_time" .PP When the fact was created, stored or otherwise updated, expressed an \s-1ISO 8601 UTC\s0 format as with \f(CW\*(C`creation_time\*(C'\fR. The \f(CW\*(C`touch\*(C'\fR 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. .PP \fIvalid\fR .IX Subsection "valid" .PP A boolean value indicating whether the fact is considered valid. It defaults to true. The \f(CW\*(C`set_valid\*(C'\fR method may be called to change the \f(CW\*(C`valid\*(C'\fR property, for example, to mark a fact invalid rather than deleting it. The value of \f(CW\*(C`valid\*(C'\fR is always normalized to return \*(L"1\*(R" for true and \*(L"0\*(R" for false. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .SS "new" .IX Subsection "new" .Vb 4 \& $fact = MyFact\->new( \& resource => \*(AqAUTHORID/Foo\-Bar\-1.23.tar.gz\*(Aq, \& content => $content_structure, \& ); .Ve .PP Constructs a new Fact. The \f(CW\*(C`resource\*(C'\fR and \f(CW\*(C`content\*(C'\fR attributes are required. No other attributes should be provided to \f(CW\*(C`new\*(C'\fR except \f(CW\*(C`creator\*(C'\fR. .SH "CLASS METHODS" .IX Header "CLASS METHODS" .SS "type" .IX Subsection "type" .Vb 1 \& $type = MyFact\->type; .Ve .PP The \f(CW\*(C`type\*(C'\fR accessor may also be called as a class method. .SS "class_from_type" .IX Subsection "class_from_type" .Vb 1 \& $class = MyFact\->class_from_type( $type ); .Ve .PP A utility function to invert the operation of the \f(CW\*(C`type\*(C'\fR method. .SS "upgrade_fact" .IX Subsection "upgrade_fact" .Vb 1 \& MyFact\->upgrade_fact( $struct ); .Ve .PP 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 \f(CW\*(C`default_schema_version\*(C'\fR method. It will be passed the hashref of args being used to initialized the fact object (generally the output of \&\f(CW\*(C`as_struct\*(C'\fR from an older version), and should alter that hash in place. .SS "default_schema_version" .IX Subsection "default_schema_version" .Vb 1 \& $version = MyFact\->default_schema_version; .Ve .PP 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. .SH "PERSISTENCE METHODS" .IX Header "PERSISTENCE METHODS" The following methods are implemented by Metabase::Fact and subclasses generally should not need to override them. .SS "save" .IX Subsection "save" .Vb 1 \& $fact\->save($filename); .Ve .PP This method writes out the fact to a file in \s-1JSON\s0 format. If the file cannot be written, an exception is raised. If the save is successful, a true value is returned. Internally, it calls \f(CW\*(C`as_json\*(C'\fR. .SS "load" .IX Subsection "load" .Vb 1 \& my $fact = Metabase::Fact\->load($filename); .Ve .PP This method loads a fact from a \s-1JSON\s0 format file and returns it. If the file cannot be read or is not valid \s-1JSON,\s0 and exception is thrown. Internally, it calls \f(CW\*(C`from_json\*(C'\fR. .SS "as_json" .IX Subsection "as_json" This returns a \s-1JSON\s0 string containing the serialized object. Internally, it calls \f(CW\*(C`as_struct\*(C'\fR. .SS "from_json" .IX Subsection "from_json" This method regenerates a fact from a \s-1JSON\s0 string generated by \&\f(CW\*(C`as_json\*(C'\fR. Internally, it calls \f(CW\*(C`from_struct\*(C'\fR. .SS "as_struct" .IX Subsection "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. .SS "from_struct" .IX Subsection "from_struct" .Vb 1 \& my $fact = Metabase::Fact\->from_struct( $struct ); .Ve .PP This takes the output of the \f(CW\*(C`as_struct\*(C'\fR method and reconstitutes a Fact object. If the class the struct represents is not loaded, \f(CW\*(C`from_struct\*(C'\fR will attempt to load the class or will throw an error. .SH "OBJECT METHODS" .IX Header "OBJECT METHODS" The following methods are implemented by Metabase::Fact and subclasses generally should not need to override them. .SS "core_metadata" .IX Subsection "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. .SS "core_metadata_types" .IX Subsection "core_metadata_types" This returns a hashref of types for each core metadata element .SS "resource_metadata" .IX Subsection "resource_metadata" This method returns metadata describing the resource. .SS "resource_metadata_types" .IX Subsection "resource_metadata_types" This returns a hashref of types for each resource metadata element .SS "set_creator" .IX Subsection "set_creator" .Vb 1 \& $fact\->set_creator($profile_uri); .Ve .PP This method sets the \f(CW\*(C`creator\*(C'\fR core metadata for the core metadata for the fact. If the fact's \f(CW\*(C`creator\*(C'\fR is already set, an exception will be thrown. .SS "set_valid" .IX Subsection "set_valid" .Vb 1 \& $fact\->set_valid(0); .Ve .PP This method sets the \f(CW\*(C`valid\*(C'\fR core metadata to a boolean value. .SS "touch" .IX Subsection "touch" .Vb 1 \& $fact\->touch .Ve .PP This method sets the \f(CW\*(C`update_time\*(C'\fR core metadata for the core metadata for the fact to the current time in \s-1ISO 8601 UTC\s0 format with a trailing \*(L"Z\*(R" (Zulu) suffice. .SH "ABSTRACT METHODS" .IX Header "ABSTRACT METHODS" Methods marked as \fIrequired\fR must be implemented by a Fact subclass. (The version in Metabase::Fact will die with an error if called.) .PP In the documentation below, the terms \fImust\fR, \fImust not\fR, \fIshould\fR, etc. have their usual \s-1RFC 2119\s0 meanings. .PP These methods \s-1MUST\s0 throw an exception if an error occurs. .SS "content_as_bytes" .IX Subsection "content_as_bytes" \&\fBrequired\fR .PP .Vb 1 \& $string = $fact\->content_as_bytes; .Ve .PP This method \s-1MUST\s0 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. .SS "content_from_bytes" .IX Subsection "content_from_bytes" \&\fBrequired\fR .PP .Vb 2 \& $content = $fact\->content_from_bytes( $string ); \& $content = $fact\->content_from_bytes( \e$string ); .Ve .PP Given a scalar, this method \s-1MUST\s0 regenerate and return the original content data structure. It \s-1MUST\s0 accept either a string or string reference as an argument. It \s-1MUST NOT\s0 overwrite the Fact's content attribute directly. .SS "content_metadata" .IX Subsection "content_metadata" \&\fBoptional\fR .PP .Vb 1 \& $content_meta = $fact\->content_metadata; .Ve .PP If provided, this method \s-1MUST\s0 return a hash reference with content-specific indexing metadata. The key \s-1MUST\s0 be the name of the field for indexing and \&\s-1SHOULD\s0 provide dimensions to differentiate one set of content from another. Values \s-1MUST\s0 be simple scalars, not references. .PP Here is a hypothetical example of \f(CW\*(C`content_metadata\*(C'\fR for an image fact: .PP .Vb 8 \& sub content_metadata { \& my $self = shift; \& return { \& width => _compute_width ( $self\->content ), \& height => _compute_height ( $self\->content ), \& caption => _extract_caption( $self\->content ), \& } \& } .Ve .PP Field names should be valid perl identifiers, consisting of alphanumeric characters or underscores. Hyphens and periods are allowed, but are not recommended. .SS "content_metadata_types" .IX Subsection "content_metadata_types" \&\fBoptional\fR .PP .Vb 1 \& my $typemap = $fact\->content_metadata_types; .Ve .PP This method is used to identify the datatypes of keys in the data structure provided by \f(CW\*(C`content_metadata\*(C'\fR. If provided, it \s-1MUST\s0 return a hash reference. It \s-1SHOULD\s0 contain a key for every key that could appear in the data structure generated by \f(CW\*(C`content_metadata\*(C'\fR and provide a value corresponding to a datatype for each key. It \s-1MAY\s0 contain keys that do not always appear in the result of \f(CW\*(C`content_metadata\*(C'\fR. .PP Data types are loosely based on Data::RX. Type \s-1SHOULD\s0 be one of the following: .PP .Vb 3 \& \*(Aq//str\*(Aq \-\- indicates a value that should be compared stringwise \& \*(Aq//num\*(Aq \-\- indicates a value that should be compared numerically \& \*(Aq//bool\*(Aq \-\- indicates a boolean value where "1" is true and "0" is false .Ve .PP Here is a hypothetical example of \f(CW\*(C`content_metadata_types\*(C'\fR for an image fact: .PP .Vb 7 \& sub content_metadata_types { \& return { \& width => \*(Aq//num\*(Aq, \& height => \*(Aq//num\*(Aq, \& caption => \*(Aq//str\*(Aq, \& } \& } .Ve .PP Consumers of \f(CW\*(C`content_metadata_types\*(C'\fR \s-1SHOULD\s0 assume that any \&\f(CW\*(C`content_metadata\*(C'\fR key not found in the result of \f(CW\*(C`content_metadata_types\*(C'\fR is a '//str' resource. .SS "validate_content" .IX Subsection "validate_content" \&\fBrequired\fR .PP .Vb 1 \& eval { $fact\->validate_content }; .Ve .PP This method \s-1SHOULD\s0 check for the validity of content within the Fact. It \&\s-1MUST\s0 throw an exception if the fact content is invalid. (The return value is ignored.) .SS "validate_resource" .IX Subsection "validate_resource" \&\fBoptional\fR .PP .Vb 1 \& eval { $fact\->validate_resource }; .Ve .PP This method \s-1SHOULD\s0 check whether the resource type is relevant for the Fact subclass. It \s-1SHOULD\s0 use Metabase::Resource to create a resource object and evaluate the resource object scheme and type. It \s-1MUST\s0 throw an exception if the resource type is invalid. Otherwise, it \s-1MUST\s0 return a valid Metabase::Resource subclass. For example: .PP .Vb 12 \& sub validate_resource { \& my ($self) = @_; \& # Metabase::Resource\->new dies if invalid \& my $obj = Metabase::Resource\->new($self\->resource); \& if ($obj\->scheme eq \*(Aqcpan\*(Aq && $obj\->type eq \*(Aqdistfile\*(Aq) { \& return $obj; \& } \& else { \& my $fact_type = $self\->type; \& Carp::confess("\*(Aq$resource\*(Aq does not apply to \*(Aq$fact_type\*(Aq"); \& } \& } .Ve .PP The default \f(CW\*(C`validate_resource\*(C'\fR accepts any resource that can initialize a \f(CW\*(C`Metabase::Resource\*(C'\fR object. .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature using the \s-1CPAN\s0 Request Tracker. Bugs can be submitted through the web interface at .PP 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. .SH "SUPPORT" .IX Header "SUPPORT" .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests through the issue tracker at . You will be notified automatically of any progress on your issue. .SS "Source Code" .IX Subsection "Source Code" This is open source software. The code repository is available for public review and contribution under the terms of the license. .PP .PP .Vb 1 \& git clone https://github.com/dagolden/Metabase\-Fact.git .Ve .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 David Golden .IP "\(bu" 4 Ricardo Signes .IP "\(bu" 4 H.Merijn Brand .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 David Steinbrunner .IP "\(bu" 4 Karen Etheridge .IP "\(bu" 4 Nathan Gary Glenn .IP "\(bu" 4 Randy Stauner .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2016 by David Golden. .PP This is free software, licensed under: .PP .Vb 1 \& The Apache License, Version 2.0, January 2004 .Ve