.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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 "Meta 3pm"
.TH Meta 3pm "2014-09-14" "perl v5.20.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"
perl5i::Meta \- The perl5i meta object
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use perl5i;
\&
\&    my $id      = $object\->mo\->id;
\&    my $class   = $object\->mc\->class;
\&    my $tainted = $object\->mo\->is_tainted;
\&    ...and so on...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Each object has a meta object which can be used to describe and
sometimes alter the object.  This is for things which are common to
*all* objects.  For example, \f(CW\*(C`$obj\->mc\->class\*(C'\fR to get the
object's class.  \f(CW\*(C`@ISA = $obj\->mc\->ISA\*(C'\fR to get an object's
parents.  And so on.
.SS "Why a meta object?"
.IX Subsection "Why a meta object?"
Why not just stick these methods in \s-1UNIVERSAL\s0?  They'd clash with
user-space methods.  For example, if an existing class has its own
\&\f(CW\*(C`id()\*(C'\fR method it would likely clash with what our \f(CW\*(C`id()\*(C'\fR method
does.  You want to guarantee that every object responds to these meta
methods the same way so there's no second-guessing.
.SS "Meta Instance vs Meta Class"
.IX Subsection "Meta Instance vs Meta Class"
Each object has a meta object for their instance, accessible with \f(CW\*(C`$obj\->mo\*(C'\fR and also a meta object for their class, accessible with
\&\f(CW\*(C`$obj\->mc\*(C'\fR.  The meta instance can do most everything the meta
class can, mc is provided mostly for disambiguation.
.PP
The problem is this:
.PP
.Vb 2
\&    my $thing = "Foo";
\&    say $thing\->mo\->class;
.Ve
.PP
In perl5i, everything is an object.  Do you want the class of \f(CW$thing\fR
or do you want to treat \f(CW$thing\fR as a class name?  Its ambiguous.  So to
disambiguate, use \f(CW\*(C`$thing\->mc\*(C'\fR when you mean \f(CW$thing\fR to be a class
name and \f(CW\*(C`$thing\->mo\*(C'\fR when you mean it to be an object.
.PP
For example, when writing a method which could be a class or could be
an object be sure to use \f(CW\*(C`$proto\->mc\->class\*(C'\fR to get the class
name.
.PP
.Vb 5
\&    sub my_method {
\&        my $proto = shift;  # could be an object, could be a class name
\&        my $class = $proto\->mc\->class;
\&        ....
\&    }
.Ve
.SH "METHODS"
.IX Header "METHODS"
\fIid\fR
.IX Subsection "id"
.PP
.Vb 1
\&    my $id = $object\->mo\->id;
.Ve
.PP
Returns an identifer for \f(CW$object\fR.
.PP
The identifier is guaranteed to be:
.PP
.Vb 3
\&  * unique to the object for the life of the process
\&  * a true value
\&  * independent of changes to the object\*(Aqs contents
.Ve
.PP
\fIclass\fR
.IX Subsection "class"
.PP
.Vb 2
\&    my $class = $object\->mo\->class;
\&    my $class = $class\->mc\->class;
.Ve
.PP
Returns the class of the \f(CW$object\fR or \f(CW$class\fR.
.PP
\fI\s-1ISA\s0\fR
.IX Subsection "ISA"
.PP
.Vb 2
\&    my @ISA = $object\->mo\->ISA;
\&    my @ISA = $class\->mc\->ISA;
.Ve
.PP
Returns the immediate parents of the \f(CW$class\fR or \f(CW$object\fR.
.PP
Essentially equivalent to:
.PP
.Vb 2
\&    no strict \*(Aqrefs\*(Aq;
\&    my @ISA = @{$class.\*(Aq::ISA\*(Aq};
.Ve
.PP
\fIlinear_isa\fR
.IX Subsection "linear_isa"
.PP
.Vb 2
\&    my @isa = $class\->mc\->linear_isa();
\&    my @isa = $object\->mo\->linear_isa();
.Ve
.PP
Returns the entire inheritance tree of the \f(CW$class\fR or \f(CW$object\fR as a list
in the order it will be searched for method inheritance.
.PP
This list includes the \f(CW$class\fR itself and includes \s-1UNIVERSAL. \s0 For example:
.PP
.Vb 2
\&    package Child;
\&    use parent qw(Parent);
\&
\&    # Child, Parent, UNIVERSAL
\&    my @isa = Child\->mo\->linear_isa();
.Ve
.PP
\fImethods\fR
.IX Subsection "methods"
.PP
.Vb 4
\&    my @methods = $class\->mc\->methods;
\&    my $methods = $class\->mc\->methods;
\&    my @methods = $object\->mo\->methods;
\&    my $methods = $object\->mo\->methods;
\&
\&    my $methods = $object\->mo\->methods({
\&        with_UNIVERSAL  => 0,
\&        just_mine       => 1,
\&    });
.Ve
.PP
Returns the methods available to a \f(CW$class\fR or \f(CW$object\fR.
.PP
By default it returns all the methods available \fBexcept those
inherited from \s-1UNIVERSAL\s0\fR because you usually don't want to know that.
.PP
\&\f(CW\*(C`with_UNIVERSAL\*(C'\fR, if true, makes it include methods inherited from \s-1UNIVERSAL.\s0
It defaults to false.
.PP
\&\f(CW\*(C`just_mine\*(C'\fR, if true, returns only methods defined in the \f(CW$class\fR.
It defaults to false.
.PP
\fIsymbol_table\fR
.IX Subsection "symbol_table"
.PP
.Vb 2
\&    my $table = $class\->mc\->symbol_table;
\&    my $table = $obj\->mo\->symbol_table;
.Ve
.PP
Returns the symbol table for the given \f(CW$class\fR or class of the \f(CW$object\fR.
.PP
If you don't know what a symbol table is... good.  If you really want to
know, see \*(L"Typeglobs and FileHandles\*(R" in perldata.
.PP
\fIsuper\fR
.IX Subsection "super"
.PP
.Vb 2
\&    my @return = $class\->mc\->super(@args);
\&    my @return = $object\->mo\->super(@args);
.Ve
.PP
Call the parent of \f(CW$class\fR/$object's implementation of the current method.
.PP
Equivalent to \f(CW\*(C`$object\->SUPER::method(@args)\*(C'\fR but based on the
class of the \f(CW$object\fR rather than the class in which the current method
was declared.
.PP
\fIis_tainted\fR
.IX Subsection "is_tainted"
.PP
.Vb 1
\&    my $is_tainted = $object\->mo\->is_tainted;
.Ve
.PP
Returns true if the \f(CW$object\fR is tainted.
.PP
Only scalars can be tainted, so objects generally return false.
.PP
String and numerically overloaded objects will check against their
overloaded versions.
.PP
\fItaint\fR
.IX Subsection "taint"
.PP
.Vb 1
\&    $object\->mo\->taint;
.Ve
.PP
Taints the \f(CW$object\fR.
.PP
Normally only scalars can be tainted, this will throw an exception on
anything else.
.PP
Tainted, string overloaded objects will cause this to be a no-op.
.PP
An object can override this method if they have a means of tainting
themselves.  Generally this is applicable to string or numeric
overloaded objects who can taint their overloaded value.
.PP
\fIuntaint\fR
.IX Subsection "untaint"
.PP
.Vb 1
\&    $object\->mo\->untaint;
.Ve
.PP
Untaints the \f(CW$object\fR.
.PP
Normally objects cannot be tainted, so it is a no op on anything but a
scalar.
.PP
Tainted, string overloaded objects will throw an exception.
.PP
An object can override this method if they have a means of untainting
themselves.  Generally this is applicable to string or numeric
overloaded objects who can untaint their overloaded value.
.PP
\fIreftype\fR
.IX Subsection "reftype"
.PP
.Vb 1
\&    my $reftype = $object\->mo\->reftype;
.Ve
.PP
Returns the underlying reference type of the \f(CW$object\fR.
.PP
\fIchecksum\fR
.IX Subsection "checksum"
.PP
.Vb 3
\&    my $checksum = $object\->mo\->checksum;
\&    my $md5    = $object\->mo\->checksum( algorithm => \*(Aqmd5\*(Aq );
\&    my $base64 = $object\->mo\->checksum( format => \*(Aqbase64\*(Aq );
.Ve
.PP
Get a digest of the object's contents, taking its class into account.
.PP
Two different objects can have the same checksum if their contents
are identical. Likewise, a single object can have different checksums
throughout its life cycle if it's mutable. This means its checksum
will change if its internal state changes.
.PP
For example,
.PP
.Vb 1
\&    $obj\->mo\->checksum( format => \*(Aqbase64\*(Aq, algorithm => \*(Aqmd5\*(Aq );
.Ve
.PP
\fIoptions\fR
.IX Subsection "options"
.IP "algorithm" 4
.IX Item "algorithm"
The checksum algorithm.  Can be \f(CW\*(C`sha1\*(C'\fR and \f(CW\*(C`md5\*(C'\fR.
.Sp
Defaults to sha1.
.IP "format" 4
.IX Item "format"
The character set of the checksum, can be \f(CW\*(C`hex\*(C'\fR, \f(CW\*(C`base64\*(C'\fR, or
\&\f(CW\*(C`binary\*(C'\fR.
.Sp
Defaults to hex.
.PP
\fIis_equal\fR
.IX Subsection "is_equal"
.PP
.Vb 1
\&    $object\->mo\->is_equal($other_object)
.Ve
.PP
Assess whether something is equal to something else, recurring over deep
data structures and treating overloaded objects as numbers or strings
when appropriate.
.PP
Examples:
.PP
.Vb 2
\&    my $prices = { chair => 50, table => 300 };
\&    my $other  = { chair => 50, table => [250, 255] };
\&
\&    say "They are equal" if $prices\->mo\->is_equal($other);
\&
\&
\&    my $uri = URI\->new("http://www.perl.org");
\&    $uri\->mo\->is_equal("http://www.perl.org") # True
.Ve
.PP
\fIperl\fR
.IX Subsection "perl"
.PP
Same as as_perl.  For backwards compatibility.
.PP
\fIas_perl\fR
.IX Subsection "as_perl"
.PP
.Vb 1
\&    my $dump = $object\->mo\->as_perl;
.Ve
.PP
Dumps the contents of the \f(CW$object\fR as Perl in a string, like Data::Dumper.
.PP
\fIas_json\fR
.IX Subsection "as_json"
.PP
.Vb 1
\&    my $json = $object\->mo\->as_json;
.Ve
.PP
Return the contents of the \f(CW$object\fR as \s-1JSON.\s0
.PP
\fIas_yaml\fR
.IX Subsection "as_yaml"
.PP
.Vb 1
\&    my $json = $object\->mo\->as_yaml;
.Ve
.PP
Return the contents of the \f(CW$object\fR as \s-1YAML.\s0
.PP
\fIdump\fR
.IX Subsection "dump"
.PP
.Vb 1
\&    my $dump = $object\->mo\->dump( format => $format );
.Ve
.PP
Dumps the contents of the \f(CW$object\fR as a string in whatever format you like.
.PP
Possible formats are yaml, json and perl.
.PP
\&\f(CW$format\fR defaults to \*(L"perl\*(R" which is equivalent to \f(CW\*(C`$object\->mo\->perl\*(C'\fR.
.PP
This is simply the long form of \f(CW\*(C`as_perl\*(C'\fR, \f(CW\*(C`as_json\*(C'\fR and \f(CW\*(C`as_yaml\*(C'\fR.