1Data::AsObject(3) User Contributed Perl Documentation Data::AsObject(3)
2
6 Data::AsObject - Easy OO access to complex perl data structures
7
9 version 0.07
10
12 use Data::AsObject qw(dao);
13 my $book = dao {
15 name => "Programming Perl",
16 authors => ["Larry Wall", "Tom Christiansen", "Jon Orwant"],
17 };
19 print $book->name # prints "Programming Perl"
21 print $book->authors(0) # prints "Larry Wall"
22 my $array_ref = $book->authors # $array_ref is ["Larry Wall", "Tom Christiansen", "Jon Orwant"]
23 my @array = $book->authors->list # @array is ("Larry Wall", "Tom Christiansen", "Jon Orwant")
24 $book->{publisher} = "O'Reilly";
25 print $book->publisher # prints "O'Reilly"
26
28 "Data::AsObject" provides easy object-oriented access to complex and
29 arbitrarily nested perl data structures. It is particularly suitable
30 for working with hash-based representation of XML data, as generated by
31 modules like XML::Complie or XML::TreePP.
32
34 Version 0.06 of "Data::AsObject" broke backward compatibility with two
35 changes that may break existing scripts.
36 • Automatic dereferencing in list context is no longer provided. Use
38 the "list" method instead.
39 • An attempt to access an non-existing hash key by default now dies
41 rather than simply produce a warning. Either explicitly request
42 Data::AsObject not to die on missing hash keys, or use an exception
43 handling mechanism to check if the data you want to access is
44 actually there.
45
47 These are some of the reasons why you may want to use "Data::AsObject":
48 Object-oriented syntax
50 The object-oriented syntax may sometimes be more appropriate than
51 the traditional hashref and arrayref syntax.
52 Protection from misspelled hash key names
54 Since "Data::AsObject" does not preform any autovivification, it
55 protects you from misspelling a hash key when accessing its value
56 (but see also Hash::Util for more robust ways to do that).
57 Easy access to hash keys with non-standard symbols
59 If your hashes contain a lot of keys with dashes or colons, as is
60 often the case with keys representing xml element names,
61 "Data::AsObject" can automatically access such keys by substituting
62 underscores for the non-standard symbols.
63 Easy dereferencing of arrayrefs
65 If you have a lot of arrayrefs in your data structure that often
66 need to be traversed, e.g. with "grep", "map" or "foreach",
67 "Data::AsObject" provides a "list" method on arrayrefs to
68 automatically dereference them.
69
71 "dao"
72 Takes as input one or more hash or array references, and returns one or
73 more objects ("Data::AsObject::Hash" or "Data::AsObject::Array"
74 respectively) that can be used to access the data structures via an
75 object oriented interface.
76 Data::AsObject uses Sub::Exporter and allows you to import the "dao"
78 sub in one of three modes:
79 strict mode
81 use Data::AsObject dao => { mode => 'strict' };
82 In this mode (which is the default) "dao" will produce an object
84 that dies whenever you try to invoke a hash key that does not
85 exist.
86 loose mode
88 use Data::AsObject dao => { mode => 'loose' };
89 In this mode "dao" will produce an object that returns "undef" and
91 issues a warning whenever you try to invoke a hash key that does
92 not exist.
93 strict mode
95 use Data::AsObject dao => { mode => 'silent' };
96 In this mode "dao" will produce an object that returns "undef"
98 whenever you try to invoke a hash key that does not exist, but does
99 not complain.
100
102 Working with hashes
103 To access hash elements by key, use the hash key as method name:
104 my $data = dao { three => { two => { one => "kaboom" } } };
106 print $data->three->two->one; # kaboom
107 If a hash key contains one or more colons or dashes, you can access its
109 value by substituting underscores for the colons or dashes (the
110 underlying hash key name is not modified).
111 my $data = dao {
113 'xml:lang' => "EN",
114 'element-name' => "some name",
115 };
116 print $data->xml_lang # "EN"
118 print $data->element_name # "some name"
119 Working with arrays
121 To access array items pass the item index as an argument to the hash
122 that contains the array:
123 my $data = dao {
125 uk => ["one", "two", "three", "four"],
126 spain => [
127 { name => 'spanish', numbers => ["uno", "dos", "tres", "cuatro"] },
128 { name => 'catalan', numbers => ["un", "dos", "tres", "quatre"] },
129 ];
130 };
131 print $data->en(1) # two
133 print $data->spain(0)->numbers(3); # cuatro
134 Array of array structures are a little bit clumsier to work with. You
136 will need to use the "get" method of "Data::AsObject::Array" and pass
137 it the index of the item you want to access:
138 my $data = dao [
140 ["one", "two", "three", "four"]
141 ["uno", "dos", "tres", "cuatro"],
142 ["un", "dos", "tres", "quatre"],
143 ];
144 print $data->get(2)->get(0); # un
146 Arrayrefs have a dereferencing "list" method. For example:
148 my $data = dao {
150 spain => [
151 { name => 'spanish', numbers => ["uno", "dos", "tres", "cuatro"] },
152 { name => 'catalan', numbers => ["un", "dos", "tres", "quatre"] },
153 ];
154 };
155 foreach my $n ( $data->spain->list ) {
157 print $n->name . " ";
158 } # spanish catalan
159 Modifying data
161 "Data::AsObject" only provides accessor functions. To modify data,
162 access the respective hash or array element directly:
163 my $data = dao {};
165 $data->{one} = "uno";
166 print $data->one # uno
167 Autovivification
169 No autovivification is performed by default (but see FUNCTIONS above).
170 An attempt to access a hash or array element that does not exist will
171 produce a fatal error. Use an exception handling mechanism such as
172 Try::Tiny.
173 use Try::Tiny;
175 my $data = dao {
177 uk => ["one", "two", "three", "four"],
178 spain => ["uno", "dos", "tres", "cuatro"],
179 germany => ["eins", "zwei", "drei", "vier"].
180 };
181 try {
183 my $numbers = $data->bulgaria;
184 } catch {
185 warn "No info about Bulgaria!";
186 };
187 See also "can" below.
189 "Data::AsObject::Hash" and special methods
191 If $data isa "Data::AsObject::Hash":
192 can "$data->can" will return the value of the "$data->{can}" element.
194 "$data->can("some_hash_key")" will properly return "undef" if
195 "some_hash_key" does not exists, or a reference to a sub that
196 returns "$data->{some_hash_key}" otherwise.
197 my $data = dao {
199 uk => ["one", "two", "three", "four"],
200 # ...
201 };
202 warn "No info about Bulgaria!" unless $data->can('bulgaria');
204 VERSION
206 Calling "$data->VERSION" will attempt to return the value of a hash
207 element with a key "VERSION". Use "Data::AsObject->VERSION"
208 instead.
209 others special methods
211 All other special methods and functions ("isa", "ref", "DESTROY")
212 should behave as expected.
213
215 Please report any bugs or feature requests to "bug-data-object at
216 rt.cpan.org", or through the web interface at
217 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-Object>. I will
218 be notified, and then you'll automatically be notified of progress on
219 your bug as I make changes.
220
222 • Hash::AsObject
223
225 Peter Shangov <pshangov@yahoo.com>
226
228 This software is copyright (c) 2011 by Peter Shangov.
229 This is free software; you can redistribute it and/or modify it under
231 the same terms as the Perl 5 programming language system itself.
232perl v5.36.0 2023-01-20 Data::AsObject(3)