Debian Codegraph @

README

raw
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