1Data::AsObject(3)     User Contributed Perl Documentation    Data::AsObject(3)
2
3
4

NAME

6       Data::AsObject - Easy OO access to complex perl data structures
7

VERSION

9       version 0.07
10

SYNOPSIS

12           use Data::AsObject qw(dao);
13
14           my $book = dao {
15               name      => "Programming Perl",
16               authors   => ["Larry Wall", "Tom Christiansen", "Jon Orwant"],
17
18           };
19
20           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

DESCRIPTION

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

WARNING

34       Version 0.06 of "Data::AsObject" broke backward compatibility with two
35       changes that may break existing scripts.
36
37       ·   Automatic dereferencing in list context is no longer provided. Use
38           the "list" method instead.
39
40       ·   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

BENEFITS

47       These are some of the reasons why you may want to use "Data::AsObject":
48
49       Object-oriented syntax
50           The object-oriented syntax may sometimes be more appropriate than
51           the traditional hashref and arrayref syntax.
52
53       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
58       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
64       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

FUNCTIONS

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
77       Data::AsObject uses Sub::Exporter and allows you to import the "dao"
78       sub in one of three modes:
79
80       strict mode
81               use Data::AsObject dao => { mode => 'strict' };
82
83           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
87       loose mode
88               use Data::AsObject dao => { mode => 'loose' };
89
90           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
94       strict mode
95               use Data::AsObject dao => { mode => 'silent' };
96
97           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

USAGE

102   Working with hashes
103       To access hash elements by key, use the hash key as method name:
104
105           my $data = dao { three => { two => { one => "kaboom" } } };
106           print $data->three->two->one; # kaboom
107
108       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
112           my $data = dao {
113               'xml:lang'     => "EN",
114               'element-name' => "some name",
115           };
116
117           print $data->xml_lang     # "EN"
118           print $data->element_name # "some name"
119
120   Working with arrays
121       To access array items pass the item index as an argument to the hash
122       that contains the array:
123
124           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
132           print $data->en(1) # two
133           print $data->spain(0)->numbers(3); # cuatro
134
135       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
139           my $data = dao [
140               ["one", "two", "three", "four"]
141               ["uno", "dos", "tres", "cuatro"],
142               ["un", "dos", "tres", "quatre"],
143           ];
144
145           print $data->get(2)->get(0); # un
146
147       Arrayrefs have a dereferencing "list" method. For example:
148
149           my $data = dao {
150               spain => [
151                   { name => 'spanish', numbers => ["uno", "dos", "tres", "cuatro"] },
152                   { name => 'catalan', numbers => ["un", "dos", "tres", "quatre"] },
153               ];
154           };
155
156           foreach my $n ( $data->spain->list ) {
157               print $n->name . " ";
158           } # spanish catalan
159
160   Modifying data
161       "Data::AsObject" only provides accessor functions. To modify data,
162       access the respective hash or array element directly:
163
164           my $data = dao {};
165           $data->{one} = "uno";
166           print $data->one # uno
167
168   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
174           use Try::Tiny;
175
176           my $data = dao {
177               uk      => ["one", "two", "three", "four"],
178               spain   => ["uno", "dos", "tres", "cuatro"],
179               germany => ["eins", "zwei", "drei", "vier"].
180           };
181
182           try {
183               my $numbers = $data->bulgaria;
184           } catch {
185               warn "No info about Bulgaria!";
186           };
187
188       See also "can" below.
189
190   "Data::AsObject::Hash" and special methods
191       If $data isa "Data::AsObject::Hash":
192
193       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
198               my $data = dao {
199                   uk      => ["one", "two", "three", "four"],
200                   # ...
201               };
202
203               warn "No info about Bulgaria!" unless $data->can('bulgaria');
204
205       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
210       others special methods
211           All other special methods and functions ("isa", "ref", "DESTROY")
212           should behave as expected.
213

BUGS

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

SEE ALSO

222       ·   Hash::AsObject
223

AUTHOR

225       Peter Shangov <pshangov@yahoo.com>
226
228       This software is copyright (c) 2011 by Peter Shangov.
229
230       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.
232
233
234
235perl v5.28.1                      2011-04-01                 Data::AsObject(3)
Impressum