.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" 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 turned on, 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 .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Metabase::Resource 3pm" .TH Metabase::Resource 3pm "2013-09-11" "perl v5.18.1" "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::Resource \- factory class for Metabase resource descriptors .SH "VERSION" .IX Header "VERSION" version 0.022 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& my $resource = Metabase::Resource\->new( \& \*(Aqcpan:///distfile/RJBS/Metabase\-Fact\-0.001.tar.gz\*(Aq, \& ); \& \& my $resource_meta = $resource\->metadata; \& my $typemap = $resource\->metadata_types; .Ve .SH "DESCRIPTION" .IX Header "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. .PP Resources in Metabase are \s-1URI\s0's that consist of a scheme and scheme specific information. For example, a standard \s-1URI\s0 framework for a \&\s-1CPAN\s0 distribution is defined by the URI::cpan class. .PP .Vb 1 \& cpan:///distfile/RJBS/URI\-cpan\-1.000.tar.gz .Ve .PP 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. .PP For example, the Metabase::Resource::cpan class will deconstruct the example above this into a Metabase resource metadata structure with the following elements: .PP .Vb 5 \& 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 .Ve .PP Only the \f(CW\*(C`type\*(C'\fR field is mandatory for all resources. The other fields are all specific to Metabase::Resource::cpan. .SH "COMMON METHODS" .IX Header "COMMON METHODS" .SS "new" .IX Subsection "new" .Vb 3 \& my $resource = Metabase::Resource\->new( \& \*(Aqcpan:///distfile/RJBS/Metabase\-Fact\-0.001.tar.gz\*(Aq, \& ); .Ve .PP Takes a single resource string argument and constructs a new Resource object from a resource subtype determined by the \s-1URI\s0 scheme. Throws an error if the required resource subclass is not available. .SS "resource" .IX Subsection "resource" Returns the string used to initialize the resource object. .SS "scheme" .IX Subsection "scheme" Returns a string containing the scheme. .SS "_cache (private)" .IX Subsection "_cache (private)" Returns a hash reference for subclasses to use to store data derived from the \f(CW\*(C`content\*(C'\fR string. .SH "OVERLOADING" .IX Header "OVERLOADING" Resources have stringification overloaded to call \f(CW\*(C`content\*(C'\fR. Equality (==) and inequality (!=) are overloaded to perform string comparison instead. .SH "SUBCLASSING AND SUBCLASS METHODS" .IX Header "SUBCLASSING AND SUBCLASS METHODS" Metabase::Resource relies on subclasses to implement scheme-specific parsing of the \s-1URI\s0 into relevant index metadata. .PP Subclasses \s-1SHOULD NOT\s0 implement a \f(CW\*(C`new\*(C'\fR constructor, as the Metabase::Resource constructor will load the subclass, construct the object, bless the object into the subclass, and and then call \f(CW\*(C`validate\*(C'\fR on the object. Subclasses \&\s-1MAY\s0 store structured data derived from the content string during validation. .PP Subclasses \s-1SHOULD\s0 use the \f(CW\*(C`content\*(C'\fR method to access the resource string and the \f(CW\*(C`scheme\*(C'\fR method to access the scheme. Subclasses \s-1MAY\s0 use the \f(CW\*(C`_cache\*(C'\fR accessor to store derived metadata data. Subclasses \s-1MUST\s0 provide a \&\f(CW\*(C`metadata_types\*(C'\fR method to return data types for all elements stored in \f(CW\*(C`_cache\*(C'\fR. .PP All subclasses \s-1MUST\s0 implement the \f(CW\*(C`validate\*(C'\fR, \f(CW\*(C`metadata\*(C'\fR and \&\f(CW\*(C`metadata_types\*(C'\fR methods, as described below. .PP All methods \s-1MUST\s0 throw an exception if an error occurs. .SS "validate" .IX Subsection "validate" .Vb 1 \& $resource\->validate .Ve .PP This method is called by the constructor. It \s-1SHOULD\s0 return true if the resource string is valid according to scheme-specific rules. It \s-1MUST\s0 die if the resource string is invalid. .SS "metadata" .IX Subsection "metadata" .Vb 1 \& $meta = $resource\->metadata; .Ve .PP This method \s-1MUST\s0 return a hash reference with resource-specific indexing metadata for the Resource. The key \s-1MUST\s0 be the name of the field for indexing. The \f(CW\*(C`scheme\*(C'\fR key \s-1MUST\s0 be present and the \f(CW\*(C`scheme\*(C'\fR value \s-1MUST\s0 be identical to the string from the \f(CW\*(C`scheme\*(C'\fR accessor. Other keys \s-1SHOULD\s0 provide dimensions to differentiate one resource from another in the context of \f(CW\*(C`scheme\*(C'\fR. If a scheme has subcategories, the key \f(CW\*(C`type\*(C'\fR \s-1SHOULD\s0 be used for the subcategory. Values \s-1MUST\s0 be simple scalars, not references. .PP Here is a hypothetical example of a \f(CW\*(C`metadata\*(C'\fR function for a metabase user resource like 'metabase:user:ec2726a4\-070c\-11df\-a2e0\-0018f34ec37c': .PP .Vb 9 \& sub metadata { \& my $self = shift; \& my ($uuid) = $self =~ m{\eAmetabase:user:(.+)\ez}; \& return { \& scheme => \*(Aqmetabase\*(Aq, \& type => \*(Aquser\*(Aq, \& user => $uuid, \& } \& } .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 "metadata_types" .IX Subsection "metadata_types" .Vb 1 \& my $typemap = $resource\->metadata_types; .Ve .PP This method is used to identify the datatypes of keys in the data structure provided by \f(CW\*(C`metadata\*(C'\fR. 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`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`metadata\*(C'\fR. .PP Data types are loosely based on Data::RX. Type \s-1SHOULD\s0 be one of the following: .PP .Vb 2 \& \*(Aq//str\*(Aq \-\- indicates a value that should be compared stringwise \& \*(Aq//num\*(Aq \-\- indicates a value that should be compared numerically .Ve .PP Here is a hypothetical example of a \f(CW\*(C`metadata_types\*(C'\fR function for a metabase user resource like 'metabase:user:ec2726a4\-070c\-11df\-a2e0\-0018f34ec37c': .PP .Vb 7 \& sub metadata_types { \& return { \& scheme => \*(Aq//str\*(Aq, \& type => \*(Aq//str\*(Aq, \& user => \*(Aq//str\*(Aq, \& } \& } .Ve .PP Consumers of \f(CW\*(C`metadata_types\*(C'\fR \s-1SHOULD\s0 assume that any \f(CW\*(C`metadata\*(C'\fR key not found in the result of \f(CW\*(C`metadata_types\*(C'\fR is a '//str' resource. .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 "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 David Golden .IP "\(bu" 4 Ricardo Signes .IP "\(bu" 4 H.Merijn Brand .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2013 by David Golden. .PP This is free software, licensed under: .PP .Vb 1 \& The Apache License, Version 2.0, January 2004 .Ve