Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Tie::Util(3)	      User Contributed Perl Documentation	  Tie::Util(3)

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

       Version 0.04 (beta)

	 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)

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

       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

	   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.

       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

	   As with "tie", you need to use the "Tie::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

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


	     fix_tie( $var = $value ) =~ s/fror/dwat/;

       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!

       perl 5.8.0 or later

       Exporter	5.57 or	later

       Scalar::Util 1.09 or later

       o   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 <> or send email to

       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.

       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.

perl v5.32.1			  2015-02-01			  Tie::Util(3)


Want to link to this manual page? Use this URL:

home | help