FakeHash - Simulate the behavior of a Perl hash variable
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
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
corresponding 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 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
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.
iterate will only iterate over the
first n buckets, and will skip the later buckets and their
contents. 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;
}
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
corresponding 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,
FakeHash will emulate the behavior of whatever version of Perl it
is running 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.
FakeHash::DrawHash - Draw a pic diagram of the internal structure of a hash
my $hash = FakeHash::DrawHash->new;
# see L<FakeHash> for more details
$hash->draw($filehandle); # Print 'pic' commands to filehandle
FakeHash::DrawHash is a subclass of FakeHash that can draw a
picture 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:
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.
Additionally, a user parameter argument may be provided, which will be
passed to the other draw_* methods.
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:
Defaults to [1, 0.55], or one inch wide by 0.55 inches tall.
Defaults to 1/5 inch.
Defaults to [1, 0.5], or one inch wide by half an inch tall.
Called once, each time drawing commences. Arguments: The filehandle
and user parameter, if any, that were passed to draw.
Called once, just at the end of each call to draw. Arguments: The
filehandle and user parameter, if any, that were passed to draw.
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.
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.
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.
FakeHash::Node - Class used internally by FakeHash to represent key-value pairs
$key = $node->key;
$value = $node->value;
$hash = $node->hash;
$next = $node->next;
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
FakeHash::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.
Mark-Jason Dominus (mjd-perl-fakehash+@plover.com)
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 MERCHANTABILITY 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.