This is Info file pm.info, produced by Makeinfo version 1.68 from the
input file bigpm.texi.
File: pm.info, Node: Tie/FileLRUCache, Next: Tie/FlipFlop, Prev: Tie/EncryptedHash, Up: Module List
A lightweight but robust filesystem based persistent LRU cache
**************************************************************
NAME
====
Tie::FileLRUCache - A lightweight but robust filesystem based
persistent LRU cache
CHANGES
=======
1.01 19991209 Added 'detainting' to cache management code.
SYNOPSIS
========
OBJECT INTERFACE
----------------
use Tie::FileLRUCache;
my $cache = Tie::FileLRUCache->new({ -cache_dir => $directory, -keep_last => 100 });
# Inserting value into LRU cache using '-key'
$cache->update({ -key => $key, -value => $value });
# Inserting value into LRU cache using '-cache_key'
my $cache_key = $cache->make_cache_key({ -key => $key });
$cache->update({ -cache_key => $cache_key, -value => $value });
# Checking LRU cache
my ($in_cache,$value) = $cache->check({ -key => $key });
if ($in_cache) {
return $value;
}
# Not in cache - do something else
# Checking LRU cache with speed up hack for objects, hashes, arrays etc used as keys
my $cache_key = $cache->make_cache_key({ -key => $something });
my ($in_cache,$value) = $cache->check({ -cache_key => $cache_key });
if ($in_cache) {
return $value;
}
# Not in cache - do something else
# Deleting a key and its value from the cache
$cache->delete({ -key => $key });
# Clearing LRU cache
$cache->clear;
TIED INTERFACE
--------------
use Tie::FileLRUCache;
[$X =] tie %hash, 'Tie::FileLRUCache', $cache_dir, $keep_last_n;
# Adding a key/value to the cache
$hash{$key} = $value;
# Checking the cache
if (not exists $hash{$key}) {;
# No match
.
.
.
} else {
my $value = $hash{$key};
.
.
.
}
# Removing a value from the cache;
delete $hash{$key};
# Clearing the cache
%hash = ();
Note: Iteration over the cache (each, keys, values) is _NOT_
supported.
DESCRIPTION
===========
Provides a persistent filesystem based LRU cache.
It uses the 'last accessed' timestamp generated by the file system to
determine the 'oldest' cache entry and discards the oldest cache entries
when needed to stay under the -keep_last limit.
If you store thing very fast (such that many entries receive the _same_
time stamp), it is essentially a coin toss which entry within a single
timestamped second gets purged from the cache to make room for new ones.
OBJECT METHODS
==============
`new($parm_ref);'
Creates and optionally initializes a Tie::FileLRUCache object:
Example:
my $cache = Tie::FileLRUCache->new({
-cache_dir => '/tmp/testing',
-keep_last => 100,
});
`check($parm_ref);'
Reads the cache for the key.
Returns two values: $cache_hit (true if a hit was found, false if not)
$value (the cached value, undef if no hit)
Examples:
my ($cache_hit,$value) = $cache->check({ -key => $key });
my ($cache_hit,$value) = $cache->check({ -cache_key => $cache_key });
The '-key' form is used when you just want to use a raw key. It can
use blessed objects, hash refs, scalars, or array refs as keys. The
more complex structures take a speed penalty for computing a
canonical form. You can minimize this penalty by using the
'-cache_key' form instead.
The '-cache_key' form is used for performance reasons when using keys
such as complex blessed objects or hashes as a key. The -cache_key is
obtained with a call to 'make_cache_key'. It is legal to mix
-cache_key and -key based calls - they are cross-compatible.
`make_cache_key($parm_ref);'
Generates a cache key by canonicalizing a passed key as a network
ordered canonical Storable string.
Example:
my $cache_key = $cache->make_cache_key({ -key => $key });
`clear;'
Completely clears the cache.
`update($parm_ref);'
Updates the Least Recently Used cache for the specified key with the
passed value. '-keep_last' is optional after the first access to a
dataset. It will use the _most recent_ 'keep_last' used if not
specified.
It is legal to use ordinary scalars, hash references, or array
references as keys as well as objects as -keys or -values.
Basically, anything that Storable can serialize can be used.
Examples:
$cache->update({ -key => $key, -value => $value });
$cache->update({ -key => $key, -value => $value, -keep_last => 100});
my $cache_key = $cache->make_cache_key({ -key => $key });
$cache->update({ -cache_key => $cache_key, -value => $value });
my $cache_key = $cache->make_cache_key({ -key => $key });
$cache->update({ -cache_key => $cache_key, -value => $value, -keep_last => 50 });
`delete($parm_ref);'
Forces the deletion of a specific key from the cache.
Example:
$cache->delete({ -key => $key });
COPYRIGHT
=========
Copyright 1999, Benjamin Franz ()
and FreeRun Technologies, Inc. (). All
Rights Reserved. This software may be copied or redistributed under the
same terms as Perl itelf.
AUTHOR
======
Benjamin Franz
TODO
====
Debugging.
File: pm.info, Node: Tie/FlipFlop, Next: Tie/Handle, Prev: Tie/FileLRUCache, Up: Module List
Alternate between two values.
*****************************
NAME
====
Tie::FlipFlop - Alternate between two values.
SYNOPSIS
========
use Tie::FlipFlop;
tie my $flipflop => Tie::FlipFlop => qw /Red Green/;
print $flipflop; # Prints 'Red'.
print $flipflop; # Prints 'Green'.
print $flipflop; # Prints 'Red'.
DESCRIPTION
===========
`Tie::FlipFlop' allows you to tie a scalar in such a way that refering
to the scalar alternates between two values. When tying the scalar, exactly
two extra arguments have to be given, the values to be alternated between.
Assigning to the scalar leads to a fatal, but trappable, error.
REVISION HISTORY
================
$Log: FlipFlop.pm,v $
Revision 1.1 1999/07/19 22:07:22 abigail
Initial revision
AUTHOR
======
This package was written by Abigail.
COPYRIGHT and LICENSE
=====================
This package is copyright 1999 by Abigail.
This program is free and open software. You may use, copy, modify,
distribute and sell this program (and any modified variants) in any way
you wish, provided you do not restrict others to do the same.
File: pm.info, Node: Tie/Handle, Next: Tie/Hash, Prev: Tie/FlipFlop, Up: Module List
base class definitions for tied handles
***************************************
NAME
====
Tie::Handle, Tie::StdHandle - base class definitions for tied handles
SYNOPSIS
========
package NewHandle;
require Tie::Handle;
@ISA = (Tie::Handle);
sub READ { ... } # Provide a needed method
sub TIEHANDLE { ... } # Overrides inherited method
package main;
tie *FH, 'NewHandle';
DESCRIPTION
===========
This module provides some skeletal methods for handle-tying classes. See
*Note Perltie: (perl.info)perltie, for a list of the functions required in
tying a handle to a package. The basic Tie::Handle package provides a new
method, as well as methods TIEHANDLE, PRINT, PRINTF and GETC.
For developers wishing to write their own tied-handle classes, the
methods are summarized below. The *Note Perltie: (perl.info)perltie,
section not only documents these, but has sample code as well:
TIEHANDLE classname, LIST
The method invoked by the command `tie *glob, classname'. Associates
a new glob instance with the specified class. LIST would represent
additional arguments (along the lines of *Note AnyDBM_File:
AnyDBM_File, and compatriots) needed to complete the association.
WRITE this, scalar, length, offset
Write length bytes of data from scalar starting at offset.
PRINT this, LIST
Print the values in LIST
PRINTF this, format, LIST
Print the values in LIST using format
READ this, scalar, length, offset
Read length bytes of data into scalar starting at offset.
READLINE this
Read a single line
GETC this
Get a single character
CLOSE this
Close the handle
OPEN this, filename
(Re-)open the handle
BINMODE this
Specify content is binary
EOF this
Test for end of file.
TELL this
Return position in the file.
SEEK this, offset, whence
Position the file.
Test for end of file.
DESTROY this
Free the storage associated with the tied handle referenced by *this*.
This is rarely needed, as Perl manages its memory quite well. But the
option exists, should a class wish to perform specific actions upon
the destruction of an instance.
MORE INFORMATION
================
The *Note Perltie: (perl.info)perltie, section contains an example of
tying handles.
File: pm.info, Node: Tie/Hash, Next: Tie/HashDefaults, Prev: Tie/Handle, Up: Module List
base class definitions for tied hashes
**************************************
NAME
====
Tie::Hash, Tie::StdHash - base class definitions for tied hashes
SYNOPSIS
========
package NewHash;
require Tie::Hash;
@ISA = (Tie::Hash);
sub DELETE { ... } # Provides needed method
sub CLEAR { ... } # Overrides inherited method
package NewStdHash;
require Tie::Hash;
@ISA = (Tie::StdHash);
# All methods provided by default, define only those needing overrides
sub DELETE { ... }
package main;
tie %new_hash, 'NewHash';
tie %new_std_hash, 'NewStdHash';
DESCRIPTION
===========
This module provides some skeletal methods for hash-tying classes. See
*Note Perltie: (perl.info)perltie, for a list of the functions required in
order to tie a hash to a package. The basic Tie::Hash package provides a
new method, as well as methods TIEHASH, EXISTS and CLEAR. The
*Tie::StdHash* package provides most methods required for hashes in *Note
Perltie: (perl.info)perltie,. It inherits from Tie::Hash, and causes tied
hashes to behave exactly like standard hashes, allowing for selective
overloading of methods. The new method is provided as grandfathering in
the case a class forgets to include a TIEHASH method.
For developers wishing to write their own tied hashes, the required
methods are briefly defined below. See the *Note Perltie:
(perl.info)perltie, section for more detailed descriptive, as well as
example code:
TIEHASH classname, LIST
The method invoked by the command `tie %hash, classname'. Associates
a new hash instance with the specified class. LIST would represent
additional arguments (along the lines of *Note AnyDBM_File:
AnyDBM_File, and compatriots) needed to complete the association.
STORE this, key, value
Store datum value into key for the tied hash *this*.
FETCH this, key
Retrieve the datum in key for the tied hash *this*.
FIRSTKEY this
Return the (key, value) pair for the first key in the hash.
NEXTKEY this, lastkey
Return the next key for the hash.
EXISTS this, key
Verify that key exists with the tied hash *this*.
The Tie::Hash implementation is a stub that simply croaks.
DELETE this, key
Delete the key key from the tied hash *this*.
CLEAR this
Clear all values from the tied hash *this*.
CAVEATS
=======
The *Note Perltie: (perl.info)perltie, documentation includes a method
called DESTROY as a necessary method for tied hashes. Neither Tie::Hash
nor *Tie::StdHash* define a default for this method. This is a standard
for class packages, but may be omitted in favor of a simple default.
MORE INFORMATION
================
The packages relating to various DBM-related implementations (DB_File,
`NDBM_File', etc.) show examples of general tied hashes, as does the *Note
Config: Config, module. While these do not utilize Tie::Hash, they serve as
good working examples.
File: pm.info, Node: Tie/HashDefaults, Next: Tie/IntegerArray, Prev: Tie/Hash, Up: Module List
Let a hash have default values
******************************
NAME
====
Tie::HashDefaults - Let a hash have default values
SYNOPSIS
========
use Tie::HashDefaults;
tie %h, 'Tie::HashDefaults', \%defaults1, \%defaults0;
DESCRIPTION
===========
This creates a data structure which is essentially an array of hashes;
this list contains all the hashes (passed by ref) in the argument list;
but it also contains a new, internally created, anonymous hash. This hash
is used to store any insertions into the tied hash.
Whenever a fetch (or an exists) is done on the tied hash, the requested
key is searched for in each hash in the list, beginning with the internal
"storage" hash; if it is not found in that hash, the key is looked for in
the first default hash, then the next, and so on, until it is found in one
of them, or there are none left to search.
When an iteration (keys or each) is done on the tied hash, the set of
keys returned is the union of keys from all of the default hashes, along
with the storage hash.
For operations that alter a hash - store, delete, clear - the default
hashes are never touched. Only the storage hash is cleared. One effect
of this is that if the tied hash is cleared, e.g. via `%h = ();', and
immediately following that an iteration is started (via keys or each), it
is likely that some keys will be returned. (Unless, of course, there is
no data in any of the given default hashes.)
Manipulating the Defaults List
------------------------------
The list of default hashes can be manipulated directly. To do this, a
special method on the tied object returns an array, by reference,
containing the list of default hashes. Any changes to this array are
reflected inside the Tie::HashDefaults object. For example, to add another
defaults source that takes precedence over the others already on the list:
unshift @{ tied(%h)->get_defaults_list }, \%new_default_source;
Or, to reverse the order in which the defaults are consulted:
$ar = tied(%h)->get_defaults_list;
@$ar = reverse @$ar;
(Once you have the array-ref "handle" on the defaults list array, it's
good for as long as the tied object stays tied.)
NOTE: calling `get_defaults_list' also resets the iterator; so don't
call it within an each loop on a hash tied to this class.
AUTHOR
======
jdporter@min.net (John Porter)
COPYRIGHT
=========
This is free software. This software may be modified and distributed
under the same terms as Perl itself.
File: pm.info, Node: Tie/IntegerArray, Next: Tie/IxHash, Prev: Tie/HashDefaults, Up: Module List
provides a tied array of packed integers of any bit length
**********************************************************
NAME
====
Tie::IntegerArray - provides a tied array of packed integers of any bit
length
SYNOPSIS
========
use Tie::IntegerArray;
# an array of signed 16-bit integers with no undef support and
# starting room for 100,000 items. You can expect this to consume a
# bit more than 200K of memory versus more than 800K for a normal
# Perl array.
my @integer_array;
tie @integer_array, 'Tie::IntegerArray',
bits => 16,
signed => 1,
undef => 0,
size => 100_000;
# put a value in
$integer_array[0] = 10;
# and print it out
print "Int 0: $integer_array[0]\n";
# the full range of array operations are available
DESCRIPTION
===========
This module provides an array interface to packed array of integers. A
packed array of integers is useful in situations where you need to store a
large set of integers in as small a space as possible. Access to the
packed array will be significantly slower than access to a normal array
but for many applications the reduction in memory usage makes this a good
trade-off.
USAGE
=====
To create an IntegerArray you call tie with a number of optional
arguements. These arguements let you fine-tune the storage of your
integers. The simplest tie call uses no options:
my @integer_array;
tie @integer_array, 'Tie::IntegerArray';
This will create an array of signed integers with the same size as
native ints on your platform. By default the array does not support undef
- values are 0 by default. This may be ideal for many applications - read
below for other options.
OPTIONS
=======
* bits (defaults to your machine's int size)
This option specifies how many bits to use to store the integer value.
This setting determines the possible range of your integers. If you
specify unsigned integers (see below) then the maximum range on your
integers is simply 2^bits. For example, 8 bits provides an unsigned
range of 0 - 255.
Since the integers are stored in a packed array you can calculate the
size of your array by multiplying the number of items by the number of
bits.
Attempting to store a value into the array that is too large or too
small for the available bit size will cause an error.
* signed (defaults to 1)
If you set signed to 1 then your integers will be signed. This
reduces their positive range by a power of 2 but provides equal
negative range. For example, an 8 bit signed integer has a range from
-128 - 127.
* undef (defaults to 0)
By default IntegerArrays do not support undef. This means that array
values will be 0 until they are set to some value. Calling defined()
on an array value will return true if exists() will. You can change
this by setting undef to 1. This requires extra memory - 1 bit per
array entry.
* size (defaults to 1)
IntegerArrays grow automatically as you add items but you can specify
a size arguement to pre-allocate space. This will improve performance
for large arrays.
FUTURE PLANS
============
This module is functionally complete but not yet fully optimized. It
relies on Tie::Array for the more advanced array functions (push, pop,
etc) and a native implementation could be faster. If this module proves
at all popular then I will definitely move in that direction.
CREDITS
=======
Steffen Beyer - Bit::Vector is pure magic.
AUTHOR
======
Sam Tregar, sam@tregar.com
LICENSE
=======
HTML::Template : A module for using HTML Templates with Perl Copyright
(C) 2000 Sam Tregar (sam@tregar.com)
This module is free software; you can redistribute it and/or modify it
under the terms of either:
a) the GNU General Public License as published by the Free Software
Foundation; either version 1, or (at your option) any later version, or
b) the "Artistic License" which comes with this module.
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 either the GNU General Public
License or the Artistic License for more details.
You should have received a copy of the Artistic License with this
module, in the file ARTISTIC. If not, I'll be glad to provide one.
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., 59
Temple Place, Suite 330, Boston, MA 02111-1307 USA
SEE ALSO
========
Bit::Vector
File: pm.info, Node: Tie/IxHash, Next: Tie/LDAP, Prev: Tie/IntegerArray, Up: Module List
ordered associative arrays for Perl
***********************************
NAME
====
Tie::IxHash - ordered associative arrays for Perl
SYNOPSIS
========
# simple usage
use Tie::IxHash;
tie HASHVARIABLE, Tie::IxHash [, LIST];
# OO interface with more powerful features
use Tie::IxHash;
TIEOBJECT = Tie::IxHash->new( [LIST] );
TIEOBJECT->Splice( OFFSET [, LENGTH [, LIST]] );
TIEOBJECT->Push( LIST );
TIEOBJECT->Pop;
TIEOBJECT->Shift;
TIEOBJECT->Unshift( LIST );
TIEOBJECT->Keys( [LIST] );
TIEOBJECT->Values( [LIST] );
TIEOBJECT->Indices( LIST );
TIEOBJECT->Delete( [LIST] );
TIEOBJECT->Replace( OFFSET, VALUE, [KEY] );
TIEOBJECT->Reorder( LIST );
TIEOBJECT->SortByKey;
TIEOBJECT->SortByValue;
TIEOBJECT->Length;
DESCRIPTION
===========
This Perl module implements Perl hashes that preserve the order in
which the hash elements were added. The order is not affected when values
corresponding to existing keys in the IxHash are changed. The elements can
also be set to any arbitrary supplied order. The familiar perl array
operations can also be performed on the IxHash.
Standard TIEHASH Interface
--------------------------
The standard TIEHASH mechanism is available. This interface is
recommended for simple uses, since the usage is exactly the same as
regular Perl hashes after the tie is declared.
Object Interface
----------------
This module also provides an extended object-oriented interface that
can be used for more powerful operations with the IxHash. The following
methods are available:
FETCH, STORE, DELETE, EXISTS
These standard TIEHASH methods mandated by Perl can be used directly.
See the tie entry in perlfunc(1) for details.
Push, Pop, Shift, Unshift, Splice
These additional methods resembling Perl functions are available for
operating on key-value pairs in the IxHash. The behavior is the same
as the corresponding perl functions, except when a supplied hash key
already exists in the hash. In that case, the existing value is
updated but its order is not affected. To unconditionally alter the
order of a supplied key-value pair, first DELETE the IxHash element.
Keys
Returns an array of IxHash element keys corresponding to the list of
supplied indices. Returns an array of all the keys if called without
arguments. Note the return value is mostly only useful when used in
a list context (since perl will convert it to the number of elements
in the array when used in a scalar context, and that may not be very
useful).
If a single argument is given, returns the single key corresponding to
the index. This is usable in either scalar or list context.
Values
Returns an array of IxHash element values corresponding to the list
of supplied indices. Returns an array of all the values if called
without arguments. Note the return value is mostly only useful when
used in a list context (since perl will convert it to the number of
elements in the array when used in a scalar context, and that may not
be very useful).
If a single argument is given, returns the single value corresponding
to the index. This is usable in either scalar or list context.
Indices
Returns an array of indices corresponding to the supplied list of
keys. Note the return value is mostly only useful when used in a
list context (since perl will convert it to the number of elements in
the array when used in a scalar context, and that may not be very
useful).
If a single argument is given, returns the single index corresponding
to the key. This is usable in either scalar or list context.
Delete
Removes elements with the supplied keys from the IxHash.
Replace
Substitutes the IxHash element at the specified index with the
supplied value-key pair. If a key is not supplied, simply
substitutes the value at index with the supplied value. If an element
with the supplied key already exists, it will be removed from the
IxHash first.
Reorder
This method can be used to manipulate the internal order of the IxHash
elements by supplying a list of keys in the desired order. Note
however, that any IxHash elements whose keys are not in the list will
be removed from the IxHash.
Length
Returns the number of IxHash elements.
SortByKey
Reorders the IxHash elements by textual comparison of the keys.
SortByValue
Reorders the IxHash elements by textual comparison of the values.
EXAMPLE
=======
use Tie::IxHash;
# simple interface
$t = tie(%myhash, Tie::IxHash, 'a' => 1, 'b' => 2);
%myhash = (first => 1, second => 2, third => 3);
$myhash{fourth} = 4;
@keys = keys %myhash;
@values = values %myhash;
print("y") if exists $myhash{third};
# OO interface
$t = Tie::IxHash->new(first => 1, second => 2, third => 3);
$t->Push(fourth => 4); # same as $myhash{'fourth'} = 4;
($k, $v) = $t->Pop; # $k is 'fourth', $v is 4
$t->Unshift(neg => -1, zeroth => 0);
($k, $v) = $t->Shift; # $k is 'neg', $v is -1
@oneandtwo = $t->Splice(1, 2, foo => 100, bar => 101);
@keys = $t->Keys;
@values = $t->Values;
@indices = $t->Indices('foo', 'zeroth');
@itemkeys = $t->Keys(@indices);
@itemvals = $t->Values(@indices);
$t->Replace(2, 0.3, 'other');
$t->Delete('second', 'zeroth');
$len = $t->Length; # number of key-value pairs
$t->Reorder(reverse @keys);
$t->SortByKey;
$t->SortByValue;
BUGS
====
You cannot specify a negative length to `Splice'. Negative indexes are
OK, though.
Indexing always begins at 0 (despite the current $[ setting) for all
the functions.
TODO
====
Addition of elements with keys that already exist to the end of the
IxHash must be controlled by a switch.
Provide TIEARRAY interface when it stabilizes in Perl.
Rewrite using XSUBs for efficiency.
AUTHOR
======
Gurusamy Sarathy gsar@umich.edu
Copyright (c) 1995 Gurusamy Sarathy. All rights reserved. This program
is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.
VERSION
=======
Version 1.21 20 Nov 1997
SEE ALSO
========
perl(1)
File: pm.info, Node: Tie/LDAP, Next: Tie/LDAP/Entry, Prev: Tie/IxHash, Up: Module List
Tie LDAP database to Perl hash.
*******************************
NAME
====
Tie::LDAP - Tie LDAP database to Perl hash.
SYNOPSIS
========
use Tie::LDAP;
tie %LDAP, 'Tie::LDAP', {
host => $host, # LDAP hostname (defaults to 127.0.0.1)
port => $port, # Port number (defaults to 389)
user => $user, # Full DN used to access LDAP database
pass => $pass, # Password used with above DN
base => $base, # Base DN used for each/keys/values operation
};
DESCRIPTION
===========
This library allows you to tie LDAP database to Perl hash. Once tied,
all hash operation will cause corresponding LDAP operation, as you would
(probably) expect.
Referencing tied hash will return hash reference to named LDAP entry
that holds lowercased attribute as hash key, and reference to ARRAY
containing data as hash value.
Storing data is as easy as fetching: just push hash reference - with
the same structure as fetched hash - back in.
Also, fetching/storing data into fetched hash reference will work as
expected - it will manipulate corresponding field in fetched LDAP entry.
EXAMPLE
=======
Here's a brief example of how you can use this module:
use Tie::LDAP;
## connect
tie %LDAP, 'Tie::LDAP', { base => 'o=IMASY, c=JP' };
## lookup entry for [dn: cn=tai, o=IMASY, c=JP]
$info = $LDAP{q{cn=tai, o=IMASY, c=JP}};
## lookup each attributes
$user = $info->{username}->[0];
$mail = @{$info->{mailaddr}};
## update each attributes
$info->{username} = ['newname'];
$info->{mailaddr} = ['tai@imasy.or.jp', 'tyamada@tk.elec.waseda.ac.jp'];
## update entry
$LDAP{q{cn=tai, o=IMASY, c=JP}} = {
username => ['newname'],
mailaddr => ['tai@imasy.or.jp', 'tyamada@tk.elec.waseda.ac.jp'],
};
## dump database (under base DN of [o=IMASY, c=JP]) in LDIF style
while (my($dn, $hash) = each %LDAP) {
print "dn: $dn\n";
while (my($name, $list) = each %{$hash}) {
foreach (@{$list}) {
print "$name: $_\n";
}
}
print "\n";
}
## disconnect
untie %LDAP;
BUGS
====
Doing each/keys/values operation to tied hash works (as shown in
example), but could be _very_ slow, depending on the size of the database.
This is because all operation is done synchronously.
Also, though this is not a bug, substituting empty array to tied hash
will cause whole database to be cleared out.
COPYRIGHT
=========
Copyright 1998-2000, T. Yamada . All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
========
*Note Net/LDAPapi: Net/LDAPapi,
File: pm.info, Node: Tie/LDAP/Entry, Next: Tie/LLHash, Prev: Tie/LDAP, Up: Module List
Tie LDAP database entry to Perl hash.
*************************************
NAME
====
Tie::LDAP::Entry - Tie LDAP database entry to Perl hash.
SYNOPSIS
========
use Tie::LDAP;
tie %LDAP, 'Tie::LDAP', {
host => $host,
user => $user,
pass => $user,
base => $base,
};
$data = $LDAP{$path};
## Simple hash operation, but also updates corresponding LDAP entry
$data->{username} = 'tai@imasy.or.jp';
...
DESCRIPTION
===========
See *Note Tie/LDAP: Tie/LDAP,.
COPYRIGHT
=========
Copyright 1998-1999, T. Yamada . All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
========
*Note Tie/LDAP: Tie/LDAP,, *Note Net/LDAP: Net/LDAP,
File: pm.info, Node: Tie/LLHash, Next: Tie/ListKeyedHash, Prev: Tie/LDAP/Entry, Up: Module List
ordered hashes
**************
NAME
====
Tie::LLHash.pm - ordered hashes
DESCRIPTION
===========
This class implements an ordered hash-like object. It's a cross
between a Perl hash and a linked list. Use it whenever you want the speed
and structure of a Perl hash, but the orderedness of a list.
Don't use it if you want to be able to address your hash entries by
number, like you can in a real list ($list[5]).
See also Tie::IxHash by Gurusamy Sarathy. It's similar (it also does
ordered hashes), but it has a different internal data structure and a
different flavor of usage. IxHash stores its data internally as both a
hash and an array in parallel. LLHash stores its data as a bidirectional
linked list, making both inserts and deletes very fast. IxHash therefore
makes your hash behave more like a list than LLHash does. This module
keeps more of the hash flavor.
SYNOPSIS
========
use Tie::LLHash;
# A new empty ordered hash:
tie (%hash, "Tie::LLHash");
# A new ordered hash with stuff in it:
tie (%hash2, "Tie::LLHash", key1=>$val1, key2=>$val2);
# Allow easy insertions at the end of the hash:
tie (%hash2, "Tie::LLHash", {lazy=>1}, key1=>$val1, key2=>$val2);
# Add some entries:
(tied %hash)->first('the' => 'hash');
(tied %hash)->insert('here' => 'now', 'the');
(tied %hash)->first('All' => 'the');
(tied %hash)->insert('are' => 'right', 'the');
(tied %hash)->insert('things' => 'in', 'All');
(tied %hash)->last('by' => 'gum');
$value = $hash{'things'}; # Look up a value
$hash{'here'} = 'NOW'; # Set the value of an EXISTING RECORD!
$key = (tied %hash)->key_before('in'); # Returns the previous key
$key = (tied %hash)->key_after('in'); # Returns the next key
# Luxury routines:
$key = (tied %hash)->current_key;
$val = (tied %hash)->current_value;
(tied %hash)->next;
(tied %hash)->prev;
(tied %hash)->reset;
# If lazy-mode is set, new keys will be added at the end.
$hash{newkey} = 'newval';
$hash{newkey2} = 'newval2';
METHODS
=======
* insert(key, value, previous_key)
This inserts a new key-value pair into the hash right after the
`previous_key' key. If `previous_key' is undefined (or not
supplied), this is exactly equivalent to `first(key, value)'. If
`previous_key' is defined, then it must be a string which is already
a key in the hash - otherwise we'll croak().
* first(key, value) (or) first()
Gets or sets the first key in the hash. Without arguments, simply
returns a string which is the first key in the database. With
arguments, it inserts a new key-value pair at the beginning of the
hash.
* last(key, value) (or) last()
Gets or sets the last key in the hash. Without arguments, simply
returns a string which is the last key in the database. With
arguments, it inserts a new key-value pair at the end of the hash.
* key_before(key)
Returns the name of the key immediately before the given key. If no
keys are before the given key, returns undef.
* key_after(key)
Returns the name of the key immediately after the given key. If no
keys are after the given key, returns undef.
* current_key()
When iterating through the hash, this returns the key at the current
position in the hash.
* current_value()
When iterating through the hash, this returns the value at the
current position in the hash.
* next()
Increments the current position in the hash forward one item.
Returns the new current key, or undef if there are no more entries.
* prev()
Increments the current position in the hash backward one item.
Returns the new current key, or undef if there are no more entries.
* reset()
Resets the current position to be the start of the order. Returns
the new current key, or undef if there are no keys.
Here is a smattering of ways you can iterate over the hash. I include
it here simply because iteration is probably important to people who need
ordered data.
while (($key, $val) = each %hash) {
print ("$key: $val\n");
}
foreach $key (keys %hash) {
print ("$key: $hash{$key}\n");
}
my $obj = tied %hash; # For the following examples
$key = $obj->reset;
while (exists $hash{$key}) {
print ("$key: $hash{$key}\n");
$key = $obj->next;
}
$obj->reset;
while (exists $hash{$obj->current_key}) {
$key = $obj->current_key;
print ("$key: $hash{$key}\n");
$obj->next;
}
WARNINGS
========
* Unless you're using lazy-mode, don't add new elements to the hash by
simple assignment, a la <$hash{$new_key} = $value>, because LLHash
won't know where in the order to put the new element.
TO DO
=====
I could speed up the keys() routine in a scalar context if I knew how to
sense when NEXTKEY is being called on behalf of keys(). Not sure whether
this is possible.
I may also want to add a method for... um, I forgot. Something.
AUTHOR
======
Ken Williams
Copyright (c) 1998 Swarthmore College. All rights reserved. This
program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
File: pm.info, Node: Tie/ListKeyedHash, Next: Tie/Math, Prev: Tie/LLHash, Up: Module List
A system allowing the use of anonymous arrays as keys to a hash.
****************************************************************
NAME
====
Tie::ListKeyedHash - A system allowing the use of anonymous arrays as
keys to a hash.
SYNOPSIS
========
use Tie::ListKeyedHash;
[$X =] tie %hash, 'Tie::ListKeyedHash';
$hash{['key','items','live']} = 'Hello!';
$hash{['key','trees','grow']} = 'Goodbye!';
print $hash{['key','items','live']},"\n";
my (@list) = keys %{$hash{['key']}};
print "@list\n";
untie %hash ;
Alternatively keys are accessible as:
$hash{'key','items','live'} = 'Hello!';
This way slows down the accesses by around 10% and cannot
be used for keys that conflict with the value of '$;'.
Also usable via the object interface methods 'put',
'get','exists','delete','clear'. The object interface
is about 2x as fast as the tied interface.
DESCRIPTION
===========
Tie::ListKeyedHash ties a hash so that you can use a reference to an
array as the key of the hash.
CHANGES
=======
0.41 09 Jun 1999
----------------
Minor documentation changes.
0.40 04 May 1999
----------------
Yet Another Rename to Tie::ListKeyedHash. Final rename, I promise.
0.30 04 May 1999
----------------
Renamed to 'Tie::ListKeyedHash' after discussion on
comp.lang.perl.module and added (on the suggestion of Ilya Zakharevich,
) support for using the tie hash as
$hash{'key1','key2','key3'} as well as its native mode of
$hash{['key1','key2','key3']}
0.20 30 April 1999
------------------
Initial public release as 'Tie::ArrayHash'
METHODS
=======
`new(....);'
Returns the object reference for the tie.
`TIEHASH(....);'
Returns the object reference for the tie.
`STORE($key_ref,$value);'
Stores the $value into the arrayhash location pointed to by the
$key_ref array reference.
If the '$key_ref' is a $; seperated text string instead of an array
reference, it splits it on $; and uses the resulting array as the
actual key.
`FETCH($key_ref);'
Returns the value pointed to by the $key_ref array reference.
If the '$key_ref' is a $; seperated text string instead of an array
reference, it splits it on $; and uses the resulting array as the
actual key.
`DELETE($key_ref);'
Deletes a specified item from the arrayhash.
If the '$key_ref' is a $; seperated text string instead of an array
reference, it splits it on $; and uses the resulting array as the
actual key.
`CLEAR;'
Clears the entire arrayhash.
`EXISTS($key_ref);'
Returns true if the specified arrayhash key exists, false if it does
not.
If the '$key_ref' is a $; seperated text string instead of an array
reference, it splits it on $; and uses the resulting array as the
actual key.
`FIRSTKEY;'
Returns the first key.
`NEXTKEY;'
Returns the next key.
`DESTROY;'
`clear;'
Clears the entire hash.
`exists([@key_list]);'
Returns true of the specified hash element exists, false if it does
not. Just as with normal hashes, intermediate elements will be
created if they do not already exist.
The strange elsif construct provides a performance boost for shallow
keys.
`get([@key_list]);'
Returns the contents of the object field denoted by the @key_list.
This is a way of making arbitrary keys that act like hashes, with the
'hardwiring' requirements of hashes. The routine returns the the
contents addressed by 'key1','key2','key3',...
The strange elsif construct provides a performance boost for shallow
keys.
`put([@key_list],$value);';
Sets $value as the contents of the object field denoted by the
@key_list. This is a way of making arbitrary keys that act like
hashes, without the 'hardwiring' requirements of hashes.
The strange elsif construct provides a performance boost for shallow
keys.
`delete([@key_list]);';
Deletes the object field denoted by the @key_list.
This is a way of making arbitrary keys that act like hashes, without
the 'hardwiring' requirements of hashes.
The strange elsif construct provides a performance boost for shallow
keys.
BUGS
====
To Be Determined.
TODO
====
FIRSTKEY, NEXTKEY have to be tested completely.
AUTHORS
=======
Benjamin Franz
VERSION
=======
Version 0.40 May 1999
Copyright (c) Benjamin Franz 1999. All rights reserved.
This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
SEE ALSO
========
perl perltie
File: pm.info, Node: Tie/Math, Next: Tie/MmapArray, Prev: Tie/ListKeyedHash, Up: Module List
Hashes which represent mathematical functions.
**********************************************
NAME
====
Tie::Math - Hashes which represent mathematical functions.
SYNOPSIS
========
use Tie::Math;
tie %fibo, 'Tie::Math', sub { f(n) = f(n-1) + f(n-2) },
sub { f(0) = 0; f(1) = 1 };
# Calculate and print the fifth fibonacci number
print $fibo{5};
DESCRIPTION
===========
Defines hashes which represent mathematical functions, such as the
fibonacci sequence, factorials, etc... Functions can be expressed in a
manner which a math or physics student might find a bit more familiar. It
also automatically employs memoization.
Multi-variable functions are supported. f() is simply passed two
variables (f(X,Y) for instance) and the hash is accessed in the same way
($func{3,-4}).
tie
tie %func, 'Tie::Math', \&function;
tie %func, 'Tie::Math', \&function, \&initialization;
&function contains the definition of the mathematical function. Use
the f() subroutine and N index provided. So to do a simple
exponential function represented by "f(N) = N**2":
tie %exp, 'Tie::Math', sub { f(N) = N**2 };
&initialization contains any special cases of the function you need to
define. In the fibonacci example in the SYNOPSIS you have to define
f(0) = 1 and f(1) = 1;
tie %fibo, 'Tie::Math', sub { f(N) = f(N-1) + f(N-2) },
sub { f(0) = 1; f(1) = 1; };
The &initializaion routine is optional.
Each calculation is "memoized" so that for each element of the array
the calculation is only done once.
While the variable N is given by default, A through Z are all
available. Simply import them explicitly:
# Don't forget to import f()
use Tie::Math qw(f X);
There's no real difference which variable you use, its just there for
your preference. (NOTE: I had to use captial letters to avoid
clashing with the y// operator)
EXAMPLE
=======
Display a polynomial equation in a table.
use Tie::Math;
tie %poly, 'Tie::Math', sub { f(N) = N**2 + 2*N + 1 };
print " f(N) = N**2 + 2*N + 1 where N == -3 to 3\n";
print "\t x \t poly\n";
for my $x (-3..3) {
printf "\t % 2d \t % 3d\n", $x, $poly{$x};
}
This should display:
f(N) = N**2 + 2*N + 1 where N == -3 to 3
x poly
-3 4
-2 1
-1 0
0 1
1 4
2 9
3 16
How about Pascal's Triangle!
use Tie::Math qw(f X Y);
my %pascal;
tie %pascal, 'Tie::Math', sub {
if( X <= Y and Y > 0 and X > 0 ) {
f(X,Y) = f(X-1,Y-1) + f(X,Y-1);
}
else {
f(X,Y) = 0;
}
},
sub {
f(1,1) = 1;
f(1,2) = 1;
f(2,2) = 1;
};
#'#
$height = 5;
for my $y (1..$height) {
print " " x ($height - $y);
for my $x (1..$y) {
print $pascal{$x,$y};
}
print "\n";
}
This should produce a nice neat little triangle:
1
1 1
1 2 1
1 3 3 1
1 4 6 4 1
EFFICIENCY
==========
Memoization is automatically employed so no f(X) is calculated twice.
This radically increases efficiency in many cases.
BUGS, CAVAETS and LIMITATIONS
=============================
Certain functions cannot be properly expressed. For example, the
equation defining a circle, f(X) = sqrt(1 - X**2), has two solutions for
each f(X).
There's some horrific hacks in here to make up for the limitations of
the current lvalue subroutine implementation. Namely missing wantlvalue().
This code use the experimental lvalue subroutine feature which will
hopefully change in the future.
The interface is currently very alpha and will probably change in the
near future.
This module BREAKS 5.6.0's DEBUGGER! Neat, eh?
This module uses the old multidimensional hash emulation from the Perl
4 days. While this isn't currently a bad thing, it may eventually be
destined for the junk heap.
AUTHOR
======
Michael G Schwern
TODO
====
Easier ways to set boundries ie. "f(X,Y) = X + Y where X > 0 and Y > 1"
File: pm.info, Node: Tie/MmapArray, Next: Tie/Multidim, Prev: Tie/Math, Up: Module List
mmap a file as a tied array
***************************
NAME
====
Tie::MmapArray - mmap a file as a tied array
SYNOPSIS
========
use Tie::MmapArray;
tie @array, 'Tie::MmapArray', $filename;
tie @array, 'Tie::MmapArray', $filename, $template;
tie @array, 'Tie::MmapArray', $filename, { template => $template,
nels => 0,
mode => "rw",
shared => 1,
offset => 0 };
$len = (tied @array)->record_size;
DESCRIPTION
===========
The Tie::MmapArray module lets you use mmap to map in a file as a perl
array rather than reading the file into dynamically allocated memory. It
depends on your operating system supporting UNIX or POSIX.1b mmap, of
course. (Code to use the equivalent functions on Win32 platforms has been
contributed but has not been tested yet.)
The type of array elements is defined by the template argument or
option. This is a Perl pack()-style template, which defaults to "i". The
template may be an array reference, in which case the elements are defined
by pairs of name and template for each element. A template string may
define multiple fields, in which case that element is regarded as an array
of fields (which need not be of the same type).
The following example shows the utmp file on Linux mapped to an array:
tie @utmp, 'Tie::MmapArray', '/var/log/utmp',
{ mode => "rw",
template => [ ut_type => 's',
ut_pid => 'i', # pid_t
ut_line => 'a12',
ut_id => 'a4',
ut_user => 'a32',
ut_host => 'a256',
ut_exit => [ # struct exit_status
e_termination => 's',
e_exit => 's' ],
ut_session => 'l',
ut_tv => [ # struct timeval
tv_sec => 'l',
tv_usec => 'l' ],
ut_addr_v6 => 'l4',
pad => 'a20' ] };
This can be scanned as follows:
for (my $i = 0; $i < @utmp; $i++) {
printf("pid: %d, user: %s\n",
$utmp[$i]->{ut_pid}, $utmp[$i]->{ut_user});
}
The following subset of pack() template letters is supported:
i
signed integer (default)
I
unsigned integer
c
signed character (one byte integer)
c
unsigned character (one byte integer)
s
signed short integer
S
unsigned short integer
n
unsigned short integer in network byte order
l
signed long integer
L
unsigned long integer
N
unsigned long integer in network byte order
f
float
d
double
aN
fixed-length, null-padded ASCII string of length N
AN
fixed-length, space-padded ASCII string of length N
ZN
fixed-length, null-terminated ASCII string of length N
The size of the array is defined by the *nels* option. If this is zero
then it is calculated as the file size divided by the element size.
If the file size is smaller than the size required for the requested
elements then a single zero byte will be written to the final byte of the
requested size. This seems to prevent the module dying with a
segmentation or bus error if memory is accessed beyond the end of the file
and generally results in a file with holes (unallocated blocks). Precise
details of the behaviour of the module are subject to change.
BUGS, RESTRICTIONS AND FUTURE DIRECTIONS
========================================
This is version 0.02 of the module and there are likely to be many
bugs. The interface may change as the result of feedback.
The options mode and shared are not yet used.
Not all pack letters are implemented yet.
push, pop, shift, unshift, and splice operations are not yet supported.
It is debateable whether they should be as they could be very expensive
if the mmaped file was large (say a Gigabyte or two). Perhaps there
should be an option to explicitly allow these operations.
AUTHOR
======
Andrew Ford , 27 December 1999.
CREDITS
=======
The module was inspired by Malcolm Beatie's Mmap module.
Reini Urban provided intial code for Win32 platforms.
File: pm.info, Node: Tie/Multidim, Next: Tie/NetAddr/IP, Prev: Tie/MmapArray, Up: Module List
"tie"-like multidimensional data structures
*******************************************
NAME
====
Tie::Multidim - "tie"-like multidimensional data structures
SYNOPSIS
========
use Tie::Multidim;
my $foo = new Tie::Multidim \%h, '%@%';
$foo->[2]{'die'}[4] = "isa";
DESCRIPTION
===========
This module implements multi-dimensional data structures on a hash.
`$foo->[2]{'die'}[4]' gets "mapped" to `$bar{"2;die;4"}', where the ';' is
actually $SUBSEP ($;), and %bar is a hash you provide.
It is particularly useful in two, not disjoint, situations:
1. the data space (matrix, if you prefer) is sparsely populated;
2. the hash into which the data is mapped is tied.
This illustrates (1):
my %matrix; # hash to store the data in.
local $; = ' ';
my $foo = new Tie::Multidim \%matrix, '@@'; # array-of-arrays.
print $foo->[5432][9876];
# prints the value of $matrix{"5432 9876"}.
This illustrates (2):
my %matrix;
tie %matrix, 'Matrix'; # some hashtie-able class.
local $; = ";"; # gets remembered by the object.
my $foo = new Tie::Multidim \%matrix, '%@%';
# 3-level structure: hash of arrays of hashes.
$foo->{'human'}[666]{'beast'} = "value";
# causes a call to
sub Matrix::STORE {
my( $self, $index, $value ) = @_;
my( $x, $y, $z ) = split $;, $index;
# with $x = 'human', $y = 666, and $z = 'beast'.
}
METHODS
=======
new
---
This is the constructor.
The first argument is a hash-reference. This hash will be used by the
Tie::Multidim object to actually store the data. The reference can be to
an anonymous hash, to a normal hash, or to a tied hash. Tie::Multidim
doesn't care, as long as it supports the normal hash get and set
operations (STORE and FETCH methods, in TIEHASH terminology).
The second argument is a string containing '@' and '%' characters (a al
function prototypes). The multidimensional data structure will be
constructed to have as many dimensions as there are characters in this
string; and each dimension will be of the type indicated by the character.
'@%' is an array of hashes; '%@' is a hash of arrays; and so on.
storage
-------
This returns the same hash reference that was passed as the first
argument to the constructor. Not exactly a method, it must be called as a
package function, and passed the multidim reference.
$foo = new Tie::Multidim, \%h, '@@';
$hashref = Tie::Multidim::storage( $foo );
# same effect as:
$hashref = \%h;
AUTHOR
======
jdporter@min.net (John Porter)
COPYRIGHT
=========
This module is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.