1Hash::AutoHash(3) User Contributed Perl Documentation Hash::AutoHash(3)
2
6 Hash::AutoHash - Object-oriented access to real and tied hashes
7
9 Version 1.17
10
12 use Hash::AutoHash;
13 # real hash
15 my $autohash=new Hash::AutoHash name=>'Joe', hobbies=>['hiking','cooking'];
16 # access or change hash elements via methods
18 my $name=$autohash->name; # 'Joe'
19 my $hobbies=$autohash->hobbies; # ['hiking','cooking']
20 $autohash->hobbies(['go','chess']); # hobbies now ['go','chess']
21 # you can also use standard hash notation and functions
23 my($name,$hobbies)=@$autohash{qw(name hobbies)};
24 $autohash->{name}='Moe'; # name now 'Moe'
25 my @values=values %$autohash; # ('Moe',['go','chess'])
26 # tied hash.
28 use Hash::AutoHash qw(autohash_tie);
29 use Tie::Hash::MultiValue; # from CPAN. each hash element is ARRAY
30 my $autohash=autohash_tie Tie::Hash::MultiValue;
31 $autohash->name('Joe');
32 $autohash->hobbies('hiking','cooking');
33 my $name=$autohash->name; # ['Joe']
34 my $hobbies=$autohash->hobbies; # ['hiking','cooking']
35 # real hash via constructor function. analogous to autohash_tied
37 use Hash::AutoHash qw(autohash_hash);
38 my $autohash=autohash_hash name=>'Joe',hobbies=>['hiking','cooking'];
39 my $name=$autohash->name; # 'Joe'
40 my $hobbies=$autohash->hobbies; # ['hiking','cooking']
41 # autohash_set is easy way to set multiple elements at once
43 # it has two forms
44 autohash_set($autohash,name=>'Moe',hobbies=>['go','chess']);
45 autohash_set($autohash,['name','hobbies'],['Moe',['go','chess']]);
46 # alias $autohash to regular hash for more concise hash notation
48 use Hash::AutoHash qw(autohash_alias);
49 my %hash;
50 autohash_alias($autohash,%hash);
51 # access or change hash elements without using ->
52 $hash{name}='Joe'; # changes $autohash and %hash
53 my $name_via_hash=$hash{name}; # 'Joe'
54 my $name_via_autohash=$autohash->name; # 'Joe'
55 # get two elements in one statement
56 my($name,$hobbies)=@hash{qw(name hobbies)};
57 # nested structures work, too, of course
59 my $name=autohash_hash first=>'Joe',last=>'Doe';
60 my $person=autohash_hash name=>$name,hobbies=>['hiking','cooking'];
61 my $first=$person->name->first; # 'Joe'
62
64 This is yet another module that lets you access or change the elements
65 of a hash using methods with the same name as the element's key. It
66 follows in the footsteps of Hash::AsObject, Hash::Inflator,
67 Data::OpenStruct::Deep, Object::AutoAccessor, and probably others. The
68 main difference between this module and its forebears is that it
69 supports tied hashes, in addition to regular hashes. This allows a
70 modular division of labor: this class is generic and treats all hashes
71 the same; any special semantics come from the tied hash.
72 The class has a 'new' method but also supplies several functions for
74 constructing new Hash::AutoHash objects.
75 The constructor functions shown in the SYNOPSIS are all you need for
77 typical uses. autohash_hash creates a new 'real' (ie, not tied)
78 Hash::AutoHash object; autohash_tie creates a new tied Hash::AutoHash
79 object. Once the objects are constructed, the class treats them the
80 same way.
81 You can get the value of a hash element using hash notation or by
83 invoking a method with the same name as the key. For example, the
84 following are equivalent.
85 my $name=$autohash->{name};
87 my $name=$autohash->name;
88 You can also change the value of an element using either notation:
90 $autohash->{name}='Jonathan';
92 $autohash->name('Jonathan');
93 And you can add new elements using either notation:
95 $autohash->{first_name}='Joe';
97 $autohash->last_name('Plumber');
98 CAUTIONS
100 • When using method notation, keys must be syntactically legal method
102 names and cannot include 'funny' characters.
103 • INCOMPATIBLE CHANGE: As of version 1.14, it is no longer possible to
105 use method notation for keys with the same names as methods inherited
106 from UNIVERSAL (the base class of everything). These are 'can',
107 'isa', 'DOES', and 'VERSION'. The reason is that as of Perl 5.9.3,
108 calling UNIVERSAL methods as functions is deprecated and developers
109 are encouraged to use method form instead. Previous versions of
110 AutoHash are incompatible with CPAN modules that adopt this style.
111 Nested structures work straightforwardly. If a value is a
113 Hash::AutoHash object, you can use a series of '->' operators to get to
114 its elements.
115 my $name=autohash_hash first=>'Joe',last=>'Doe';
117 my $person=autohash_hash name=>$name,hobbies=>['hiking','cooking'];
118 my $first=$person->name->first; # $name is 'Joe'
119 The class provides a full plate of functions for performing hash
121 operations on Hash::AutoHash objects. These are useful if you want to
122 avoid hash notation all together. The following example uses these
123 functions to removes hash elements whose values are undefined:
124 use Hash::AutoHash qw(autohash_keys autohash_delete);
126 my @keys=autohash_keys($autohash);
127 for my $key (@keys) {
128 autohash_delete($autohash,$key) unless defined $autohash->$key;
129 }
130 The autohash_set function is an easy way to set multiple elements at
132 once. This is especially handy for setting the initial value of a tied
133 Hash::AutoHash object, in cases where the tied hash cannot do this
134 directly.
135 use Hash::AutoHash qw(autohash_set);
137 my $autohash=autohash_tie Tie::Hash::MultiValue;
138 autohash_set($autohash,name=>'Joe',hobbies=>'hiking',hobbies=>'cooking');
139 In the example above, 'hobbies' is set twice, because that's how
141 Tie::Hash::MultiValue lets you set a multi-valued element. Setting the
142 element to an ARRAY of values doesn't do it.
143 You can also feed autohash_set separate ARRAYs of keys and values.
145 my $autohash=autohash_tie Tie::Hash::MultiValue;
147 autohash_set($autohash,['name','hobbies'],['Joe','hiking']);
148 You can alias the object to a regular hash for more concise hash
150 notation.
151 use Hash::AutoHash qw(autohash_alias);
153 my $autohash=autohash_tie Tie::Hash::MultiValue;
154 autohash_alias($autohash,%hash);
155 $hash{name}='Joe'; # changes both $autohash and %hash
156 $autohash->hobbies('kayaking'); # changes both $autohash and %hash
157 my($name,$hobbies)=@hash{qw(name hobbies)};
158 By aliasing $autohash to %hash, you avoid the need to dereference the
160 variable when using hash notation. Admittedly, this is a minor
161 convenience, but the reduction in verbosity can be useful in some
162 cases.
163 It is also possible to link a Hash::AutoHash object to an existing hash
165 which may be real or tied, a process we call wrapping. The effect is
166 similar to aliasing. The difference is that with aliasing, the object
167 exists first whereas with wrapping, the hash exists first.
168 # wrap existing hash - can be real or tied.
170 use Hash::AutoHash qw(autohash_wrap);
171 my %hash=(name=>'Moe',hobbies=>['running','rowing']);
172 my $autohash=autohash_wrap %hash;
173 my($name,$hobbies)=@hash{qw(name hobbies)};
174 $hash{name}='Joe'; # changes both $autohash and %hash
175 $autohash->hobbies('kayaking'); # changes both $autohash and %hash
176 If the Hash::AutoHash object is tied, the autohash_tied function
178 returns the object implementing the tied hash. If the Hash::AutoHash
179 object is aliased to a hash, the function also works on the hash.
180 autohash_tied is almost equivalent to Perl's built-in tied function;
181 see "Accessing the tied object" for details.
182 use Hash::AutoHash qw(autohash_tied);
184 my $autohash=autohash_tie Tie::Hash::MultiValue;
185 my $tied=autohash_tied($autohash); # Tie::Hash::MultiValue object
186 autohash_alias($autohash,%hash);
187 my $tied=autohash_tied(%hash); # same object as above
188 If you're certain the Hash::AutoHash object is tied, you can invoke
190 methods on the tied object as follows. CAUTION: this will generate an
191 error if the object is not tied.
192 my $result=autohash_tied($autohash)->some_method(@parameters);
194 A safer way is to supply the method name and parameters as additional
196 arguments to the autohash_tied function. This will return undef if the
197 object is not tied.
198 my $result=autohash_tied($autohash,'some_method',@parameters);
200 Keeping the namespace clean
202 Hash::AutoHash provides all of its capabilities through class methods
203 (these are methods, such as 'new', that are invoked on the class rather
204 than on individual objects) or through functions that must be imported
205 into the caller's namespace. In most cases, a method invoked on an
206 object is interpreted as a request to access or change an element of
207 the underlying hash.
208 CAUTION: As of version 1.14, it is not possible to use method notation
210 for keys with the same names as methods inherited from UNIVERSAL (the
211 base class of everything). These are 'can', 'isa', 'DOES', and
212 'VERSION'. The reason is that as of Perl 5.9.3, calling UNIVERSAL
213 methods as functions is deprecated and developers are encouraged to use
214 method form instead. Previous versions of AutoHash are incompatible
215 with CPAN modules that adopt this style.
216 Special care is needed with methods used implicitly by Perl to
218 implement common features ('import', 'AUTOLOAD', 'DESTROY').
219 'import' is usually invoked by Perl as a class method when processing
221 'use' statements to import functions into the caller's namespace. We
222 preserve this behavior but when invoked on an object, we interpret the
223 call as a request to access or change the element of the underlying
224 hash whose kye is 'import'.
225 'AUTOLOAD' and 'DESTROY' pose different problems, since they are
227 logically object methods. Fortunately, Perl leaves enough clues to let
228 us tell whether these methods were called by Perl or directly by the
229 application. When called by Perl, they operate as Perl expects; when
230 called by the application, they access the underlying hash.
231 The 'new' method warrants special mention. In normal use, 'new' is
233 almost always invoked as a class method, eg,
234 new Hash::AutoHash(name=>'Joe')
236 This invokes the 'new' method on Hash::AutoHash which constructs a new
238 object as expected. If, however, 'new' is invoked on an object, eg,
239 $autohash->new
241 the code accesses the hash element named 'new'.
243 Constructors
245 Hash::AutoHash provides a number of constructor functions as well as a
246 'new' method which is simply a front-end for the constructor functions.
247 To use the constructor functions, you must import them into the
248 caller's namespace using the common Perl idiom of listing the desired
249 functions in a 'use' statement.
250 use Hash::AutoHash qw(autohash_hash autohash_tie autohash_wrap autohash_wrapobj
252 autohash_wraptie autohash_new);
253 autohash_hash
255 Title : autohash_hash
257 Usage : $autohash=autohash_hash name=>'Joe',hobbies=>['hiking','cooking']
258 Function: Create a real (ie, not tied) Hash::AutoHash object and
259 optionally set its initial value
260 Returns : Hash::AutoHash object
261 Args : Optional list of key=>value pairs
262 autohash_tie
264 Title : autohash_tie
266 Usage : $autohash=autohash_tie Tie::Hash::MultiValue
267 Function: Create a tied Hash::AutoHash object
268 Returns : Hash::AutoHash object tied to the given class
269 Args : The class implementing the tied hash; quotes are optional. Any
270 additional parameters are passed to the TIEHASH constructor.
271 The object returned by autohash_tie is simultaneously a Hash::AutoHash
273 object and a tied hash. To get the object implementing the tied hash
274 (ie, the object returned by Perl's tie function), do either of the
275 following.
276 my $tied=tied %$autohash; # note '%' before '$'
278 my $tied=autohash_tied($autohash); # note no '%' before '$'
279 The autohash_set function is a convenient way to set the initial value
281 of a tied Hash::AutoHash object in cases where the tied hash cannot do
282 this directly.
283 use Hash::AutoHash qw(autohash_set);
285 my $autohash=autohash_tie Tie::Hash::MultiValue;
286 autohash_set ($autohash,name=>'Joe',hobbies=>'hiking',hobbies=>'cooking');
287 In the example above, 'hobbies' is set twice, because that's how
289 Tie::Hash::MultiValue lets you set a multi-valued element. Setting the
290 element to an ARRAY of values doesn't do it.
291 You can also provide autohash_set with separate ARRAYs of keys and
293 values.
294 my $autohash=autohash_tie Tie::Hash::MultiValue;
296 autohash_set($autohash,['name','hobbies'],['Joe','hiking']);
297 Wrapping an existing hash or tied object
299 The constructor functions described in this section let you create a
301 Hash::AutoHash object that is linked to an existing hash or tied
302 object, a process we call wrapping. Once the linkage is made, the
303 contents of the object and hash will be identical; any changes made to
304 one will be reflected in the other.
305 autohash_wrap
307 Title : autohash_wrap
309 Usage : $autohash=autohash_wrap %hash,name=>'Joe',hobbies=>['hiking','cooking']
310 Function: Create a Hash::AutoHash object linked to the hash. The initial
311 value of the object is whatever value the hash currently has. Any
312 additional parameters are key=>value pairs which are used to set
313 further elements of the object (and hash)
314 Returns : Hash::AutoHash object linked to the hash
315 Args : Hash and optional list of key=>value pairs. The hash can be real or
316 tied. The key=>value pairs set further elements of the object (and
317 hash).
318 Notes : If the hash is tied, the constructed object will be tied to the
319 object implementing the tied hash. If the hash is not tied, the
320 constructed object will be tied to an object of type
321 Hash::AutoHash::dup which implements the linking.
322 autohash_wrapobj
324 Title : autohash_wrapobj
326 Usage : $autohash=autohash_wrapobj $tied_object,name=>'Joe',hobbies=>'hiking'
327 Function: Create a Hash::AutoHash object linked to a tied hash given
328 the object implementing the tie (in other words, the object returned
329 by Perl's tie function). The initial value of the constructed object
330 is whatever value the hash currently has. Any additional parameters
331 are key=>value pairs which are used to set further elements of the
332 object (and hash).
333 Returns : Hash::AutoHash object linked to the hash
334 Args : Object implementing a tied hash and optional list of key=>value
335 pairs. The key=>value pairs set further elements of the object (and
336 hash).
337 Here is another, perhaps more typical, illustration of
339 autohash_wrapobj.
340 $autohash=autohash_wrapobj tie %hash,'Tie::Hash::MultiValue'
342 You can set initial values in the constructed object by including them
344 as parameters to the function, using parentheses to keep them separate
345 from the parameters to 'tie'. All the parentheses in the example below
346 are necessary.
347 $autohash=autohash_wrapobj ((tie %hash,'Tie::Hash::MultiValue'),
349 name=>'Joe',hobbies=>'hiking',hobbies=>'cooking')
350 autohash_wraptie
352 Title : autohash_wraptie
354 Usage : $autohash=autohash_wraptie %hash,Tie::Hash::MultiValue
355 Function: Create a Hash::AutoHash object linked to a tied hash and do
356 the tying in one step.
357 Returns : Hash::AutoHash object linked to the hash. As a side effect,
358 the hash will be tied to the given class.
359 Args : Hash and the class implementing the tied hash (quotes are optional).
360 Any additional parameters are passed to the TIEHASH constructor.
361 Notes : This is equivalent to
362 $autohash=autohash_wrapobj tie %hash,'Tie::Hash::MultiValue'
363 new
365 'new' and autohash_new are front-ends to the other constructor
367 functions. To accommodate the diversity of the other functions, the
368 parameter syntax makes some assumptions and is not completely general.
369 Title : new
371 Usage : $autohash=new Hash::AutoHash
372 name=>'Joe',hobbies=>['hiking','cooking']
373 -- OR --
374 $autohash=new Hash::AutoHash ['Tie::Hash::MultiValue'],
375 name=>'Joe',hobbies=>'hiking',hobbies=>'cooking'
376 -- OR --
377 $autohash=new Hash::AutoHash \%hash,
378 name=>'Joe',hobbies=>'hiking',hobbies=>'cooking'
379 -- OR --
380 $autohash=new Hash::AutoHash $tied_object,
381 name=>'Joe',hobbies=>'hiking',hobbies=>'cooking'
382 -- OR --
383 $autohash=new Hash::AutoHash [\%hash,'Tie::Hash::MultiValue'],
384 name=>'Joe',hobbies=>'hiking',hobbies=>'cooking'
385 Function: Create a Hash::AutoHash object and optionally set elements.
386 Form 1, like autohash_hash, creates a real (ie, not tied) object.
387 Form 2, like autohash_tie, creates a tied object,
388 Form 3, like autohash_wrap, creates an object linked to a hash.
389 Form 4, like autohash_wrapobj, creates an object linked to a tied
390 hash given the object implementing the tie
391 Form 5, like autohash_wraptie, creates an object linked to a tied
392 hash and does the tie in one step
393 Returns : Hash::AutoHash object
394 Args : The first argument determines the form. The remaining arguments are
395 an optional list of key=>value pairs which are used to set elements
396 of the object
397 Form 1. first argument is a scalar (eg, a string)
398 Form 2. first argument is an ARRAY whose elements are the class
399 implementing the tied hash (quotes are required) followed by
400 additional parameters for the the TIEHASH constructor.
401 Form 3. first argument is a HASH that doesn't look like a tied
402 object. See form 4.
403 Form 4. first argument is a HASH that looks like a tied object; this
404 is any blessed HASH that provides a TIEHASH method.
405 Form 5. first argument is an ARRAY whose elements are a HASH and the
406 class implementing the tied hash (quotes are required) followed by
407 additional parameters for the the TIEHASH constructor.
408 autohash_new
410 Like new, autohash_new is a front-end to the other constructor
412 functions. We provide it for stylistic consistency. To accommodate the
413 diversity of the other functions, the parameter syntax makes some
414 assumptions and is not completely general.
415 Title : autohash_new
417 Usage : $autohash=autohash_new name=>'Joe',hobbies=>['hiking','cooking']
418 -- OR --
419 $autohash=autohash_new ['Tie::Hash::MultiValue'],
420 name=>'Joe',hobbies=>'hiking',hobbies=>'cooking'
421 -- OR --
422 $autohash=autohash_new \%hash,
423 name=>'Joe',hobbies=>'hiking',hobbies=>'cooking'
424 -- OR --
425 $autohash=autohash_new $tied_object,
426 name=>'Joe',hobbies=>'hiking',hobbies=>'cooking'
427 -- OR --
428 $autohash=autohash_new [\%hash,'Tie::Hash::MultiValue'],
429 name=>'Joe',hobbies=>'hiking',hobbies=>'cooking'
430 Function: same as 'new'
431 Returns : Hash::AutoHash object
432 Args : same as 'new'
433 Aliasing: autohash_alias
435 You can alias a Hash::AutoHash object to a regular hash to avoid the
436 need to dereference the variable when using hash notation. The effect
437 is similar to wrapping an existing hash via the autohash_wrap function.
438 The difference is that with aliasing, the Hash::AutoHash object exists
439 first and you are linking a hash to it, whereas with wrapping, the hash
440 exists first.
441 Once the linkage is made, the contents of the object and hash will be
443 identical; any changes made to one will be reflected in the other.
444 As a convenience, the autoahash_alias functions can link in either
446 direction depending on whether the given object exists.
447 Title : autohash_alias
449 Usage : autohash_alias($autohash,%hash)
450 Function: If $autohash is defined and is a Hash::AutoHash object, link
451 $autohash to %hash. If $autohash is not defined, create a new
452 Hash::AutoHash object that wraps %hash
453 Args : Hash::AutoHash object or undef and hash
454 Returns : Hash::AutoHash object
455 Getting and setting hash elements
457 One way to get and set hash elements is to treat the object as a HASH
458 and use standard hash notation, eg,
459 my $autohash=autohash_hash name=>'Joe',hobbies=>['hiking','cooking'];
461 my $name=$autohash->{name};
462 my($name,$hobbies)=@$autohash{qw(name hobbies)};
463 $autohash->{name}='Moe';
464 @$autohash{qw(name hobbies)}=('Joe',['running','rowing']);
465 A second approach is to invoke a method with the name of the key. Eg,
467 $autohash->name;
469 $autohash->name('Moe'); # sets name to 'Moe'
470 $autohash->hobbies(['blading','rowing']); # sets hobbies to ['blading','rowing']
471 New hash elements can be added using either notation. For example,
473 $autohash->{first_name}='Joe';
475 $autohash->last_name('Plumber');
476 If the object wraps or aliases a hash, you can operate on the hash
478 instead of the Hash::AutoHash object. This may allow more concise
479 notation by avoiding the need to dereference the object repeatedly.
480 use Hash::AutoHash qw(autohash_alias);
482 autohash_alias($autohash,%hash);
483 my $name=$hash{name}; # instead of $autohash->{name}
484 my @keys=keys %hash; # instead of keys %$autohash
485 The class also provides two functions for wholesale manipulation of
487 arguments. To use these functions, you must import them into the
488 caller's namespace using the common Perl idiom of listing the desired
489 functions in a 'use' statement.
490 use Hash::AutoHash qw(autohash_get autohash_set);
492 autohash_get
494 Title : autohash_get
496 Usage : ($name,$hobbies)=autohash_get($autohash,qw(name hobbies))
497 Function: Get values for multiple keys.
498 Args : Hash::AutoHash object and list of keys
499 Returns : list of argument values
500 autohash_set
502 Title : autohash_set
504 Usage : autohash_set($autohash,name=>'Joe Plumber',first_name=>'Joe')
505 -- OR --
506 autohash_set($autohash,['name','first_name'],['Joe Plumber','Joe'])
507 Function: Set multiple arguments in existing object.
508 Args : Form 1. Hash::AutoHash object and list of key=>value pairs
509 Form 2. Hash::AutoHash object, ARRAY of keys, ARRAY of values
510 Returns : Hash::AutoHash object
511 Functions for hash-like operations
513 These functions provide hash-like operations on Hash::AutoHash objects.
514 These are useful if you want to avoid hash notation all together. To
515 use these functions, you must import them into the caller's namespace
516 using the common Perl idiom of listing the desired functions in a 'use'
517 statement.
518 use Hash::AutoHash
520 qw(autohash_clear autohash_delete autohash_each autohash_exists
521 autohash_keys autohash_values
522 autohash_count autohash_empty autohash_notempty);
523 autohash_clear
525 Title : autohash_clear
527 Usage : autohash_clear($autohash)
528 Function: Delete entire contents of $autohash
529 Args : Hash::AutoHash object
530 Returns : nothing
531 autohash_delete
533 Title : autohash_delete
535 Usage : autohash_delete($autohash,@keys)
536 Function: Delete keys and their values from $autohash.
537 Args : Hash::AutoHash object, list of keys
538 Returns : nothing
539 autohash_exists
541 Title : autohash_exists
543 Usage : if (autohash_exists($autohash,$key)) { ... }
544 Function: Test whether key is present in $autohash.
545 Args : Hash::AutoHash object, key
546 Returns : boolean
547 autohash_each
549 Title : autohash_each
551 Usage : while (my($key,$value)=autohash_each($autohash)) { ... }
552 -- OR --
553 while (my $key=autohash_each($autohash)) { ... }
554 Function: Iterate over all key=>value pairs or all keys present in $autohash
555 Args : Hash::AutoHash object
556 Returns : list context: next key=>value pair in $autohash or empty list at end
557 scalar context: next key in $autohash or undef at end
558 autohash_keys
560 Title : autohash_keys
562 Usage : @keys=autohash_keys($autohash)
563 Function: Get all keys that are present in $autohash
564 Args : Hash::AutoHash object
565 Returns : list of keys
566 autohash_values
568 Title : autohash_values
570 Usage : @values=autohash_values($autohash)
571 Function: Get the values of all keys that are present in $autohash
572 Args : Hash::AutoHash object
573 Returns : list of values
574 autohash_count
576 Title : autohash_count
578 Usage : $count=autohash_count($autohash)
579 Function: Get the number keys that are present in $autohash
580 Args : Hash::AutoHash object
581 Returns : number
582 autohash_empty
584 Title : autohash_empty
586 Usage : if (autohash_empty($autohash)) { ... }
587 Function: Test whether $autohash is empty
588 Args : Hash::AutoHash object
589 Returns : boolean
590 autohash_notempty
592 Title : autohash_notempty
594 Usage : if (autohash_notempty($autohash)) { ... }
595 Function: Test whether $autohash is not empty. Complement of autohash_empty
596 Args : Hash::AutoHash object
597 Returns : boolean
598 Accessing the tied object: autohash_tied
600 If a Hash::AutoHash object is tied, the application sometimes needs to
601 access the object implementing the underlying tied hash. The term
602 'tied object' refers to this object. This is necessary, for example,
603 if the tied object provides options that affect the operation of the
604 tied hash.
605 In many cases, you can access the tied object using Perl's built-in
607 tied function.
608 my $autohash=autohash_tie Tie::Hash::MultiValue;
610 my $tied=tied %$autohash; # note leading '%'
611 However Perl's built-in tied function doesn't do the right thing when
613 the Hash::AutoHash object wraps or is aliased to a regular (not tied)
614 hash. In these cases, the code uses an internal tied hash to implement
615 the connection between the Hash::AutoHash object and the hash. (The
616 internal tied hash is currently named Hash::AutoHash::alias, but this
617 is subject to change).
618 The autohash_tied function is a safer way to get the tied object. In
620 most cases, it is equivalent to Perl's built-in tied function, but it
621 reaches through the internal Hash::AutoHash::alias object when one is
622 present.
623 If the Hash::AutoHash object is aliased to a hash, the function also
625 works on the hash.
626 use Hash::AutoHash qw(autohash_tied);
628 my $autohash=autohash_tie Tie::Hash::MultiValue;
629 my $tied=autohash_tied($autohash); # Tie::Hash::MultiValue object
630 autohash_alias($autohash,%hash);
631 my $tied=autohash_tied(%hash); # same object as above
632 If you're certain the Hash::AutoHash object is tied, you can invoke
634 methods on the result of autohash_tied. This will generate an error if
635 the object is not tied. A safer way is to supply the method name and
636 parameters as additional arguments to the autohash_tied function. This
637 will return undef if the object is not tied.
638 # two ways to invoke method on tied object
640 # 1st generates error if $autohash not tied
641 # 2nd returns undef if $autohash not tied
642 my $result=autohash_tied($autohash)->some_method(@parameters);
643 my $result=autohash_tied($autohash,'some_method',@parameters);
644 use Hash::AutoHash qw(autohash_tied);
646 Title : autohash_tied
648 Usage : $tied=autohash_tied($autohash)
649 -- OR --
650 $tied=autohash_tied(%hash)
651 -- OR --
652 $result=autohash_tied($autohash,'some_method',@parameters)
653 -- OR --
654 $result=autohash_tied(%hash,'some_method',@parameters)
655 Function: The first two forms return the object implementing the tied hash that
656 underlies a Hash::AutoHash object if it is tied, or undef if it isn't
657 tied. The latter two forms invoke a method on the tied object if the
658 Hash::AutoHash object is tied, or undef if it isn't tied.
659 In forms 1 and 3, the first argument is the Hash::AutoHash object.
660 In forms 2 and 4, the first argument is a hash to which a
661 Hash::AutoHash object has been aliased
662 Returns : In forms 1 and 2, object implementing tied hash or undef.
663 In forms 3 and 4, result of invoking method (which can be anything or
664 nothing), or undef.
665 Args : Form 1. Hash::AutoHash object
666 Form 2. hash to which Hash::AutoHash object is aliased
667 Form 3. Hash::AutoHash object, method name, optional list of
668 parameters for method
669 Form 4. hash to which Hash::AutoHash object is aliased, method name,
670 optional list of parameters for method
671 Subclassing
673 Special considerations apply when subclassing Hash::AutoHash due to its
674 goal of keeping the namespace clean and its heavy use of functions
675 instead of methods.
676 A common use-case is a subclass that provides an object interface to a
678 specific tied hash class. In such cases, the subclass would probably
679 provide a 'new' method that constructs objects tied to that class and
680 would probably want to hide the other constructor functions. The
681 subclass might also want to provide the other functions from
682 Hash::AutoHash (why not?) but might want to change their names to be
683 consistent with the subclass's name.
684 Here is an example subclass, TypicalChild, illustrating this use-case.
686 TypicalChild provides a 'new' method that creates objects tied to
687 Tie::Hash::MultiValue. The 'new' method can also set the object's
688 initial value (the TIEHASH method of Tie::Hash::MultiValue does not
689 support this directly). The subclass provides the other functions from
690 Hash::AutoHash but renames each from autohash_XXX to typicalchild_XXX.
691 package TypicalChild;
693 use Hash::AutoHash;
694 our @ISA=qw(Hash::AutoHash);
695 our @NORMAL_EXPORT_OK=();
696 our %RENAME_EXPORT_OK=();
697 our @RENAME_EXPORT_OK=sub {s/^autohash/typicalchild/; $_};
698 our @EXPORT_OK=TypicalChild::helper->EXPORT_OK;
699 our @SUBCLASS_EXPORT_OK=TypicalChild::helper->SUBCLASS_EXPORT_OK;
700 #############################################################
702 # helper package to avoid polluting TypicalChild namespace
703 #############################################################
704 package TypicalChild::helper;
705 use Hash::AutoHash qw(autohash_tie autohash_set);
706 use Tie::Hash::MultiValue;
707 BEGIN {
708 our @ISA=qw(Hash::AutoHash::helper);
709 }
710 sub _new {
711 my($helper_class,$class,@args)=@_;
712 my $self=autohash_tie Tie::Hash::MultiValue;
713 autohash_set($self,@args);
714 bless $self,$class;
715 }
716 1;
717 The subclass consists of two packages: TypicalChild and
719 TypicalChild::helper. The helper package is where all the real code
720 goes to avoid polluting TypicalChild's namespace. TypicalChild must be
721 a subclass of Hash::AutoHash (ie, Hash::AutoHash must be in its @ISA
722 array); TypicalChild::helper must be a subclass of
723 Hash::AutoHash::helper (ie, Hash::AutoHash::helper must be in its @ISA
724 array).
725 The 'new' method of Hash::AutoHash dispatches to the '_new' method in
727 the helper class after making sure the method was invoked on a class.
728 That's why the code has a '_new' method in TypicalChild::helper rather
729 than 'new' method in TypicalChild.
730 The BEGIN block is needed to make sure @ISA is set at compile-time
732 before @EXPORT_OK is calculated.
733 The code in TypicalChild dealing with the various EXPORT_OK arrays
735 handles the renaming of functions from Hash::AutoHash (or, more
736 generally, any ancestor class), the exporting of additional functions
737 defined by the subclass, and sets the stage for subclasses of the
738 subclass to do the same thing.
739 Variable: @NORMAL_EXPORT_OK
741 Usage : @NORMAL_EXPORT_OK=qw(autohash_set typicalchild_function)
742 Function: Functions that will be exported 'normally', in other words with no
743 change of name. The functions can be defined here (in the helper
744 class, not the main class!!) or in any ancestor class
745 Variable: %NORMAL_EXPORT_OK
747 Usage : %NORMAL_EXPORT_OK=(learn=>'autohash_set',forget=>'autohash_delete')
748 Function: Functions that will be exported with a different name. The left-hand
749 side of each pair is the new name; the right-hand side is the name of
750 a function defined here (in the helper class, not the main class!!)
751 or in any ancestor class
752 Variable: @RENAME_EXPORT_OK
754 Usage : @RENAME_EXPORT_OK=sub {s/^autohash/typicalchild/; $_}
755 -- OR --
756 @RENAME_EXPORT_OK=(sub {s/^autohash/typicalchild/; $_},
757 qw(autohash_exists autohash_get))
758 Function: Functions that will be exported with a different name. This provides
759 an easy way to rename many functions at once. The first element of
760 the list is a subroutine that will be applied to each other element
761 of the list to generate the new names. The functions in the list can
762 be defined here (in the helper class, not the main class!!) or in any
763 ancestor class
764 If the list of functions is empty, the subroutine is applied to
766 everything in its parent classes' @SUBCLASS_EXPORT_OK array.
767 The form of the subroutine is exactly as for Perl's grep and map
769 functions.
770 Variable: @EXPORT_OK
772 Usage : @EXPORT_OK=TypicalChild::helper->EXPORT_OK
773 -- OR --
774 @EXPORT_OK=qw(learn forget)
775 Function: Complete list of functions that the subclass is willing to export.
776 The EXPORT_OK method computes this from the other variables. You can
777 also set it explicitly.
778 Variable: @SUBCLASS_EXPORT_OK
780 Usage : @SUBCLASS_EXPORT_OK=TypicalChild::helper->SUBCLASS_EXPORT_OK
781 -- OR --
782 @SUBCLASS_EXPORT_OK=qw(learn forget)
783 Function: Functions that subclasses of this class might want to export. This
784 provides the default list of functions for @RENAME_EXPORT_OK in these
785 subclasses. The SUBCLASS_EXPORT_OK method simply sets this to
786 @EXPORT_OK which is tantamount to assuming that subclasses may want
787 to export everything this class exports. You can also set it
788 explicitly.
789
791 perltie and Tie::Hash present background on tied hashes.
792 Hash::AsObject, Hash::Inflator, Data::OpenStruct::Deep, and
794 Object::AutoAccessor are similar classes and may be better choices if
795 you don't need or want to used tied hashes. The source code of
796 Hash::AsObject alerted us to the danger of methods inherited from
797 UNIVERSAL.
798 Hash::AutoHash::Args, Hash::AutoHash::MultiValued,
800 Hash::AutoHash::AVPairsSingle, Hash::AutoHash::AVPairsMulti,
801 Hash::AutoHash::Record are subclasses each of which provides an object
802 interface to a specific tied hash class.
803 Tie::Hash::MultiValue is a nice tied hash class used as an example
805 throughout this POD.
806 Many interesting tied hash classes are available on CPAN and can be
808 found by searching for 'Tie::Hash'.
809
811 Nat Goodman, "<natg at shore.net>"
812
814 Please report any bugs or feature requests to "bug-hash-autohash at
815 rt.cpan.org", or through the web interface at
816 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hash-AutoHash>. I will
817 be notified, and then you'll automatically be notified of progress on
818 your bug as I make changes.
819 Known Bugs and Caveats
821 • Overridden UNIVERSAL methods no longer supported
822 INCOMPATIBLE CHANGE: As of version 1.14, it is no longer possible
824 to use method notation for keys with the same names as methods
825 inherited from UNIVERSAL (the base class of everything). These are
826 'can', 'isa', 'DOES', and 'VERSION'. The reason is that as of Perl
827 5.9.3, calling UNIVERSAL methods as functions is deprecated and
828 developers are encouraged to use method form instead. Previous
829 versions of AutoHash are incompatible with CPAN modules that adopt
830 this style.
831 • Tied hashes and serialization
833 Many serialization modules do not handle tied variables properly,
835 and will not give correct results when applied to Hash::AutoHash
836 objects that use tied hashes. In this context, "serialization"
837 refers to the process of converting Perl data structures into
838 strings that can be saved in files or elsewhere and later restored.
839 Storable handles tied hashes correctly and can be used to serialize
841 all kinds of Hash::AutoHash objects.
842 Data::Dumper, YAML,and Data::Dump::Streamer do not handle tied
844 hashes correctly and cannot be used to serialize Hash::AutoHash
845 objects that use tied hashes. This includes objects created by the
846 autohash_tie, autohash_wrap, and autohash_wrapobj functions (or by
847 equivalent calls to 'new' or autohash_new). It also includes
848 objects that have been aliased. The only Hash::AutoHash objects
849 that can be serialized by these packages are real ones (ie, objects
850 created by autohash_hash or equivalent calls to 'new' or
851 autohash_new) that have not been aliased.
852 If you want to print Hash::AutoHash objects for debugging or
854 testing purposes, Data::Dump works fine. However there is no way to
855 recreate the objects from the printed form.
856 • Tied hashes and prototypes considered harmful (by some)
858 This class uses tied hashes and subroutine prototypes, Perl
860 features that Damian Conway urges programmers to avoid. Obviously,
861 we disagree with Damian on this point, but we acknowledge the
862 weight of his argument.
863
865 You can find documentation for this module with the perldoc command.
866 perldoc Hash::AutoHash
868 You can also look for information at:
870 • RT: CPAN's request tracker
872 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hash-AutoHash>
874 • AnnoCPAN: Annotated CPAN documentation
876 <http://annocpan.org/dist/Hash-AutoHash>
878 • CPAN Ratings
880 <http://cpanratings.perl.org/d/Hash-AutoHash>
882 • Search CPAN
884 <http://search.cpan.org/dist/Hash-AutoHash/>
886
888 Copyright (c) 2008, 2009 Institute for Systems Biology (ISB). All
889 Rights Reserved.
890 This program is free software; you can redistribute it and/or modify it
892 under the terms of either: the GNU General Public License as published
893 by the Free Software Foundation; or the Artistic License.
894 See http://dev.perl.org/licenses/ for more information.
896perl v5.32.1 2021-01-27 Hash::AutoHash(3)