1Meta(3)               User Contributed Perl Documentation              Meta(3)
2
3
4

NAME

6       perl5i::Meta - The perl5i meta object
7

SYNOPSIS

9           use perl5i;
10
11           my $id      = $object->mo->id;
12           my $class   = $object->mc->class;
13           my $tainted = $object->mo->is_tainted;
14           ...and so on...
15

DESCRIPTION

17       Each object has a meta object which can be used to describe and
18       sometimes alter the object.  This is for things which are common to
19       *all* objects.  For example, "$obj->mc->class" to get the object's
20       class.  "@ISA = $obj->mc->ISA" to get an object's parents.  And so on.
21
22   Why a meta object?
23       Why not just stick these methods in UNIVERSAL?  They'd clash with user-
24       space methods.  For example, if an existing class has its own "id()"
25       method it would likely clash with what our "id()" method does.  You
26       want to guarantee that every object responds to these meta methods the
27       same way so there's no second-guessing.
28
29   Meta Instance vs Meta Class
30       Each object has a meta object for their instance, accessible with
31       "$obj->mo" and also a meta object for their class, accessible with
32       "$obj->mc".  The meta instance can do most everything the meta class
33       can, mc is provided mostly for disambiguation.
34
35       The problem is this:
36
37           my $thing = "Foo";
38           say $thing->mo->class;
39
40       In perl5i, everything is an object.  Do you want the class of $thing or
41       do you want to treat $thing as a class name?  Its ambiguous.  So to
42       disambiguate, use "$thing->mc" when you mean $thing to be a class name
43       and "$thing->mo" when you mean it to be an object.
44
45       For example, when writing a method which could be a class or could be
46       an object be sure to use "$proto->mc->class" to get the class name.
47
48           sub my_method {
49               my $proto = shift;  # could be an object, could be a class name
50               my $class = $proto->mc->class;
51               ....
52           }
53

METHODS

55       id
56
57           my $id = $object->mo->id;
58
59       Returns an identifier for $object.
60
61       The identifier is guaranteed to be:
62
63         * unique to the object for the life of the process
64         * a true value
65         * independent of changes to the object's contents
66
67       class
68
69           my $class = $object->mo->class;
70           my $class = $class->mc->class;
71
72       Returns the class of the $object or $class.
73
74       ISA
75
76           my @ISA = $object->mo->ISA;
77           my @ISA = $class->mc->ISA;
78
79       Returns the immediate parents of the $class or $object.
80
81       Essentially equivalent to:
82
83           no strict 'refs';
84           my @ISA = @{$class.'::ISA'};
85
86       linear_isa
87
88           my @isa = $class->mc->linear_isa();
89           my @isa = $object->mo->linear_isa();
90
91       Returns the entire inheritance tree of the $class or $object as a list
92       in the order it will be searched for method inheritance.
93
94       This list includes the $class itself and includes UNIVERSAL.  For
95       example:
96
97           package Child;
98           use parent qw(Parent);
99
100           # Child, Parent, UNIVERSAL
101           my @isa = Child->mo->linear_isa();
102
103       methods
104
105           my @methods = $class->mc->methods;
106           my $methods = $class->mc->methods;
107           my @methods = $object->mo->methods;
108           my $methods = $object->mo->methods;
109
110           my $methods = $object->mo->methods({
111               with_UNIVERSAL  => 0,
112               just_mine       => 1,
113           });
114
115       Returns the methods available to a $class or $object.
116
117       By default it returns all the methods available except those inherited
118       from UNIVERSAL because you usually don't want to know that.
119
120       "with_UNIVERSAL", if true, makes it include methods inherited from
121       UNIVERSAL.  It defaults to false.
122
123       "just_mine", if true, returns only methods defined in the $class.  It
124       defaults to false.
125
126       symbol_table
127
128           my $table = $class->mc->symbol_table;
129           my $table = $obj->mo->symbol_table;
130
131       Returns the symbol table for the given $class or class of the $object.
132
133       If you don't know what a symbol table is... good.  If you really want
134       to know, see "Typeglobs and FileHandles" in perldata.
135
136       super
137
138           my @return = $class->mc->super(@args);
139           my @return = $object->mo->super(@args);
140
141       Call the parent of $class/$object's implementation of the current
142       method.
143
144       Equivalent to "$object->SUPER::method(@args)" but based on the class of
145       the $object rather than the class in which the current method was
146       declared.
147
148       is_tainted
149
150           my $is_tainted = $object->mo->is_tainted;
151
152       Returns true if the $object is tainted.
153
154       Only scalars can be tainted, so objects generally return false.
155
156       String and numerically overloaded objects will check against their
157       overloaded versions.
158
159       taint
160
161           $object->mo->taint;
162
163       Taints the $object.
164
165       Normally only scalars can be tainted, this will throw an exception on
166       anything else.
167
168       Tainted, string overloaded objects will cause this to be a no-op.
169
170       An object can override this method if they have a means of tainting
171       themselves.  Generally this is applicable to string or numeric
172       overloaded objects who can taint their overloaded value.
173
174       untaint
175
176           $object->mo->untaint;
177
178       Untaints the $object.
179
180       Normally objects cannot be tainted, so it is a no op on anything but a
181       scalar.
182
183       Tainted, string overloaded objects will throw an exception.
184
185       An object can override this method if they have a means of untainting
186       themselves.  Generally this is applicable to string or numeric
187       overloaded objects who can untaint their overloaded value.
188
189       reftype
190
191           my $reftype = $object->mo->reftype;
192
193       Returns the underlying reference type of the $object.
194
195       checksum
196
197           my $checksum = $object->mo->checksum;
198           my $md5    = $object->mo->checksum( algorithm => 'md5' );
199           my $base64 = $object->mo->checksum( format => 'base64' );
200
201       Get a digest of the object's contents, taking its class into account.
202
203       Two different objects can have the same checksum if their contents are
204       identical. Likewise, a single object can have different checksums
205       throughout its life cycle if it's mutable. This means its checksum will
206       change if its internal state changes.
207
208       For example,
209
210           $obj->mo->checksum( format => 'base64', algorithm => 'md5' );
211
212       options
213
214       algorithm
215           The checksum algorithm.  Can be "sha1" and "md5".
216
217           Defaults to sha1.
218
219       format
220           The character set of the checksum, can be "hex", "base64", or
221           "binary".
222
223           Defaults to hex.
224
225       is_equal
226
227           $object->mo->is_equal($other_object)
228
229       Assess whether something is equal to something else, recurring over
230       deep data structures and treating overloaded objects as numbers or
231       strings when appropriate.
232
233       Examples:
234
235           my $prices = { chair => 50, table => 300 };
236           my $other  = { chair => 50, table => [250, 255] };
237
238           say "They are equal" if $prices->mo->is_equal($other);
239
240
241           my $uri = URI->new("http://www.perl.org");
242           $uri->mo->is_equal("http://www.perl.org") # True
243
244       perl
245
246       Same as as_perl.  For backwards compatibility.
247
248       as_perl
249
250           my $dump = $object->mo->as_perl;
251
252       Dumps the contents of the $object as Perl in a string, like
253       Data::Dumper.
254
255       as_json
256
257           my $json = $object->mo->as_json;
258
259       Return the contents of the $object as JSON.
260
261       as_yaml
262
263           my $json = $object->mo->as_yaml;
264
265       Return the contents of the $object as YAML.
266
267       dump
268
269           my $dump = $object->mo->dump( format => $format );
270
271       Dumps the contents of the $object as a string in whatever format you
272       like.
273
274       Possible formats are yaml, json and perl.
275
276       $format defaults to "perl" which is equivalent to "$object->mo->perl".
277
278       This is simply the long form of "as_perl", "as_json" and "as_yaml".
279
280
281
282perl v5.30.0                      2019-07-26                           Meta(3)