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

FreeBSD Manual Pages

  
 
  

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

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 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
	   &tied($var)".

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

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

NAME | VERSION | SYNOPSIS | DESCRIPTION | FUNCTIONS | THE to NAMESPACE | PREREQUISITES | BUGS | AUTHOR & COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tie::Util&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help