.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "Meta::Builder::Base 3pm"
.TH Meta::Builder::Base 3pm "2012-12-16" "perl v5.14.2" "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"
Meta::Builder::Base \- Base class for Meta::Builder Meta Objects.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Base class for all Meta::Builder Meta objects. This is where the methods
used to define new metrics and actions live. This class allows for the creation
of dynamic meta objects.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
My/Meta.pm:
.PP
.Vb 3
\&    package My::Meta;
\&    use strict;
\&    use warnings;
\&
\&    use base \*(AqMeta::Builder::Base\*(Aq;
\&
\&    # Name the accessor that will be defined in the class that uses the meta object
\&    # It is used to retrieve the classes meta object.
\&    _\|_PACKAGE_\|_\->set_accessor( "mymeta" );
\&
\&    # Add a metric with two actions
\&    _\|_PACKAGE_\|_\->add_metric(
\&        mymetric => sub { [] },
\&        pop => sub {
\&            my $self = shift;
\&            my ( $data ) = @_;
\&            pop @$data;
\&        },
\&        push => sub {
\&            my $self = shift;
\&            my ( $data, $metric, $action, @args ) = @_;
\&            push @$data => @args;
\&        }
\&    );
\&
\&    # Add an additional action to the metric
\&    _\|_PACKAGE_\|_\->add_action( \*(Aqmymetric\*(Aq, get_ref => sub { shift });
\&
\&    # Add some predefined metric types + actions
\&    _\|_PACKAGE_\|_\->add_hash_metric( \*(Aqmy_hashmetric\*(Aq );
\&    _\|_PACKAGE_\|_\->add_lists_metric( \*(Aqmy_listsmetric\*(Aq );
.Ve
.PP
My.pm:
.PP
.Vb 3
\&    package My;
\&    use strict;
\&    use warnings;
\&
\&    use My::Meta;
\&
\&    My::Meta\->new( _\|_PACKAGE_\|_ );
\&
\&    # My::Meta defines mymeta() as the accessor we use to get our meta object.
\&    # this is the ONLY way to get the meta object for this class.
\&
\&    mymeta()\->mymetric_push( "some data" );
\&    mymeta()\->my_hashmetric_add( key => \*(Aqvalue\*(Aq );
\&    mymeta()\->my_listsmetric_push( list => qw/valueA valueB/ );
\&
\&    # It works fine as an object/class method as well.
\&    _\|_PACKAGE_\|_\->mymeta\->do_thing(...);
\&
\&    ...;
.Ve
.SH "PACKAGE METRIC"
.IX Header "PACKAGE METRIC"
Whenever you create a new instance of a meta-object you must provide the name
of the package to which the meta-object belongs. The 'package' metric will be
set to this package name, and can be retirved via the 'package' method:
\&\f(CW\*(C`$meta\-\*(C'\fR\fIpackage()\fR>.
.SH "HASH METRICS"
.IX Header "HASH METRICS"
Hash metrics are metrics that hold key/value pairs. A hash metric is defined
using either the \f(CW\*(C`hash_metric()\*(C'\fR function, or the \f(CW\*(C`$meta\-\*(C'\fR\fIadd_hash_metric()\fR>
method. The following actions are automatically defined for hash metrics:
.ie n .IP "$meta\->add_METRIC( $key, $value )" 4
.el .IP "\f(CW$meta\fR\->add_METRIC( \f(CW$key\fR, \f(CW$value\fR )" 4
.IX Item "$meta->add_METRIC( $key, $value )"
Add a key/value pair to the metric. Will throw an exception if the metric
already has a value for the specified key.
.ie n .IP "$value = $meta\->get_METRIC( $key )" 4
.el .IP "\f(CW$value\fR = \f(CW$meta\fR\->get_METRIC( \f(CW$key\fR )" 4
.IX Item "$value = $meta->get_METRIC( $key )"
Get the value for a specified key.
.ie n .IP "$bool = $meta\->has_METRIC( $key )" 4
.el .IP "\f(CW$bool\fR = \f(CW$meta\fR\->has_METRIC( \f(CW$key\fR )" 4
.IX Item "$bool = $meta->has_METRIC( $key )"
Check that the metric has the specified key defined.
.ie n .IP "$meta\->clear_METRIC( $key )" 4
.el .IP "\f(CW$meta\fR\->clear_METRIC( \f(CW$key\fR )" 4
.IX Item "$meta->clear_METRIC( $key )"
Clear the specified key/value pair in the metric. (returns nothing)
.ie n .IP "$value = $meta\->pull_METRIC( $key )" 4
.el .IP "\f(CW$value\fR = \f(CW$meta\fR\->pull_METRIC( \f(CW$key\fR )" 4
.IX Item "$value = $meta->pull_METRIC( $key )"
Get the value for the specified key, then clear the pair form the metric.
.SH "LISTS METRICS"
.IX Header "LISTS METRICS"
.ie n .IP "$meta\->push_METRIC( $key, @values )" 4
.el .IP "\f(CW$meta\fR\->push_METRIC( \f(CW$key\fR, \f(CW@values\fR )" 4
.IX Item "$meta->push_METRIC( $key, @values )"
Push values into the specified list for the given metric.
.ie n .IP "@values = $meta\->get_METRIC( $key )" 4
.el .IP "\f(CW@values\fR = \f(CW$meta\fR\->get_METRIC( \f(CW$key\fR )" 4
.IX Item "@values = $meta->get_METRIC( $key )"
Get the values for a specified key.
.ie n .IP "$bool = $meta\->has_METRIC( $key )" 4
.el .IP "\f(CW$bool\fR = \f(CW$meta\fR\->has_METRIC( \f(CW$key\fR )" 4
.IX Item "$bool = $meta->has_METRIC( $key )"
Check that the metric has the specified list.
.ie n .IP "$meta\->clear_METRIC( $key )" 4
.el .IP "\f(CW$meta\fR\->clear_METRIC( \f(CW$key\fR )" 4
.IX Item "$meta->clear_METRIC( $key )"
Clear the specified list in the metric. (returns nothing)
.ie n .IP "@values = $meta\->pull_METRIC( $key )" 4
.el .IP "\f(CW@values\fR = \f(CW$meta\fR\->pull_METRIC( \f(CW$key\fR )" 4
.IX Item "@values = $meta->pull_METRIC( $key )"
Get the values for the specified list in the metric, then clear the list.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.ie n .IP "$meta = $class\->new( $package, %metrics )" 4
.el .IP "\f(CW$meta\fR = \f(CW$class\fR\->new( \f(CW$package\fR, \f(CW%metrics\fR )" 4
.IX Item "$meta = $class->new( $package, %metrics )"
Create a new instance of the meta-class, and apply it to \f(CW$package\fR.
.ie n .IP "$metadata = $class\->\fImeta_meta()\fR" 4
.el .IP "\f(CW$metadata\fR = \f(CW$class\fR\->\fImeta_meta()\fR" 4
.IX Item "$metadata = $class->meta_meta()"
Get the meta data for the meta-class itself. (The meta-class is build using
meta-data)
.ie n .IP "$new_hashref = $class\->\fIgen_hash()\fR" 4
.el .IP "\f(CW$new_hashref\fR = \f(CW$class\fR\->\fIgen_hash()\fR" 4
.IX Item "$new_hashref = $class->gen_hash()"
Generate a new empty hashref.
.ie n .IP "$name = $class\->action_method_name( $metric, $action )" 4
.el .IP "\f(CW$name\fR = \f(CW$class\fR\->action_method_name( \f(CW$metric\fR, \f(CW$action\fR )" 4
.IX Item "$name = $class->action_method_name( $metric, $action )"
Generate the name of the method for the given metric and action. Override this
if you do not like the \s-1\fIMETRIC_ACTION\s0()\fR method names.
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
.ie n .IP "$package = $meta\->\fIpackage()\fR" 4
.el .IP "\f(CW$package\fR = \f(CW$meta\fR\->\fIpackage()\fR" 4
.IX Item "$package = $meta->package()"
Get the name of the package to which this meta-class applies.
.ie n .IP "$meta\->set_accessor( $name )" 4
.el .IP "\f(CW$meta\fR\->set_accessor( \f(CW$name\fR )" 4
.IX Item "$meta->set_accessor( $name )"
Set the accessor that is used to retrieve the meta-object from the class to
which it applies.
.ie n .IP "$meta\->add_hash_metric( $metric, %actions )" 4
.el .IP "\f(CW$meta\fR\->add_hash_metric( \f(CW$metric\fR, \f(CW%actions\fR )" 4
.IX Item "$meta->add_hash_metric( $metric, %actions )"
Add a hash metric (see \*(L"\s-1HASH\s0 \s-1METRICS\s0\*(R").
.Sp
\&\f(CW%actions\fR should contain \f(CW\*(C`action =<gt\*(C'\fR sub {...}> pairs for constructing
actions (See \fIadd_action()\fR).
.ie n .IP "$meta\->add_lists_metric( $metric, %actions )" 4
.el .IP "\f(CW$meta\fR\->add_lists_metric( \f(CW$metric\fR, \f(CW%actions\fR )" 4
.IX Item "$meta->add_lists_metric( $metric, %actions )"
Add a lists metric (see \*(L"\s-1LISTS\s0 \s-1METRICS\s0\*(R")
.Sp
\&\f(CW%actions\fR should contain \f(CW\*(C`action =<gt\*(C'\fR sub {...}> pairs for constructing
actions (See \fIadd_action()\fR).
.ie n .IP "$meta\->add_metric( $metric, \e&generator, %actions )" 4
.el .IP "\f(CW$meta\fR\->add_metric( \f(CW$metric\fR, \e&generator, \f(CW%actions\fR )" 4
.IX Item "$meta->add_metric( $metric, &generator, %actions )"
Add a custom metric. The second argument should be a sub that generates a
default value for the metric.
.Sp
\&\f(CW%actions\fR should contain \f(CW\*(C`action =<gt\*(C'\fR sub {...}> pairs for constructing
actions (See \fIadd_action()\fR).
.ie n .IP "$meta\->add_action( $metric, $action => sub { ... } )" 4
.el .IP "\f(CW$meta\fR\->add_action( \f(CW$metric\fR, \f(CW$action\fR => sub { ... } )" 4
.IX Item "$meta->add_action( $metric, $action => sub { ... } )"
Add an action for the specified metric. See \*(L"\s-1ACTION\s0 \s-1AND\s0 \s-1HOOK\s0 \s-1METHODS\s0\*(R" for
details on how to write an action coderef.
.ie n .IP "$meta\->hook_before( $metric, $action, sub { ... })" 4
.el .IP "\f(CW$meta\fR\->hook_before( \f(CW$metric\fR, \f(CW$action\fR, sub { ... })" 4
.IX Item "$meta->hook_before( $metric, $action, sub { ... })"
Add a hook for the specified metric. See \*(L"\s-1ACTION\s0 \s-1AND\s0 \s-1HOOK\s0 \s-1METHODS\s0\*(R" for
details on how to write a hook coderef.
.ie n .IP "$meta\->hook_after( $metric, $action, sub { ... })" 4
.el .IP "\f(CW$meta\fR\->hook_after( \f(CW$metric\fR, \f(CW$action\fR, sub { ... })" 4
.IX Item "$meta->hook_after( $metric, $action, sub { ... })"
Add a hook for the specified metric. See \*(L"\s-1ACTION\s0 \s-1AND\s0 \s-1HOOK\s0 \s-1METHODS\s0\*(R" for
details on how to write a hook coderef.
.SH "ACTION AND HOOK METHODS"
.IX Header "ACTION AND HOOK METHODS"
.Vb 5
\&    sub {
\&        my $self = shift;
\&        my ( $data, $metric, $action, @args ) = @_;
\&        ...;
\&    }
.Ve
.PP
Action and hook methods are called when someone calls
\&\f(CW\*(C`$meta\-<gt\*(C'\fRmetric_action(...)>. First all before hooks will be called, the the
action itself, and finally the after hooks will be called. All methods in the
chain get the exact same unaltered arguments. Only the main action sub can
return anything.
.PP
Arguments are:
.ie n .IP "0: $self" 4
.el .IP "0: \f(CW$self\fR" 4
.IX Item "0: $self"
These are methods, so the first argument is the meta object itself.
.ie n .IP "1: $data" 4
.el .IP "1: \f(CW$data\fR" 4
.IX Item "1: $data"
This is the data structure stored for the metric. This is the same as calling
\&\f(CW$meta\fR\->\fImetric()\fR
.ie n .IP "2: $metric" 4
.el .IP "2: \f(CW$metric\fR" 4
.IX Item "2: $metric"
Name of the metric
.ie n .IP "3: $action" 4
.el .IP "3: \f(CW$action\fR" 4
.IX Item "3: $action"
Name of the action
.ie n .IP "4+: @args" 4
.el .IP "4+: \f(CW@args\fR" 4
.IX Item "4+: @args"
Arguments that \fImetric_action()\fR was called with.
.SH "DEFAULT ACTION METHODS"
.IX Header "DEFAULT ACTION METHODS"
There are the default action methods used by hashmetrics and listsmetrics.
.ie n .IP "$meta\->default_hash_add( $data, $metric, $action, $item, $value )" 4
.el .IP "\f(CW$meta\fR\->default_hash_add( \f(CW$data\fR, \f(CW$metric\fR, \f(CW$action\fR, \f(CW$item\fR, \f(CW$value\fR )" 4
.IX Item "$meta->default_hash_add( $data, $metric, $action, $item, $value )"
.PD 0
.ie n .IP "$value = $meta\->default_hash_get( $data, $metric, $action, $item )" 4
.el .IP "\f(CW$value\fR = \f(CW$meta\fR\->default_hash_get( \f(CW$data\fR, \f(CW$metric\fR, \f(CW$action\fR, \f(CW$item\fR )" 4
.IX Item "$value = $meta->default_hash_get( $data, $metric, $action, $item )"
.ie n .IP "$bool = $meta\->default_hash_has( $data, $metric, $action, $item )" 4
.el .IP "\f(CW$bool\fR = \f(CW$meta\fR\->default_hash_has( \f(CW$data\fR, \f(CW$metric\fR, \f(CW$action\fR, \f(CW$item\fR )" 4
.IX Item "$bool = $meta->default_hash_has( $data, $metric, $action, $item )"
.ie n .IP "$meta\->default_hash_clear( $data, $metric, $action, $item )" 4
.el .IP "\f(CW$meta\fR\->default_hash_clear( \f(CW$data\fR, \f(CW$metric\fR, \f(CW$action\fR, \f(CW$item\fR )" 4
.IX Item "$meta->default_hash_clear( $data, $metric, $action, $item )"
.ie n .IP "$value = $meta\->default_hash_pull( $data, $metric, $action, $item )" 4
.el .IP "\f(CW$value\fR = \f(CW$meta\fR\->default_hash_pull( \f(CW$data\fR, \f(CW$metric\fR, \f(CW$action\fR, \f(CW$item\fR )" 4
.IX Item "$value = $meta->default_hash_pull( $data, $metric, $action, $item )"
.ie n .IP "$meta\->default_list_push( $data, $metric, $action, $item, @values )" 4
.el .IP "\f(CW$meta\fR\->default_list_push( \f(CW$data\fR, \f(CW$metric\fR, \f(CW$action\fR, \f(CW$item\fR, \f(CW@values\fR )" 4
.IX Item "$meta->default_list_push( $data, $metric, $action, $item, @values )"
.ie n .IP "@values = $meta\->default_list_get( $data, $metric, $action, $item )" 4
.el .IP "\f(CW@values\fR = \f(CW$meta\fR\->default_list_get( \f(CW$data\fR, \f(CW$metric\fR, \f(CW$action\fR, \f(CW$item\fR )" 4
.IX Item "@values = $meta->default_list_get( $data, $metric, $action, $item )"
.ie n .IP "$bool = $meta\->default_list_has( $data, $metric, $action, $item )" 4
.el .IP "\f(CW$bool\fR = \f(CW$meta\fR\->default_list_has( \f(CW$data\fR, \f(CW$metric\fR, \f(CW$action\fR, \f(CW$item\fR )" 4
.IX Item "$bool = $meta->default_list_has( $data, $metric, $action, $item )"
.ie n .IP "$meta\->default_list_clear( $data, $metric, $action, $item )" 4
.el .IP "\f(CW$meta\fR\->default_list_clear( \f(CW$data\fR, \f(CW$metric\fR, \f(CW$action\fR, \f(CW$item\fR )" 4
.IX Item "$meta->default_list_clear( $data, $metric, $action, $item )"
.ie n .IP "@values = $meta\->default_list_pull( $data, $metric, $action, $item )" 4
.el .IP "\f(CW@values\fR = \f(CW$meta\fR\->default_list_pull( \f(CW$data\fR, \f(CW$metric\fR, \f(CW$action\fR, \f(CW$item\fR )" 4
.IX Item "@values = $meta->default_list_pull( $data, $metric, $action, $item )"
.PD
.SH "AUTHORS"
.IX Header "AUTHORS"
Chad Granum exodist7@gmail.com
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2010 Chad Granum
.PP
Meta-Builder is free software; Standard perl licence.
.PP
Meta-Builder is distributed in the hope that it will be useful, but \s-1WITHOUT\s0
\&\s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0
\&\s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the license for more details.