From: Randy J Ray Date: Tue, 6 Feb 1996 17:04:47 +0000 (-0700) Subject: Documentation patch: Tie::Hash, Tie::Scalar, Tie::SubstrHash X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=64d0c9732b520ac8f3a9448f7c3f9f5b4209bd6d;p=p5sagit%2Fp5-mst-13.2.git Documentation patch: Tie::Hash, Tie::Scalar, Tie::SubstrHash [This finishes a job started by Randy Ray with perl5.002b1f.] This patch updates the files lib/TieHash.pm and lib/SubstrHash.pm. Those two files are moved to a new directory called lib/Tie. A new tie-related class for scalars, lib/Tie/Scalar.pm, is added. Each of these has pod documentation that passes through pod2man without complaint. All package names are updated to reflect this structure, and the "standard" sub-classes for hashes and scalars are named Tie::StdHash and Tie::StdScalar, in keeping with the group consensus. With this, the documentation for Tie::Hash should be fine, Tie::Scalar exists and is documented, and Tie::SubstrHash (formerly just SubstrHash) is also documented, albeit weakly. I have no examples of usage to show, and I suspect a possible bug or two, but without examples it's hard to say. As it happens, this patch also impacts the DBM-style extensions, as they (DB_File, NDBM_File, GBM_File, ODBM_File, SDBM_File) all inherited from the old TieHash.pm as a base class. --- diff --git a/lib/Tie/Hash.pm b/lib/Tie/Hash.pm index 161771a..9a9d059 100644 --- a/lib/Tie/Hash.pm +++ b/lib/Tie/Hash.pm @@ -1,24 +1,24 @@ -package TieHash; +package Tie::Hash; =head1 NAME -TieHash, TieHash::Std - base class definitions for tied hashes +Tie::Hash, Tie::StdHash - base class definitions for tied hashes =head1 SYNOPSIS package NewHash; - require TieHash; + require Tie::Hash; - @ISA = (TieHash); + @ISA = (Tie::Hash); sub DELETE { ... } # Provides needed method sub CLEAR { ... } # Overrides inherited method package NewStdHash; - require TieHash; + require Tie::Hash; - @ISA = (TieHash::Std); + @ISA = (Tie::StdHash); # All methods provided by default, define only those needing overrides sub DELETE { ... } @@ -32,20 +32,23 @@ TieHash, TieHash::Std - base class definitions for tied hashes =head1 DESCRIPTION This module provides some skeletal methods for hash-tying classes. See -L for a list of the functions required in order to tie a hash -to a package. The basic B package provides a C method, as well -as methods C, C and C. The B package -provides most methods required for hashes in L. It inherits from -B, and causes tied hashes to behave exactly like standard hashes, -allowing for selective overloading of methods. The B method is provided -as grandfathering in the case a class forgets to include a B method. +L for a list of the functions required in order to tie a hash +to a package. The basic B package provides a C method, as well +as methods C, C and C. The B package +provides most methods required for hashes in L. It inherits from +B, and causes tied hashes to behave exactly like standard hashes, +allowing for selective overloading of methods. The C method is provided +as grandfathering in the case a class forgets to include a C method. For developers wishing to write their own tied hashes, the required methods -are: +are briefly defined below. See the L section for more detailed +descriptive, as well as example code: + +=over =item TIEHASH classname, LIST -The method invoked by the command C. Associates a new +The method invoked by the command C. Associates a new hash instance with the specified class. C would represent additional arguments (along the lines of L and compatriots) needed to complete the association. @@ -82,18 +85,16 @@ Clear all values from the tied hash I. =head1 CAVEATS -The L documentation includes a method called C as -a necessary method for tied hashes. Neither B nor B -define a default for this method. - -The C method provided by these two packages is not listed in the -L section. +The L documentation includes a method called C as +a necessary method for tied hashes. Neither B nor B +define a default for this method. This is a standard for class packages, +but may be omitted in favor of a simple default. =head1 MORE INFORMATION The packages relating to various DBM-related implemetations (F, F, etc.) show examples of general tied hashes, as does the -L module. While these do not utilize B, they serve as +L module. While these do not utilize B, they serve as good working examples. =cut @@ -138,12 +139,12 @@ sub CLEAR { } } -# The TieHash::Std package implements standard perl hash behaviour. +# The Tie::StdHash package implements standard perl hash behaviour. # It exists to act as a base class for classes which only wish to # alter some parts of their behaviour. -package TieHash::Std; -@ISA = qw(TieHash); +package Tie::StdHash; +@ISA = qw(Tie::Hash); sub TIEHASH { bless {}, $_[0] } sub STORE { $_[0]->{$_[1]} = $_[2] } diff --git a/lib/Tie/Scalar.pm b/lib/Tie/Scalar.pm new file mode 100644 index 0000000..2db02ae --- /dev/null +++ b/lib/Tie/Scalar.pm @@ -0,0 +1,138 @@ +package Tie::Scalar; + +=head1 NAME + +Tie::Scalar, Tie::StdScalar - base class definitions for tied scalars + +=head1 SYNOPSIS + + package NewScalar; + require Tie::Scalar; + + @ISA = (Tie::Scalar); + + sub FETCH { ... } # Provide a needed method + sub TIESCALAR { ... } # Overrides inherited method + + + package NewStdScalar; + require Tie::Scalar; + + @ISA = (Tie::StdScalar); + + # All methods provided by default, so define only what needs be overridden + sub FETCH { ... } + + + package main; + + tie $new_scalar, NewScalar; + tie $new_std_scalar, NewStdScalar; + +=head1 DESCRIPTION + +This module provides some skeletal methods for scalar-tying classes. See +L for a list of the functions required in tying a scalar to a +package. The basic B package provides a C method, as well +as methods C, C and C. The B +package provides all the methods specified in L. It inherits from +B and causes scalars tied to it to behave exactly like the +built-in scalars, allowing for selective overloading of methods. The C +method is provided as a means of grandfathering, for classes that forget to +provide their own C method. + +For developers wishing to write their own tied-scalar classes, the methods +are summarized below. The L section not only documents these, but +has sample code as well: + +=over + +=item TIESCALAR classname, LIST + +The method invoked by the command C. Associates a new +scalar instance with the specified class. C would represent additional +arguments (along the lines of L and compatriots) needed to +complete the association. + +=item FETCH this + +Retrieve the value of the tied scalar referenced by I. + +=item STORE this, value + +Store data I in the tied scalar referenced by I. + +=item DESTROY this + +Free the storage associated with the tied scalar referenced by I. +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. + +=back + +=head1 MORE INFORMATION + +The L section uses a good example of tying scalars by associating +process IDs with priority. + +=cut + +use Carp; + +sub new { + my $pkg = shift; + $pkg->TIESCALAR(@_); +} + +# "Grandfather" the new, a la Tie::Hash + +sub TIESCALAR { + my $pkg = shift; + if (defined &{"{$pkg}::new"}) { + carp "WARNING: calling ${pkg}->new since ${pkg}->TIESCALAR is missing" + if $^W; + $pkg->new(@_); + } + else { + croak "$pkg doesn't define a TIESCALAR method"; + } +} + +sub FETCH { + my $pkg = ref $_[0]; + croak "$pkg doesn't define a FETCH method"; +} + +sub STORE { + my $pkg = ref $_[0]; + croak "$pkg doesn't define a STORE method"; +} + +# +# The Tie::StdScalar package provides scalars that behave exactly like +# Perl's built-in scalars. Good base to inherit from, if you're only going to +# tweak a small bit. +# +package Tie::StdScalar; +@ISA = (Tie::Scalar); + +sub TIESCALAR { + my $class = shift; + my $instance = shift || undef; + return bless \$instance => $class; +} + +sub FETCH { + return ${$_[0]}; +} + +sub STORE { + ${$_[0]} = $_[1]; +} + +sub DESTROY { + undef ${$_[0]}; +} + +1; diff --git a/lib/Tie/SubstrHash.pm b/lib/Tie/SubstrHash.pm index 6250e73..a01c66e 100644 --- a/lib/Tie/SubstrHash.pm +++ b/lib/Tie/SubstrHash.pm @@ -1,4 +1,40 @@ -package SubstrHash; +package Tie::SubstrHash; + +=head1 NAME + +Tie::SubstrHash - Fixed-table-size, fixed-key-length hashing + +=head1 SYNOPSIS + + require Tie::SubstrHash; + + tie %myhash, Tie::SubstrHash, $key_len, $value_len, $table_size; + +=head1 DESCRIPTION + +The B package provides a hash-table-like interface to +an array of determinate size, with constant key size and record size. + +Upon tying a new hash to this package, the developer must specify the +size of the keys that will be used, the size of the value fields that the +keys will index, and the size of the overall table (in terms of key-value +pairs, not size in hard memory). I. The newly-allocated hash table may now have +data stored and retrieved. Efforts to store more than C<$table_size> +elements will result in a fatal error, as will efforts to store a value +not exactly C<$value_len> characters in length, or reference through a +key not exactly C<$key_len> characters in length. While these constraints +may seem excessive, the result is a hash table using much less internal +memory than an equivalent freely-allocated hash table. + +=head1 CAVEATS + +Because the current implementation uses the table and key sizes for the +hashing algorithm, there is no means by which to dynamically change the +value of any of the initialization parameters. + +=cut + use Carp; sub TIEHASH {