.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Object::Pad::MetaFunctions 3pm"
.TH Object::Pad::MetaFunctions 3pm "2023-01-13" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"Object::Pad::MetaFunctions" \- utility functions for "Object::Pad" classes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&   use v5.36;
\&   use Object::Pad::MetaFunctions qw( deconstruct_object );
\&
\&   sub debug_print_object ( $obj )
\&   {
\&      my ( $classname, @repr ) = deconstruct_object( $obj );
\&
\&      say "An object of type $classname having:";
\&
\&      foreach my ( $fieldname, $value ) ( @repr ) {
\&         printf "%30s = %s\en", $fieldname, $value;
\&      }
\&   }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module contains a number of miscellaneous utility functions for working
with Object::Pad\-based classes or instances thereof.
.PP
These functions all involve a certain amount of encapsulation-breaking into
the object instances being operated on. This sort of thing shouldn't be
encouraged in most regular code, but there can be occasions when it is useful;
such as debug printing of values, generic serialisation, or tightly-coupled
unit tests that wish to operate on the interals of the object instances they
test.
.PP
Therefore, use of these functions should be considered \*(L"last-resort\*(R". Consider
carefully the sorts of things you are trying to do with them, and whether this
kind of reaching into the internals of an object, bypassing all of its
interface encapsulation, is really the best technique to achieve your goal.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "metaclass"
.IX Subsection "metaclass"
.Vb 1
\&   $metaclass = metaclass( $obj )
.Ve
.PP
\&\fISince version 0.67.\fR
.PP
Returns the Object::Pad::MOP::Class metaclass associated with the class
that the object is an instance of.
.SS "deconstruct_object"
.IX Subsection "deconstruct_object"
.Vb 1
\&   ( $classname, @repr ) = deconstruct_object( $obj )
.Ve
.PP
\&\fISince version 0.67.\fR
.PP
Returns a list of perl values containing a representation of all the fields in
the object instance. This representation form may be useful for tasks such as
debug printing or serialisation of the instance. This list is prefixed by the
name of the class of instance as a plain string.
.PP
The exact form of this representation is still experimental and may change in
a later version. Currently, it takes the form of an even-sized list of
key/value pairs, associating field names with their values. Each key gives the
name of a component class and the full name of the field within it, separated
by a dot (\f(CW\*(C`.\*(C'\fR).
.PP
.Vb 1
\&   \*(AqCLASSNAME.$FIELD1\*(Aq => VALUE, \*(AqCLASSNAME.@FIELD2\*(Aq => VALUE, ...
.Ve
.PP
In the case of scalar fields, the value is the actual value of that field. In
the case of array or hash fields, the value in the repr list is a reference to
an anonymous \fIcopy of\fR the value stored in the field.
.PP
.Vb 3
\&   \*(AqCLASSNAME.$SCALARFIELD\*(Aq => $VALUE,
\&   \*(AqCLASSNAME.@ARRAYFIELD\*(Aq  => [ @VALUE ],
\&   \*(AqCLASSNAME.%HASHFIELD\*(Aq   => { %VALUE },
.Ve
.PP
The pairs are ordered, with the actual object class type first, followed by
any roles added by that class, then each parent class recursively. Within each
component class, the fields are given in declared order.
.PP
This reliable ordering may be useful when printing values in human-readable
form, or serialising to some stable storage.
.SS "ref_field"
.IX Subsection "ref_field"
.Vb 1
\&   $fieldref = ref_field( $fieldname, $obj )
.Ve
.PP
\&\fISince version 0.67.\fR
.PP
Returns a reference to the named field storage variable of the given instance
object. The \fI\f(CI$fieldname\fI\fR should be specified as the class name and the field
name separated by a dot (\f(CW\*(C`.\*(C'\fR) (as per \*(L"deconstruct_object\*(R").
.PP
The class name may also be omitted; at which point the first occurance of a
field of the given name found in any component class it matched instead.
.PP
If no matching field is found, an exception is thrown.
.PP
Be careful when using this function as it has the ability to expose instance
fields in a way that allows them to be modified. For a safer alternative when
only read access is required, use \*(L"get_field\*(R" instead.
.SS "get_field"
.IX Subsection "get_field"
.Vb 3
\&   $scalar = get_field( $fieldname, $obj )
\&   @array  = get_field( $fieldname, $obj )
\&   %hash   = get_field( $fieldname, $obj )
.Ve
.PP
\&\fISince version 0.67.\fR
.PP
Returns the value of the named field of the given instance object. Behaves
correctly given context; namely, that when invoked on array or hash fields in
scalar context it will return the number of elements or keys, or in list
context will return the list of elements or key/value pairs.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>