NAME

Tie::SecureHash - A tied hash that supports namespace-based encapsulation

VERSION

This document describes version 1.00 of Tie::SecureHash, released December 3, 1998

SYNOPSIS

    use Tie::SecureHash;

    # CREATE A SECURE HASH

        my %hash;
        tie %hash, Tie::SecureHash;

    # CREATE A REFERENCE TO A SECURE HASH (BLESSED INTO Tie::SecureHash!)

        my $hashref = Tie::SecureHash->new();

    # CREATE A REFERENCE TO A SECURE HASH (BLESSED INTO $some_other_class)

        my $hashref = Tie::SecureHash->new($some_other_class);

    # CREATE NEW ENTRIES IN THE HASH

        package MyClass;

        sub new
        {
                my ($class, %args) = @_
                my $self = Tie::SecureHash->($class);

                $self->{MyClass::public}     = $args{public};
                $self->{MyClass::_protected} = $args{protected};
                $self->{MyClass::__private}  = $args{private};

                return $self;
        }

    # SAME EFFECT, EASIER SYNTAX...

        package MyClass;

        sub new
        {
                my ($class, %args) = @_
                my $self = Tie::SecureHash->($class,
                                public     => $args{public},
                                _protected => $args{protected},
                                __private  => $args{private},
                                );

                return $self;
        }


    # ACCESS RESTRICTIONS ON ENTRIES

        package MyClass;

        sub print_attributes
        {
            my $self = $_[0];
                                        # OKAY? (ACCESSIBLE WHERE?)

            print $self->{public};      #  YES  (ANYWHERE)
            print $self->{_protected};  #  YES  (ONLY IN MyClass HIERARCHY)
            print $self->{__private};   #  YES  (ONLY IN MyClass)
        }


        package SonOfMyClass; @ISA = qw( MyClass );

        sub print_attributes
        {
            my $self = $_[0];
                                        # OKAY? (ACCESSIBLE WHERE?)

            print $self->{public};      #  YES  (ANYWHERE)
            print $self->{_protected};  #  YES  (ONLY IN MyClass HIERARCHY)
            print $self->{__private};   #  NO!  (ONLY IN MyClass)
        }


        package main;

        my $object = MyClass->new();
                                        # OKAY? (ACCESSIBLE WHERE?)

        print $object->{public};        #  YES  (ANYWHERE)
        print $object->{_protected};    #  NO!  (ONLY IN MyClass HIERARCHY)
        print $object->{__private};     #  NO!  (ONLY IN MyClass)


    # DEBUGGING

        $object->Tie::SecureHash::debug();

DESCRIPTION

[Coming soon]

DIAGNOSTICS

Private key %s of tied securehash inaccessible from package %s

Private keys can only be accessed from their "owner" package. An attempt was made to access a private key from some other package.

Private key %s of tied securehash inaccessible from file %s

Private keys can only be accessed from the lexical scope of the file in which they were originally declared. An attempt was made to access a private key from some lexical scope (probably another file, but perhaps an eval).

Protected key %s of tied securehash inaccessible from package %s

Protected keys can only be accessed from theie "owner" package and any of its subclasses. An attempt was made to access a protected key from some package not in the owner's inheritance hierarchy.

Entry for key %s of tied securehash cannot be created from package %s

Keys must be declared from within the lexical scope of their owner's package. In other words, the qualifier for a key declaration must be the same as the current package. An attempt was made to declare a key from some package other than its owner.

Private key %s does not exist in tied securehash

Securehash keys are not autovivifying; they must be declared using a fully qualified key before they can be used. An attempt was made to access or assign to an unqualified private key (one with two leading underscores), before the corresponding fully qualified key was declared.

Protected key %s does not exist in tied securehash

Securehash keys are not autovivifying; they must be declared using a fully qualified key before they can be used. An attempt was made to access or assign to an unqualified protected key (one with a single leading underscore), before the corresponding fully qualified key was declared.

Public key %s does not exist in tied securehash

Securehash keys are not autovivifying; they must be declared using a fully qualified key before they can be used. An attempt was made to access or assign to an unqualified public key (one with no leading underscore), before the corresponding fully qualified key was declared.

Ambiguous key %s (when accessed from package %s). Could be: %s

An unqualified key was used to access the securehash, but it was ambiguous in the context. The error message lists the set of fully qualified keys that might have matched.

Invalid key %s

An attempt was made to access the securehash (or declare a key) through an improperly formatted key. This almost always means that the qualifier isn't a valid package name.

%s can't be both "strict" and "fast"

Tie::SecureHash detected that both the $Tie::SecureHash::strict and $Tie::SecureHash::fast keys were set. But the two modes are mutually exclusive.

Accessing securehash via unqualified key %s will be unsafe in 'fast' mode. Use %s::%s

This warning is issued in "strict" mode, and points out an access attempt which will break if the code is converted to "fast" mode.

Tie'ing a securehash directly will circumvent 'fast' mode. Use Tie::SecureHash::new instead

This warning is issued in "strict" mode, and points out an explicit tie to the Tie::SecureHash module. Hashes tied in this way will not speed up under "fast" mode.

Tie'ing a securehash directly should never happen in 'fast' mode. Use Tie::SecureHash::new instead

This warning is issued in "fast" mode, and points out an explicit tie to the Tie::SecureHash module. Hashes tied in this way will still be slow. This diagnostic can be turned off by setting $Tie::SecureHash::fast to any value other than 1.

Unable to assign to securehash because the following existing keys are inaccessible from package %s and cannot be deleted: %s

An attempt was made to assign a completely new set of entries to a securehash. Typically something like this:

        %securehash = ();

This doesn't work unless all the existing keys are accessible at the point of the assignment.

AUTHOR

Damian Conway (damian@cs.monash.edu.au)

BUGS AND IRRITATIONS

There are undoubtedly serious bugs lurking somewhere in this code :-) Bug reports and other feedback are most welcome.

COPYRIGHT

        Copyright (c) 1998-2000, Damian Conway. All Rights Reserved.
      This module is free software. It may be used, redistributed
      and/or modified under the terms of the Perl Artistic License
           (see http://www.perl.com/perl/misc/Artistic.html)