.\" 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
.\" ========================================================================
.\"
.IX Title "Hash::AsObject 3pm"
.TH Hash::AsObject 3pm "2022-12-12" "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"
Hash::AsObject \- treat hashes as objects, with arbitrary accessors/mutators
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&    $h = Hash::AsObject\->new;
\&    $h\->foo(123);
\&    print $h\->foo;       # prints 123
\&    print $h\->{\*(Aqfoo\*(Aq};   # prints 123
\&    $h\->{\*(Aqbar\*(Aq}{\*(Aqbaz\*(Aq} = 456;
\&    print $h\->bar\->baz;  # prints 456
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A Hash::AsObject is a blessed hash that provides read-write
access to its elements using accessors.  (Actually, they're both accessors
and mutators.)
.PP
It's designed to act as much like a plain hash as possible; this means, for
example, that you can use methods like \f(CW\*(C`DESTROY\*(C'\fR to get or set hash elements
with that name.  See below for more information.
.SH "METHODS"
.IX Header "METHODS"
The whole point of this module is to provide arbitrary methods.  For the most
part, these are defined at runtime by a specially written \f(CW\*(C`AUTOLOAD\*(C'\fR function.
.PP
In order to behave properly in all cases, however, a number of special methods
and functions must be supported.  Some of these are defined while others are
simply emulated in \s-1AUTOLOAD.\s0
.IP "\fBnew\fR" 4
.IX Item "new"
.Vb 3
\&    $h = Hash::AsObject\->new;
\&    $h = Hash::AsObject\->new(\e%some_hash);
\&    $h = Hash::AsObject\->new(%some_other_hash);
.Ve
.Sp
Create a new Hash::AsObject.
.Sp
If called as an instance method, this accesses a hash element 'new':
.Sp
.Vb 3
\&    $h\->{\*(Aqnew\*(Aq} = 123;
\&    $h\->new;       # 123
\&    $h\->new(456);  # 456
.Ve
.IP "\fBisa\fR" 4
.IX Item "isa"
This method cannot be used to access a hash element 'isa', because
Hash::AsObject doesn't attempt to handle it specially.
.IP "\fBcan\fR" 4
.IX Item "can"
Similarly, this can't be used to access a hash element 'can'.
.IP "\fB\s-1AUTOLOAD\s0\fR" 4
.IX Item "AUTOLOAD"
.Vb 3
\&    $h\->{\*(AqAUTOLOAD\*(Aq} = \*(Aqabc\*(Aq;
\&    $h\->AUTOLOAD;       # \*(Aqabc\*(Aq
\&    $h\->AUTOLOAD(\*(Aqxyz\*(Aq) # \*(Aqxyz\*(Aq
.Ve
.Sp
Hash::AsObject::AUTOLOAD recognizes when \s-1AUTOLOAD\s0 is begin called as an
instance method, and treats this as an attempt to get or set the '\s-1AUTOLOAD\s0'
hash element.
.IP "\fB\s-1DESTROY\s0\fR" 4
.IX Item "DESTROY"
.Vb 3
\&    $h\->{\*(AqDESTROY\*(Aq} = [];
\&    $h\->DESTROY;    # []
\&    $h\->DESTROY({}) # {}
.Ve
.Sp
\&\f(CW\*(C`DESTROY\*(C'\fR is called automatically by the Perl runtime when an object goes out
of scope.  A Hash::AsObject can't distinguish this from a call to access the
element \f(CW$h\fR\->{'\s-1DESTROY\s0'}, and so it blithely gets (or sets) the hash's '\s-1DESTROY\s0'
element; this isn't a problem, since the Perl interpreter discards any value
that \s-1DESTROY\s0 returns when called automatically.
.IP "\fB\s-1VERSION\s0\fR" 4
.IX Item "VERSION"
When called as a class method, this returns \f(CW$Hash::AsObject::VERSION\fR; when
called as an instance method, it gets or sets the hash element '\s-1VERSION\s0';
.IP "\fBimport\fR" 4
.IX Item "import"
Since Hash::AsObject doesn't export any symbols, this method
has no special significance and you can safely call it as a method to get or
set an 'import' element.
.Sp
When called as a class method, nothing happens.
.PP
The methods \f(CW\*(C`can()\*(C'\fR and \f(CW\*(C`isa()\*(C'\fR are special, because they're defined in the
\&\f(CW\*(C`UNIVERSAL\*(C'\fR class that all packages automatically inherit from.  Unfortunately,
this means that you can't use Hash::AsObject to access elements
\&'can' and 'isa'.
.SH "CAVEATS"
.IX Header "CAVEATS"
No distinction is made between non-existent elements and those that are
present but undefined.  Furthermore, there's no way to delete an
element without resorting to \f(CW\*(C`delete $h\->{\*(Aqfoo\*(Aq}\*(C'\fR.
.PP
Storing a hash directly into an element of a Hash::AsObject
instance has the effect of blessing that hash into
Hash::AsObject.
.PP
For example, the following code:
.PP
.Vb 5
\&    my $h = Hash::AsObject\->new;
\&    my $foo = { \*(Aqbar\*(Aq => 1, \*(Aqbaz\*(Aq => 2 };
\&    print ref($foo), "\en";
\&    $h\->foo($foo);
\&    print ref($foo), "\en";
.Ve
.PP
Produces the following output:
.PP
.Vb 2
\&    HASH
\&    Hash::AsObject
.Ve
.PP
I could fix this, but then code like the following would throw an exception,
because \f(CW\*(C`$h\->foo($foo)\*(C'\fR will return a plain hash reference, not
an object:
.PP
.Vb 1
\&    $h\->foo($foo)\->bar;
.Ve
.PP
Well, I can make \f(CW\*(C`$h\->foo($foo)\->bar\*(C'\fR work, but then code like
this won't have the desired effect:
.PP
.Vb 5
\&    my $foo = { \*(Aqbar\*(Aq => 123 };
\&    $h\->foo($foo);
\&    $h\->foo\->bar(456);
\&    print $foo\->{\*(Aqbar\*(Aq};  # prints 123
\&    print $h\->foo\->bar;   # prints 456
.Ve
.PP
I suppose I could fix \fIthat\fR, but that's an awful lot of work for little
apparent benefit.
.PP
Let me know if you have any thoughts on this.
.SH "BUGS"
.IX Header "BUGS"
Autovivification is probably not emulated correctly.
.PP
The blessing of hashes stored in a Hash::AsObject might be
considered a bug.  Or a feature; it depends on your point of view.
.SH "TO DO"
.IX Header "TO DO"
.IP "\(bu" 4
Add the capability to delete elements, perhaps like this:
.Sp
.Vb 3
\&    use Hash::AsObject \*(Aqdeleter\*(Aq => \*(Aqkill\*(Aq;
\&    $h = Hash::AsObject\->new({\*(Aqone\*(Aq => 1, \*(Aqtwo\*(Aq => 2});
\&    kill $h, \*(Aqone\*(Aq;
.Ve
.Sp
That might seem to violate the prohibition against exporting functions
from object-oriented packages, but then technically it wouldn't be
exporting it \fBfrom\fR anywhere since the function would be constructed
by hand.  Alternatively, it could work like this:
.Sp
.Vb 3
\&    use Hash::AsObject \*(Aqdeleter\*(Aq => \*(Aqkill\*(Aq;
\&    $h = Hash::AsObject\->new({\*(Aqone\*(Aq => 1, \*(Aqtwo\*(Aq => 2});
\&    $h\->kill(\*(Aqone\*(Aq);
.Ve
.Sp
But, again, what if the hash contained an element named 'kill'?
.IP "\(bu" 4
Define multiple classes in \f(CW\*(C`Hash/AsObject.pm\*(C'\fR?  For example, there
could be one package for read-only access to a hash, one for hashes
that throw exceptions when accessors for non-existent keys are called,
etc.  But this is hard to do fully without (a) altering the underlying
hash, or (b) defining methods besides \s-1AUTOLOAD.\s0 Hmmm...
.SH "VERSION"
.IX Header "VERSION"
0.06
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Hoffman <nkuitse \s-1AT\s0 cpan \s-1DOT\s0 org>
.SH "CREDITS"
.IX Header "CREDITS"
Andy Wardley for Template::Stash, which was my
inspiration.  Writing template code like this:
.PP
.Vb 1
\&    [% foo.bar.baz(qux) %]
.Ve
.PP
Made me yearn to write Perl code like this:
.PP
.Vb 1
\&    foo\->bar\->baz($qux);
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2003\-2007 Paul M. Hoffman. All rights reserved.
.PP
This program is free software; you can redistribute it
and modify it under the same terms as Perl itself.