README
1NAME
2 Hash::Objectify - Create objects from hashes on the fly
3
4VERSION
5 version 0.008
6
7SYNOPSIS
8 use Hash::Objectify;
9
10 # turn a hash reference into an object with accessors
11
12 $object = objectify { foo => 'bar', wibble => 'wobble' };
13 print $object->foo;
14
15 # objectify with a specific class name
16
17 $object = objectify { foo => 'bar' }, "Foo::Response";
18 print ref $object; # "Foo::Response"
19
20DESCRIPTION
21 Hash::Objectify turns a hash reference into a simple object with
22 accessors for each of the keys.
23
24 One application of this module could be to create lightweight response
25 objects without the extra work of setting up an entire response class
26 with the framework of your choice.
27
28 Using Hash::Objectify is slower than accessing the keys of the hash
29 directly, but does provide "typo protection" since a misspelled method
30 is an error.
31
32USAGE
33 By default, the "objectify" function is automatically exported.
34
35 objectify
36 $object = objectify $hashref
37 $object = objectify $hashref, $classname;
38
39 $object->$key; # accessor
40 $object->$key($value); # mutator
41
42 The "objectify" function copies the hash reference (shallow copy), and
43 blesses it into the given classname. If no classname is given, a
44 meaningless, generated package name is used instead. In either case, the
45 object will inherit from the Hash::Objectified class, which generates
46 accessors on demand for any key in the hash.
47
48 As an optimization, a generated classname will be the same for any given
49 "objectify" call if the keys of the input are the same. (This avoids
50 excessive accessor generation.)
51
52 The first time a method is called on the object, an accessor will be
53 dynamically generated if the key exists. If the key does not exist, an
54 exception is thrown. Note: deleting a key *after* calling it as an
55 accessor will not cause subsequent calls to throw an exception; the
56 accessor will merely return undef.
57
58 Objectifying with a "real" classname that does anything other than
59 inherit from Hash::Objectified may lead to surprising behaviors from
60 method name conflict. You probably don't want to do that.
61
62 Objectifying anything other than an unblessed hash reference is an
63 error. This is true even for objects based on blessed hash references,
64 since the correct semantics are not universally obvious. If you really
65 want Hash::Objectify for access to the keys of a blessed hash, you
66 should make an explicit, shallow copy:
67
68 my $copy = objectify {%$object};
69
70 objectify_lax
71 $object = objectify_lax { foo => 'bar' };
72 $object->quux; # not fatal
73
74 This works just like "objectify", except that non-existing keys return
75 "undef" instead of throwing exceptions. Non-existing keys will still
76 return "undef" if checked with "can".
77
78 WARNING: having an object that doesn't throw on unknown methods violates
79 object-oriented behavior expectations so is generally a bad idea. If you
80 really feel you need this, be aware that the safety guard is removed and
81 you might lose a finger.
82
83 If called with an existing non-lax objectified package name, the
84 behavior of accessors not yet called with change to become lax. You
85 probably don't want to do that.
86
87CAVEATS
88 If an objectified hashref contains keys that conflict with existing
89 resolvable methods (e.g. "can", "AUTOLOAD", "DESTROY"), you won't be
90 able to access those keys via a method as the existing methods take
91 precedence.
92
93 Specifying custom package names or manipulating @ISA for objectified
94 packages (including subclassing) is likely to lead to surprising
95 behavior. It is not recommended and is not supported. If it breaks, you
96 get to keep the pieces.
97
98SUPPORT
99 Bugs / Feature Requests
100 Please report any bugs or feature requests through the issue tracker at
101 <https://github.com/dagolden/Hash-Objectify/issues>. You will be
102 notified automatically of any progress on your issue.
103
104 Source Code
105 This is open source software. The code repository is available for
106 public review and contribution under the terms of the license.
107
108 <https://github.com/dagolden/Hash-Objectify>
109
110 git clone https://github.com/dagolden/Hash-Objectify.git
111
112AUTHOR
113 David Golden <dagolden@cpan.org>
114
115COPYRIGHT AND LICENSE
116 This software is Copyright (c) 2012 by David Golden.
117
118 This is free software, licensed under:
119
120 The Apache License, Version 2.0, January 2004
121
122