1Object::Pad::MetaFunctiUosnesr(3C)ontributed Perl DocumeOnbtjaetcito:n:Pad::MetaFunctions(3)
2
3
4

NAME

6       "Object::Pad::MetaFunctions" - utility functions for "Object::Pad"
7       classes
8

SYNOPSIS

10          use v5.36;
11          use Object::Pad::MetaFunctions qw( deconstruct_object );
12
13          sub debug_print_object ( $obj )
14          {
15             my ( $classname, @repr ) = deconstruct_object( $obj );
16
17             say "An object of type $classname having:";
18
19             foreach my ( $fieldname, $value ) ( @repr ) {
20                printf "%30s = %s\n", $fieldname, $value;
21             }
22          }
23

DESCRIPTION

25       This module contains a number of miscellaneous utility functions for
26       working with Object::Pad-based classes or instances thereof.
27
28       These functions all involve a certain amount of encapsulation-breaking
29       into the object instances being operated on. This sort of thing
30       shouldn't be encouraged in most regular code, but there can be
31       occasions when it is useful; such as debug printing of values, generic
32       serialisation, or tightly-coupled unit tests that wish to operate on
33       the interals of the object instances they test.
34
35       Therefore, use of these functions should be considered "last-resort".
36       Consider carefully the sorts of things you are trying to do with them,
37       and whether this kind of reaching into the internals of an object,
38       bypassing all of its interface encapsulation, is really the best
39       technique to achieve your goal.
40

FUNCTIONS

42   metaclass
43          $metaclass = metaclass( $obj )
44
45       Since version 0.67.
46
47       Returns the Object::Pad::MOP::Class metaclass associated with the class
48       that the object is an instance of.
49
50   deconstruct_object
51          ( $classname, @repr ) = deconstruct_object( $obj )
52
53       Since version 0.67.
54
55       Returns a list of perl values containing a representation of all the
56       fields in the object instance. This representation form may be useful
57       for tasks such as debug printing or serialisation of the instance. This
58       list is prefixed by the name of the class of instance as a plain
59       string.
60
61       The exact form of this representation is still experimental and may
62       change in a later version. Currently, it takes the form of an even-
63       sized list of key/value pairs, associating field names with their
64       values. Each key gives the name of a component class and the full name
65       of the field within it, separated by a dot (".").
66
67          'CLASSNAME.$FIELD1' => VALUE, 'CLASSNAME.@FIELD2' => VALUE, ...
68
69       In the case of scalar fields, the value is the actual value of that
70       field. In the case of array or hash fields, the value in the repr list
71       is a reference to an anonymous copy of the value stored in the field.
72
73          'CLASSNAME.$SCALARFIELD' => $VALUE,
74          'CLASSNAME.@ARRAYFIELD'  => [ @VALUE ],
75          'CLASSNAME.%HASHFIELD'   => { %VALUE },
76
77       The pairs are ordered, with the actual object class type first,
78       followed by any roles added by that class, then each parent class
79       recursively. Within each component class, the fields are given in
80       declared order.
81
82       This reliable ordering may be useful when printing values in human-
83       readable form, or serialising to some stable storage.
84
85   ref_field
86          $fieldref = ref_field( $fieldname, $obj )
87
88       Since version 0.67.
89
90       Returns a reference to the named field storage variable of the given
91       instance object. The $fieldname should be specified as the class name
92       and the field name separated by a dot (".") (as per
93       "deconstruct_object").
94
95       The class name may also be omitted; at which point the first occurance
96       of a field of the given name found in any component class it matched
97       instead.
98
99       If no matching field is found, an exception is thrown.
100
101       Be careful when using this function as it has the ability to expose
102       instance fields in a way that allows them to be modified. For a safer
103       alternative when only read access is required, use "get_field" instead.
104
105   get_field
106          $scalar = get_field( $fieldname, $obj )
107          @array  = get_field( $fieldname, $obj )
108          %hash   = get_field( $fieldname, $obj )
109
110       Since version 0.67.
111
112       Returns the value of the named field of the given instance object.
113       Behaves correctly given context; namely, that when invoked on array or
114       hash fields in scalar context it will return the number of elements or
115       keys, or in list context will return the list of elements or key/value
116       pairs.
117

AUTHOR

119       Paul Evans <leonerd@leonerd.org.uk>
120
121
122
123perl v5.36.1                      2023-05-15     Object::Pad::MetaFunctions(3)
Impressum