NAME

Tie::Util - Utility functions for fiddling with tied variables

VERSION

Version 0.01

This is a beta version. If you could please test it and report any bugs (via e-mail), I would be grateful.

SYNOPSIS

use Tie::Util;

use Tie::RefHash;
tie %hash, 'Tie::RefHash';

$obj = tied %hash;
tie %another_hash, to => $obj; # two hashes now tied to the same object

is_tied %hash; # returns true

$obj = weak_tie %hash3, 'Tie::RefHash';
# %hash3 now holds a weak reference to the Tie::RefHash object.

weaken_tie %another_hash; # weaken an existing tie

is_weak_tie %hash3; # returns true
is_weak_tie %hash;  # returns false but defined
is_weak_tie %hash4; # returns undef (not tied)

DESCRIPTION

This module provides a few subroutines for examining and modifying tied variables, including those that hold weak references to the objects to which they are tied (weak ties).

It also provides tie constructors in the to:: namespace, so that you can tie variables to existing objects, like this:

tie $var, to => $obj;
weak_tie @var, to => $another_obj; # for a weak tie

FUNCTIONS

All the following functions are exported by default. You can choose to import only a few, with use Tie::Util qw'is_tied weak_tie', or none at all, with use Tie::Util().

is_tied [*%@$]var

Similar to the built-in tied function, but it returns a simple scalar.

With this function you don't have to worry about whether the object to which a variable is tied overloads its booleanness (like JE::Boolean et al.), so you can simply write is_tied instead of defined tied.

Furthermore, it will still return true if it is a weak tie that has gone stale (the object to which it was tied [without holding a reference count] has lost all other references, so the variable is now tied to undef), whereas tied returns undef in such cases.

weak_tie [*%@$]var, $package, @args

Like tie, this calls $package's tie constructor, passing it the @args, and ties the variable to the returned object. But the tie that it creates is a weak one, i.e., the tied variable does not hold a reference count on the object.

weaken_tie [*%@$]var

This turns an existing tie into a weak one.

is_weak_tie [*%@$]var

Returns a defined true or false, indicating whether a tied variable is weakly tied. Returns undef if the variable is not tied.

PREREQUISITES

perl 5.8.3 or later

BUGS

To report bugs, please e-mail the author.

AUTHOR & COPYRIGHT

Copyright (C) 2007 Father Chrysostomos <sprout [at] cpan [dot] org>

This program is free software; you may redistribute it and/or modify it under the same terms as perl.

SEE ALSO

The tie and tied functions in the perlfunc man page.

The perltie man page.

Scalar::Util's weaken function

The B module.

Data::Dumper::Streamer, for which I wrote two of these functions.