1Hash::AutoHash(3)     User Contributed Perl Documentation    Hash::AutoHash(3)
2
3
4

NAME

6       Hash::AutoHash - Object-oriented access to real and tied hashes
7

VERSION

9       Version 1.17
10

SYNOPSIS

12         use Hash::AutoHash;
13
14         # real hash
15         my $autohash=new Hash::AutoHash name=>'Joe', hobbies=>['hiking','cooking'];
16
17         # 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
22         # 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
27         # 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
36         # 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
42         # 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
47         # 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
58         # 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

DESCRIPTION

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
73       The class has a 'new' method but also supplies several functions for
74       constructing new Hash::AutoHash objects.
75
76       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
82       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
86         my $name=$autohash->{name};
87         my $name=$autohash->name;
88
89       You can also change the value of an element using either notation:
90
91         $autohash->{name}='Jonathan';
92         $autohash->name('Jonathan');
93
94       And you can add new elements using either notation:
95
96         $autohash->{first_name}='Joe';
97         $autohash->last_name('Plumber');
98
99       CAUTIONS
100
101       · When using method notation, keys must be syntactically legal method
102         names and cannot include 'funny' characters.
103
104       · 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
112       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
116         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
120       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
125         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
131       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
136         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
140       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
144       You can also feed autohash_set separate ARRAYs of keys and values.
145
146         my $autohash=autohash_tie Tie::Hash::MultiValue;
147         autohash_set($autohash,['name','hobbies'],['Joe','hiking']);
148
149       You can alias the object to a regular hash for more concise hash
150       notation.
151
152         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
159       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
164       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
169         # 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
177       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
183         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
189       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
193         my $result=autohash_tied($autohash)->some_method(@parameters);
194
195       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
199         my $result=autohash_tied($autohash,'some_method',@parameters);
200
201   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
209       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
217       Special care is needed with methods used implicitly by Perl to
218       implement common features ('import', 'AUTOLOAD', 'DESTROY').
219
220       '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
226       '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
232       The 'new' method warrants special mention.  In normal use, 'new' is
233       almost always invoked as a class method, eg,
234
235         new Hash::AutoHash(name=>'Joe')
236
237       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
240         $autohash->new
241
242       the code accesses the hash element named 'new'.
243
244   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
251        use Hash::AutoHash qw(autohash_hash autohash_tie autohash_wrap autohash_wrapobj
252                              autohash_wraptie autohash_new);
253
254       autohash_hash
255
256        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
263       autohash_tie
264
265        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
272       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
277         my $tied=tied %$autohash;            # note '%' before '$'
278         my $tied=autohash_tied($autohash);   # note no '%' before '$'
279
280       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
284         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
288       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
292       You can also provide autohash_set with separate ARRAYs of keys and
293       values.
294
295         my $autohash=autohash_tie Tie::Hash::MultiValue;
296         autohash_set($autohash,['name','hobbies'],['Joe','hiking']);
297
298       Wrapping an existing hash or tied object
299
300       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
306       autohash_wrap
307
308        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
323       autohash_wrapobj
324
325        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
338       Here is another, perhaps more typical, illustration of
339       autohash_wrapobj.
340
341         $autohash=autohash_wrapobj tie %hash,'Tie::Hash::MultiValue'
342
343       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
348         $autohash=autohash_wrapobj ((tie %hash,'Tie::Hash::MultiValue'),
349                                     name=>'Joe',hobbies=>'hiking',hobbies=>'cooking')
350
351       autohash_wraptie
352
353        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
364       new
365
366       '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
370        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
409       autohash_new
410
411       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
416        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
434   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
442       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
445       As a convenience, the autoahash_alias functions can link in either
446       direction depending on whether the given object exists.
447
448        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
456   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
460         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
466       A second approach is to invoke a method with the name of the key.  Eg,
467
468         $autohash->name;
469         $autohash->name('Moe');                   # sets name to 'Moe'
470         $autohash->hobbies(['blading','rowing']); # sets hobbies to ['blading','rowing']
471
472       New hash elements can be added using either notation.  For example,
473
474         $autohash->{first_name}='Joe';
475         $autohash->last_name('Plumber');
476
477       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
481         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
486       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
491        use Hash::AutoHash qw(autohash_get autohash_set);
492
493       autohash_get
494
495        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
501       autohash_set
502
503        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
512   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
519        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
524       autohash_clear
525
526        Title   : autohash_clear
527        Usage   : autohash_clear($autohash)
528        Function: Delete entire contents of $autohash
529        Args    : Hash::AutoHash object
530        Returns : nothing
531
532       autohash_delete
533
534        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
540       autohash_exists
541
542        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
548       autohash_each
549
550        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
559       autohash_keys
560
561        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
567       autohash_values
568
569        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
575       autohash_count
576
577        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
583       autohash_empty
584
585        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
591       autohash_notempty
592
593        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
599   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
606       In many cases, you can access the tied object using Perl's built-in
607       tied function.
608
609         my $autohash=autohash_tie Tie::Hash::MultiValue;
610         my $tied=tied %$autohash;             # note leading '%'
611
612       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
619       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
624       If the Hash::AutoHash object is aliased to a hash, the function also
625       works on the hash.
626
627         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
633       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
639         # 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
645        use Hash::AutoHash qw(autohash_tied);
646
647        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
672   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
677       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
685       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
692         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
701         #############################################################
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
718       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
726       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
731       The BEGIN block is needed to make sure @ISA is set at compile-time
732       before @EXPORT_OK is calculated.
733
734       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
740        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
746        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
753        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
765                  If the list of functions is empty, the subroutine is applied to
766                  everything in its parent classes' @SUBCLASS_EXPORT_OK array.
767
768                  The form of the subroutine is exactly as for Perl's grep and map
769                  functions.
770
771        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
779        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

SEE ALSO

791       perltie and Tie::Hash present background on tied hashes.
792
793       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
799       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
804       Tie::Hash::MultiValue is a nice tied hash class used as an example
805       throughout this POD.
806
807       Many interesting tied hash classes are available on CPAN and can be
808       found by searching for 'Tie::Hash'.
809

AUTHOR

811       Nat Goodman, "<natg at shore.net>"
812

BUGS AND CAVEATS

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
820   Known Bugs and Caveats
821       ·   Overridden UNIVERSAL methods no longer supported
822
823           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
832       ·   Tied hashes and serialization
833
834           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
840           Storable handles tied hashes correctly and can be used to serialize
841           all kinds of Hash::AutoHash objects.
842
843           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
853           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
857       ·   Tied hashes and prototypes considered harmful (by some)
858
859           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

SUPPORT

865       You can find documentation for this module with the perldoc command.
866
867           perldoc Hash::AutoHash
868
869       You can also look for information at:
870
871       ·   RT: CPAN's request tracker
872
873           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hash-AutoHash>
874
875       ·   AnnoCPAN: Annotated CPAN documentation
876
877           <http://annocpan.org/dist/Hash-AutoHash>
878
879       ·   CPAN Ratings
880
881           <http://cpanratings.perl.org/d/Hash-AutoHash>
882
883       ·   Search CPAN
884
885           <http://search.cpan.org/dist/Hash-AutoHash/>
886
888       Copyright (c) 2008, 2009 Institute for Systems Biology (ISB). All
889       Rights Reserved.
890
891       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
895       See http://dev.perl.org/licenses/ for more information.
896
897
898
899perl v5.28.1                      2019-02-02                 Hash::AutoHash(3)
Impressum