| 1 |
NAME |
| 2 |
|
| 3 |
Meta::Builder - Tools for creating Meta objects to track custom |
| 4 |
metrics. |
| 5 |
|
| 6 |
DESCRIPTION |
| 7 |
|
| 8 |
Meta programming is becoming more and more popular. The popularity of |
| 9 |
Meta programming comes from the fact that many problems are made |
| 10 |
significantly easier. There are a few specialized Meta tools out there, |
| 11 |
for instance Class:MOP which is used by Moose to track class metadata. |
| 12 |
|
| 13 |
Meta::Builder is designed to be a generic tool for writing Meta |
| 14 |
objects. Unlike specialized tools, Meta::Builder makes no assumptions |
| 15 |
about what metrics you will care about. Meta::Builder also makes it |
| 16 |
simple for others to extend your meta-object based tools by providing |
| 17 |
hooks for other packages to add metrics to your meta object. |
| 18 |
|
| 19 |
If a specialized Meta object tool is available to meet your needs |
| 20 |
please use it. However if you need a simple Meta object to track a |
| 21 |
couple metrics, use Meta::Builder. |
| 22 |
|
| 23 |
Meta::Builder is also low-sugar and low-dep. In most cases you will not |
| 24 |
want a class that needs a meta object to use your meta-object class |
| 25 |
directly. Rather you will usually want to create a sugar class that |
| 26 |
exports enhanced API functions that manipulate the meta object. |
| 27 |
|
| 28 |
SYNOPSIS |
| 29 |
|
| 30 |
My/Meta.pm: |
| 31 |
|
| 32 |
package My::Meta; |
| 33 |
use strict; |
| 34 |
use warnings; |
| 35 |
|
| 36 |
use Meta::Builder; |
| 37 |
|
| 38 |
# Name the accessor that will be defined in the class that uses the meta object |
| 39 |
# It is used to retrieve the classes meta object. |
| 40 |
accessor "mymeta"; |
| 41 |
|
| 42 |
# Add a metric with two actions |
| 43 |
metric mymetric => sub { [] }, |
| 44 |
pop => sub { |
| 45 |
my $self = shift; |
| 46 |
my ( $data ) = @_; |
| 47 |
pop @$data; |
| 48 |
}, |
| 49 |
push => sub { |
| 50 |
my $self = shift; |
| 51 |
my ( $data, $metric, $action, @args ) = @_; |
| 52 |
push @$data => @args; |
| 53 |
}; |
| 54 |
|
| 55 |
# Add an additional action to the metric |
| 56 |
action mymetric => ( get_ref => sub { shift }); |
| 57 |
|
| 58 |
# Add some predefined metric types + actions |
| 59 |
hash_metric 'my_hashmetric'; |
| 60 |
lists_metric 'my_listsmetric'; |
| 61 |
|
| 62 |
My.pm: |
| 63 |
|
| 64 |
package My; |
| 65 |
use strict; |
| 66 |
use warnings; |
| 67 |
|
| 68 |
use My::Meta; |
| 69 |
|
| 70 |
My::Meta->new( __PACKAGE__ ); |
| 71 |
|
| 72 |
# My::Meta defines mymeta() as the accessor we use to get our meta object. |
| 73 |
# this is the ONLY way to get the meta object for this class. |
| 74 |
|
| 75 |
mymeta()->mymetric_push( "some data" ); |
| 76 |
mymeta()->my_hashmetric_add( key => 'value' ); |
| 77 |
mymeta()->my_listsmetric_push( list => qw/valueA valueB/ ); |
| 78 |
|
| 79 |
# It works fine as an object/class method as well. |
| 80 |
__PACKAGE__->mymeta->do_thing(...); |
| 81 |
|
| 82 |
...; |
| 83 |
|
| 84 |
USING |
| 85 |
|
| 86 |
When you use Meta::Builder your class is automatically turned into a |
| 87 |
subclass of Meta::Builder::Base. In addition several "sugar" functions |
| 88 |
are exported into your namespace. To avoid the "sugar" functions you |
| 89 |
can simply subclass Meta::Builder::Base directly. |
| 90 |
|
| 91 |
EXPORTS |
| 92 |
|
| 93 |
metric( $name, \&generator, %actions ) |
| 94 |
|
| 95 |
Wrapper around caller-add_metric()>. See Meta::Builder::Base. |
| 96 |
|
| 97 |
action( $metric, $name, $code ) |
| 98 |
|
| 99 |
Wrapper around caller-add_action()>. See Meta::Builder::Base. |
| 100 |
|
| 101 |
hash_metric( $name, %additional_actions ) |
| 102 |
|
| 103 |
Wrapper around caller-add_hash_metric()>. See Meta::Builder::Base. |
| 104 |
|
| 105 |
lists_metric( $name, %additional_actions ) |
| 106 |
|
| 107 |
Wrapper around caller-add_lists_metric()>. See Meta::Builder::Base. |
| 108 |
|
| 109 |
before( $metric, $action, $code ) |
| 110 |
|
| 111 |
Wrapper around caller-hook_before()>. See Meta::Builder::Base. |
| 112 |
|
| 113 |
after( $metric, $action, $code ) |
| 114 |
|
| 115 |
Wrapper around caller-hook_after()>. See Meta::Builder::Base. |
| 116 |
|
| 117 |
accessor( $name ) |
| 118 |
|
| 119 |
Wrapper around caller-set_accessor()>. See Meta::Builder::Base. |
| 120 |
|
| 121 |
make_immutable() |
| 122 |
|
| 123 |
Overrides all functions/methods that alter the meta objects |
| 124 |
meta-data. This in effect prevents anything from adding new metrics, |
| 125 |
actions, or hooks without directly editing the metadata. |
| 126 |
|
| 127 |
AUTHORS |
| 128 |
|
| 129 |
Chad Granum [email protected] |
| 130 |
|
| 131 |
COPYRIGHT |
| 132 |
|
| 133 |
Copyright (C) 2010 Chad Granum |
| 134 |
|
| 135 |
Meta-Builder is free software and is licensed under the same terms as |
| 136 |
Perl itself. |
| 137 |
|
| 138 |
Meta-Builder is distributed in the hope that it will be useful, but |
| 139 |
WITHOUT ANY WARRANTY; without even the implied warranty of |
| 140 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license |
| 141 |
for more details. |
| 142 |
|