Unix Man page/Perldoc/Info page, English-Chinese Dictionary,
Chinese-English Dictionary
Unix Man page/Perldoc/Info page, English-Chinese Dictionary,
Chinese-English Dictionary
FakeHash(3pm) User Contributed Perl Documentation FakeHash(3pm) NAME FakeHash - Simulate the behavior of a Perl hash variable SYNOPSIS use FakeHash; my $hash = FakeHash->new; $hash->store($key, $value); # analogous to $h{$key} = $value @keys = $hash->keys; # analogous to @keys = keys %h $hash->delete($key); # analogous to delete $h{$key} $value = $hash->fetch($key); # analogous to $value = $h{$key} $string = $hash->scalarval; # analogous to $string = %h $string = $hash->clear; # analogous to %h = () $hash->iterate(...); # Invoke callbacks for each bucket and node # Caution: Not tested my $hash = tie %h => FakeHash; # $hash will mirror the changes to %h use FakeHash 'hashval'; $n = hashval($string); # hash value for string FakeHash->version(5.005); # Use Perl 5.005 hashval function $version = FakeHash->version; # Return Perl version currently in force DESCRIPTION "FakeHash" simulates the behavior of a Perl hash variable, maintaining a synthetic data structure that mirrors the true data structure inside of Perl. This can be used to investigate hash performance or behavior. For example, see the "FakeHash::DrawHash" class, described below, which draws a box-and-arrow diagram representing the memory layout of a hash. The "store", "fetch", "keys", and "delete" methods perform the corre- sponding operations on the simulated hash. The "iterate" method iterates over the simulated structure and invokes user-supplied callbacks. The arguments to "iterate" are a hash of actions, and an optional user parameter. The "actions" hash may have any or all of the following keys: prebucket A function that is called once for each bucket in the hash, prior to iterating over the nodes in the bucket. The arguments to the "prebucket" function are: the bucket number; a "FakeHash::Node" object representing the first node in the bucket (or an undefined value of the bucket is empty,) and the user parameter. prebucket The same, except that the function is called after iterating over the nodes in the bucket. node A function that is called once for each node (key-value pair) in the hash. The node function is called for a node after the "pre- bucket" function and before the "postbucket" function is called for the node's bucket. The arguments to the "node" function are: The bucket number; a "FakeHash::Node" object representing the first node in the bucket; the node's number within the bucket (0 for the first node in the bucket); the node itself; and the user parameter. maxbucket If this is a number, say n, "iterate" will only iterate over the first n buckets, and will skip the later buckets and their con- tents. If this is a function, "iterate" will call it once, with the user paramater as its argument, and will expect it to return a number n to be used as above. If it is omitted, "iterate" will iterate over all buckets and their contents. For example, the "keys" method is implemented as a call to "iterate", as follows: sub keys { my $self = shift; my @r; $self->iterate({node => sub { my ($i, $b, $n, $node) = @_; push @r, $node->key; }, }); @r; } Other Methods "FakeHash->DEBUG" will return the current setting of the "DEBUG" flag, and will change the value of the flag if given an argument. When the "DEBUG" flag is set to a true value, the module may emit diagnostic messages to "STDERR". Each "FakeHash" object may carry auxiliary information. Auxiliary information is not used by "FakeHash" but may be used by subclasses. "$hash->set_defaults(key, value, key, value,...)" sets the specified auxiliariy data values for the "FakeHash" object. A hashref may be passed instead; its contents will be appended to the values already installed. To query the currently-set values, use "$hash->defaults(key, key, ...)", which will return a list of the cor- responding values, or, in scalar context, a reference to an array of the corresponding values. "$hash->size" retrieves the number of buckets in the hash. The Perl hash function changed between versions 5.005 and 5.6, so the behavior of Perl hashes changed at the same time. By default, "Fake- Hash" will emulate the behavior of whatever version of Perl it is run- ning under. To change this, use the "version" method. Its argument is the version of Perl that you would like to emulate. It returns the version number prior to setting. NAME FakeHash::DrawHash - Draw a "pic" diagram of the internal structure of a hash SYNOPSIS my $hash = FakeHash::DrawHash->new; # see L<FakeHash> for more details $hash->draw($filehandle); # Print 'pic' commands to filehandle DESCRIPTION "FakeHash::DrawHash" is a subclass of "FakeHash" that can draw a pic- ture of the internal structure of a Perl hash variable. It emits code suitable for the Unix "pic" drawing program. "FakeHash::DrawHash" provides the following methods: draw Emit "pic" code for a box-and-arrow diagram that represents the current state of the simulated hash. A filehandle argument may be provided to receive the output. If omitted, output goes to "STDOUT". Addition- ally, a user parameter argument may be provided, which will be passed to the other "draw_*" methods. draw_param Set or retrieve various parameters dermining box size and layout. Takes a name and an optional value argument and returns the old value associated with the name. If the value is provided, sets the new value. Valid names are: BUCKET Determines the size of the boxes used to represent each hash bucket. The value should be a reference to an array of the height and width, in inches. Defaults to "[1, 0.55]", or one inch wide by 0.55 inches tall. BUCKETSPACE Amount of horizontal space,in inches, between the box that repre- sents a bucket and the bixes that represent the bucket contents. If zero, the buckets will abut their contents. Defaults to 1/5 inch. KVP The size of the boxes used to represent each key-value node. The value should be a reference to an array of the height and width, in inches. Defaults to "[1, 0.5]", or one inch wide by half an inch tall. draw_start Called once, each time drawing commences. Arguments: The filehandle and user parameter, if any, that were passed to "draw". draw_end Called once, just at the end of each call to "draw". Arguments: The filehandle and user parameter, if any, that were passed to "draw". draw_bucket Called each time "draw" needs to draw a single bucket. Arguments: The filehandle that was passed to "draw"; the bucket number (starting from 0) of the current bucket; a boolean value which is true if and only if the bucket is nonempty; and the user parameter that was passed to "draw". draw_node Called each time "draw" needs to draw a single key-value node. Arguments: The filehandle that was passed to "draw"; the bucket number (starting from 0) of the bucket in which the current node resides; the number of the node in the current bucket (the first node is node zero); a "FakeHash::Node" object representing the node itself; and the user parameter that was passed to "draw". IDEA The theory here is that it should be easy to override these methods with corresponding methods that draw the diagram in PostScript or GD or whatever. If you do this, please send me the code so that I can distribute it. NAME FakeHash::Node - Class used internally by "FakeHash" to represent key-value pairs SYNOPSIS $key = $node->key; $value = $node->value; $hash = $node->hash; $next = $node->next; DESCRIPTION "FakeHash::Node" is used internally by "FakeHash" for various purposes. For example, the "FakeHash::iterate" function invokes a user-supplied callback for each key-value pair, passing it a series of "Fake- Hash::Node" objects that represent the key-value pairs. The "key" and "value" methods retrieve the key and value of a node. The "hash" method retrieves the key's hash value. "$node->next" method retrieves the node that follows $node in its bucket, or an undefined value if $node is last in its bucket. If any of these methods is passed an additional argument, it will set the corresponding value. It will return the old value in any case. AUTHOR Mark-Jason Dominus ("mjd-perl-fakehash+@plover.com") COPYRIGHT "FakeHash.pm" is a Perl module that simulates the behavior of a Perl hash variable. "FakeHash::DrawHash" renders a diagram of a simulated hash. Copyright (C) 200 Mark-Jason Dominus This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MER- CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. perl v5.8.7 2000-12-19 FakeHash(3pm) |