NAME
Tie::Util - Utility functions for fiddling with tied variables
VERSION
Version 0.04 (beta)
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
Tie::Util::tie @whatever, to => "MyClass"; # tie @whatever to a class
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
It also allows one to tie a variable to a package, instead of an object (see below).
FUNCTIONS
All the following functions are exported by default, except for fix_tie
. 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 ofdefined 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
), whereastied
returnsundef
in such cases. - tie [*%@$]var, $package, @args
- &tie( \$var, $package, @args );
-
perl did not allow the built-in to be overridden until version 5.13.3, so, for older perls, you have to call this with the
Tie::Util::
prefix or use the&tie(...)
notation.This is just like the built-in function except that, when called with 'to' as the package, it allows you to tie the variable to anything (well, any scalar at least). This is probably only useful for tying a variable to a package, as opposed to an object. (Believe it or not, it's just pure Perl; no XS trickery.)
Otherwise the behaviour is identical to the core function.
- weak_tie [*%@$]var, $package, @args
-
Like perl's tie function, 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.Like
tie
, above, it lets you tie the variable to anything, not just an 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.NOTE: This used to return true for a variable tied to
undef
. Now (as of version 0.02) it returns false, because the tie does not actually hold a weak reference; it holds no reference at all. - tied [*%@$]var
- &tied( \$var )
-
Like perl's tied function, this returns what the variable is tied to, but, unlike the built-in, it returns the actual scalar that the tie uses (instead of copying it), so you can, for instance, check to see whether the variable is tied to a tied variable with
tied &tied($var)
.As with
tie
, you need to use theTie::Util::
prefix or the ampersand form if your perl version is less than 5.13.3. - fix_tie (scalar lvalue expression)
-
This provides a work-around for a bug in perl that was introduced in 5.8.9 and 5.10.0, but was fixed in 5.13.2: If you assign a reference to a tied scalar variable, some operators will operate on that reference, instead of calling
FETCH
and using its return value.If you assign a reference to a tied variable, or a value that might be a reference to a variable that might be tied, then you can 'fix' the tie afterwards by called
fix_tie
on it.fix_tie
is an lvalue function that returns its first argument after fixing it, so you can replace code like($var = $value) =~ s/fror/dwat/;
with
fix_tie( $var = $value ) =~ s/fror/dwat/;
THE to NAMESPACE
Tie::Util installs tie constructors in the 'to' package to work its magic. If anyone else wants to release a module named 'to', just let me know and I'll give you comaint status, as long as you promise not to break Tie::Util!
PREREQUISITES
perl 5.8.0 or later
Exporter 5.57 or later
Scalar::Util 1.09 or later
BUGS
This module does not provide a single function to access the information obscured by a tie. For that, you can simply untie a variable, access its contents, and re-tie it (which is fairly trivial with the functions this module already provides).
Please report bugs at http://rt.cpan.org/ or send email to <bug-Tie-Util@rt.cpan.org>.
AUTHOR & COPYRIGHT
Copyright (C) 2007-14 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.