/ 
FakeHash-0.80
River stage zero No dependents
/ FakeHash

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 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

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 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.

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 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;
}

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 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.

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 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:

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. Additionally, 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 represents 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 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.

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 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.