1Meta::Builder::Base(3)User Contributed Perl DocumentationMeta::Builder::Base(3)
2
3
4

NAME

6       Meta::Builder::Base - Base class for Meta::Builder Meta Objects.
7

DESCRIPTION

9       Base class for all Meta::Builder Meta objects. This is where the
10       methods used to define new metrics and actions live. This class allows
11       for the creation of dynamic meta objects.
12

SYNOPSIS

14       My/Meta.pm:
15
16           package My::Meta;
17           use strict;
18           use warnings;
19
20           use base 'Meta::Builder::Base';
21
22           # Name the accessor that will be defined in the class that uses the meta object
23           # It is used to retrieve the classes meta object.
24           __PACKAGE__->set_accessor( "mymeta" );
25
26           # Add a metric with two actions
27           __PACKAGE__->add_metric(
28               mymetric => sub { [] },
29               pop => sub {
30                   my $self = shift;
31                   my ( $data ) = @_;
32                   pop @$data;
33               },
34               push => sub {
35                   my $self = shift;
36                   my ( $data, $metric, $action, @args ) = @_;
37                   push @$data => @args;
38               }
39           );
40
41           # Add an additional action to the metric
42           __PACKAGE__->add_action( 'mymetric', get_ref => sub { shift });
43
44           # Add some predefined metric types + actions
45           __PACKAGE__->add_hash_metric( 'my_hashmetric' );
46           __PACKAGE__->add_lists_metric( 'my_listsmetric' );
47
48       My.pm:
49
50           package My;
51           use strict;
52           use warnings;
53
54           use My::Meta;
55
56           My::Meta->new( __PACKAGE__ );
57
58           # My::Meta defines mymeta() as the accessor we use to get our meta object.
59           # this is the ONLY way to get the meta object for this class.
60
61           mymeta()->mymetric_push( "some data" );
62           mymeta()->my_hashmetric_add( key => 'value' );
63           mymeta()->my_listsmetric_push( list => qw/valueA valueB/ );
64
65           # It works fine as an object/class method as well.
66           __PACKAGE__->mymeta->do_thing(...);
67
68           ...;
69

PACKAGE METRIC

71       Whenever you create a new instance of a meta-object you must provide
72       the name of the package to which the meta-object belongs. The 'package'
73       metric will be set to this package name, and can be retrieved via the
74       'package' method: "$meta-"package()>.
75

HASH METRICS

77       Hash metrics are metrics that hold key/value pairs. A hash metric is
78       defined using either the "hash_metric()" function, or the
79       "$meta-"add_hash_metric()> method. The following actions are
80       automatically defined for hash metrics:
81
82       $meta->add_METRIC( $key, $value )
83           Add a key/value pair to the metric. Will throw an exception if the
84           metric already has a value for the specified key.
85
86       $value = $meta->get_METRIC( $key )
87           Get the value for a specified key.
88
89       $bool = $meta->has_METRIC( $key )
90           Check that the metric has the specified key defined.
91
92       $meta->clear_METRIC( $key )
93           Clear the specified key/value pair in the metric. (returns nothing)
94
95       $value = $meta->pull_METRIC( $key )
96           Get the value for the specified key, then clear the pair form the
97           metric.
98

LISTS METRICS

100       $meta->push_METRIC( $key, @values )
101           Push values into the specified list for the given metric.
102
103       @values = $meta->get_METRIC( $key )
104           Get the values for a specified key.
105
106       $bool = $meta->has_METRIC( $key )
107           Check that the metric has the specified list.
108
109       $meta->clear_METRIC( $key )
110           Clear the specified list in the metric. (returns nothing)
111
112       @values = $meta->pull_METRIC( $key )
113           Get the values for the specified list in the metric, then clear the
114           list.
115

CLASS METHODS

117       $meta = $class->new( $package, %metrics )
118           Create a new instance of the meta-class, and apply it to $package.
119
120       $metadata = $class->meta_meta()
121           Get the meta data for the meta-class itself. (The meta-class is
122           build using meta-data)
123
124       $new_hashref = $class->gen_hash()
125           Generate a new empty hashref.
126
127       $name = $class->action_method_name( $metric, $action )
128           Generate the name of the method for the given metric and action.
129           Override this if you do not like the METRIC_ACTION() method names.
130

OBJECT METHODS

132       $package = $meta->package()
133           Get the name of the package to which this meta-class applies.
134
135       $meta->set_accessor( $name )
136           Set the accessor that is used to retrieve the meta-object from the
137           class to which it applies.
138
139       $meta->add_hash_metric( $metric, %actions )
140           Add a hash metric (see "HASH METRICS").
141
142           %actions should contain "action =<gt" sub {...}> pairs for
143           constructing actions (See add_action()).
144
145       $meta->add_lists_metric( $metric, %actions )
146           Add a lists metric (see "LISTS METRICS")
147
148           %actions should contain "action =<gt" sub {...}> pairs for
149           constructing actions (See add_action()).
150
151       $meta->add_metric( $metric, \&generator, %actions )
152           Add a custom metric. The second argument should be a sub that
153           generates a default value for the metric.
154
155           %actions should contain "action =<gt" sub {...}> pairs for
156           constructing actions (See add_action()).
157
158       $meta->add_action( $metric, $action => sub { ... } )
159           Add an action for the specified metric. See "ACTION AND HOOK
160           METHODS" for details on how to write an action coderef.
161
162       $meta->hook_before( $metric, $action, sub { ... })
163           Add a hook for the specified metric. See "ACTION AND HOOK METHODS"
164           for details on how to write a hook coderef.
165
166       $meta->hook_after( $metric, $action, sub { ... })
167           Add a hook for the specified metric. See "ACTION AND HOOK METHODS"
168           for details on how to write a hook coderef.
169

ACTION AND HOOK METHODS

171           sub {
172               my $self = shift;
173               my ( $data, $metric, $action, @args ) = @_;
174               ...;
175           }
176
177       Action and hook methods are called when someone calls
178       "$meta-<gt"metric_action(...)>. First all before hooks will be called,
179       the action itself, and finally the after hooks will be called. All
180       methods in the chain get the exact same unaltered arguments. Only the
181       main action sub can return anything.
182
183       Arguments are:
184
185       0: $self
186           These are methods, so the first argument is the meta object itself.
187
188       1: $data
189           This is the data structure stored for the metric. This is the same
190           as calling $meta->metric()
191
192       2: $metric
193           Name of the metric
194
195       3: $action
196           Name of the action
197
198       4+: @args
199           Arguments that metric_action() was called with.
200

DEFAULT ACTION METHODS

202       There are the default action methods used by hashmetrics and
203       listsmetrics.
204
205       $meta->default_hash_add( $data, $metric, $action, $item, $value )
206       $value = $meta->default_hash_get( $data, $metric, $action, $item )
207       $bool = $meta->default_hash_has( $data, $metric, $action, $item )
208       $meta->default_hash_clear( $data, $metric, $action, $item )
209       $value = $meta->default_hash_pull( $data, $metric, $action, $item )
210       $meta->default_list_push( $data, $metric, $action, $item, @values )
211       @values = $meta->default_list_get( $data, $metric, $action, $item )
212       $bool = $meta->default_list_has( $data, $metric, $action, $item )
213       $meta->default_list_clear( $data, $metric, $action, $item )
214       @values = $meta->default_list_pull( $data, $metric, $action, $item )
215

AUTHORS

217       Chad Granum exodist7@gmail.com
218

COPYRIGHT

220       Copyright (C) 2010 Chad Granum
221
222       Meta-Builder is free software; Standard perl licence.
223
224       Meta-Builder is distributed in the hope that it will be useful, but
225       WITHOUT ANY WARRANTY; without even the implied warranty of
226       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the license
227       for more details.
228
229
230
231perl v5.32.1                      2021-01-27            Meta::Builder::Base(3)