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->new($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->new($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
  The problem
    In Perl objects are just variables that have been associated with a
    particular package. Typically they're blessed hashes, or arrays, or
    scalars; occasionally they're darker mysteries, like typeglobs or
    closures. And because they are usually just standard variables, the
    attribute values they store are freely accessible everywhere in a
    program.

    So, even if the object has accessor methods to control how the object's
    attributes are manipulated:

            $obj->set_name("ob1");
            print $obj->get_name();

    it's still possible to access the data directly:

            $obj->{_name} = "ob1";
            print $obj->{_name};

    But if the get_name and set_name methods do anything other than simply
    retrieve and set the underlying hash entryfor example, checking the
    assigned value's validity, or logging retrievalsthen directly accessing
    the data in this way may introduce subtle bugs into the program.

    In practice, this lack of a built-in encapsulation mechanism rarely
    seems to be a problem in Perl. Most object-oriented Perl programmers use
    hashes as the basis of their objects, and get by quite happily with the
    principle of "encapsulation by good manners". The lack of protection for
    attribute values doesn't matter because users of a class either respect
    the official interface of its objects (i.e. their methods), or they're
    smart enough to get away with poking around inside an object without
    breaking anything.

    The only problem is that this culturally enforced encapsulation doesn't
    scale very well. It's fine for a few hundred lines of code written by a
    single programmer, but is less successful when the code is tens of
    thousands of lines long and developed by a group of people. Even if the
    entire team can be trusted to maintain sufficient programming discipline
    and to consistently respect the notional encapsulation of attributes (a
    dubious proposition), accidents and mistakes will happen. Especially in
    rarely used parts of the system.

    Moreover, deliberate decisions to circumvent the conventions of
    encapsulation are rarely documented adequately, leading to problems much
    later in the development cycle. For example, consider a notionally
    "private" attribute of an object, which for efficiency reasons is
    accessed directly in an obscure part of a large system. If the
    implementation of the object's class changes, that attribute may cease
    to exist. In a more static language, this would cause an error message
    to be generated when next some external code attempts to access the (now
    non-existent) attribute. However, Perl's autovivification of hash
    entries will silently "recreate" the former attribute whenever it's
    accessed. The direct access operation proceeds, but now it retrieves or
    modifies a "phantom" attribute. Bugs such as this can be painfully
    difficult to diagnose and track down, especially if the original
    programmer has moved on by the time the problem is discovered.

    Most object-oriented languages provide encapsulation that comes in
    varying strengths. For example, in C++ and Java, object and class data
    members can be declared as "public", "protected", or "private". "Public"
    attributes are available everywhere, "protected" attributes are
    restricted to a particular class hierarchy, and "private" attributes are
    only visible to the current class. Likewise, attributes in Eiffel can be
    given an export list to control which other classes can access them.

    In contrast, other Perl encapsulation techniques (encapsulation via
    closures, and the "Flyweight" patter -- see perltoot and *Object
    Oriented Perl*) are inherently "all-or-nothing" propositions. Every
    attribute is completely encapsulated from the rest of the program. In
    C++/Java terms, they're all "private"; in Eiffel terms, none of them is
    "exported". It's up to the accessor subroutines to provide the necessary
    logic (i.e. die unless $public{$attr} || caller eq $class) to grant
    different levels of access. And, of course, this logic has to be
    manually coded in each encapsulating closure.

    A more significant drawback is that these techniques are moderately hard
    to understand and to code correctly, particularly by beginners, who
    probably benefit most from proper encapsulation. Both techniques are
    based on the closure properties of Perl subroutines, which are not well
    understood by many programmers. Both are most efficiently implemented
    using relatively obscure code, which reduces the maintainability of the
    resulting classes.

    All in all, the costs of building encapsulated classes seem to outweigh
    the benefits. It's hardly surprising that, as elegant as they are, such
    classes are used so rarely. What's really needed is a mechanism that
    will allow objects to be implemented in the usual way (i.e. by blessing
    hashes) and yet enable the implementer to designate some of the
    attributes of the resulting objects as "protected" or "private".

  A limited-access hash
    The Tie::SecureHash module does just that. Hashes that are tied to it
    continue to provide most of the behaviours of a normal hash, but also
    allow their keys to be fully qualifiedas if they were independent
    package variables. The module then uses these key qualifiers to restrict
    the accessibility of the corresponding entries in a tied hash.

    A Tie::SecureHash object (or securehash) can be created by explicitly
    tie'ing an existing hash:

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

    or by calling the module's constructor method:

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

    The constructor version returns a reference to an anonymous hash that
    has been tied to the Tie::SecureHash package, and which has also been
    blessed into the Tie::SecureHash class.

    Either way, a securehash acts like a regular hash, and provides:

    *   access to individual entries using the normal hash access syntaxes:
        $securehash{$key} or "$securehash_ref->{$key}",

    *   iteration through the entire hash: "each %securehash",

    *   lists of keys and values that it currently contains: "keys
        %securehash}, "values %{$securehash_ref}","

    *   existence checks for entries: "exists $securehash_ref->{$key}",

    The module provides object methods corresponding to each of these
    operations: "$securehash_ref->values()", "$securehash_ref->each()",
    "$securehash_ref->exists($key)", etc.

    Securehashes also support deletion of individual entries and direct
    assignment, with some limitations.

  Building objects from securehashes
    When using a securehash as the basis of an object (i.e. blessing it in
    some class's constructor), it's tedious to have to create the hash, tie
    it, and then bless it as well:

            sub MyClass::new {
                    my $class = ref($_[0]) || $_[0];
                    tie my %hash, Tie::SecureHash;
                    my $self = bless \%hash, $class;
        
                    # initialization of attrs here
                        
                    return $self;
            }

    Because securehashes are principally intended as object implementations,
    the Tie::SecureHash module makes process easier by providing the method
    Tie::SecureHash::new. When called with a single argument, this method
    creates a new securehash (i.e. ties an ordinary anonymous hash to the
    Tie::SecureHash package) and then blesses it into the class named by
    argument (or into the same class as the argument, if it's an object
    reference). That simplifies MyClass::new to this:

            sub MyClass::new {
                    my $self = Tie::SecureHash->new($_[0]);
                        
                    # initialization of attrs here
                        
                    return $self;
            }

  Declaring securehash entries
    Both versions of MyClass::new shown above leave space for
    initialization. That's because the various entries of a securehash have
    to be explicitly "declared" before they can be used. In other words,
    securehash entries aren't autovivifying.

    This may seem inconvenient at first, but it actually saves an inordinate
    amount of time and effort tracking down "spelling bugs" like this:

            package Disk::Recovery;
        
            sub new {
                    my ($class, @files) = @_;
                    bless {
                            _retrieved  => [ @files ],
                            _attempts   => 0,
                            _wierd_data => undef,
                    }, $class;
            }
        
            sub report {
                    print "Made $self->{_attempts} attempts to recover:\n";
                    print "\t$_\n" foreach (@{self->{retreived}})
                    print "Failed (weird data)\n" if $self->{_weird_data};
            }

    Unlike the regular hash in the above example, the entries of a
    securehash can't be accessed until they've been "created". A specific
    entry is created by referring to it using a qualified key, which is a
    key string consisting of any characters except ':', preceded by a
    standard Perl package qualifier. The following table illustrates some
    typical qualified keys:

            Qualified key           Actual key      Qualifier
            =============           ==========      =========
            'Class::key             'key'           'Class::'
            'Class::a key'          'a key',        'Class::'
            'My::CD::_tracks'       '_tracks'       'My::CD::'
            'Railway::_tracks'      '_tracks'       'Railway::'
            'Crypt::__passwd'       '__passwd'      'Crypt::'
            'main::key_berm'        'key_berm'      'main::'
            '::key_berm'            'key_berm'      'main::'

    Each qualifier indicates the package that "owns" the key. Hence, the
    first two keys above are owned by class Class and the last two by the
    main package.

    Qualified keys that have the same key but different qualifiers (for
    example, 'Railway::_tracks' and 'My::CD::_tracks') are treated as being
    distinct, even if they label two entries in the same securehash.

    Typically, entries in a securehash are created by referring to their
    fully-qualified names at some point in a class's constructor:

            sub MyClass::new {
                    my $self = Tie::SecureHash->new($_[0]);
                        
                    $self->{MyClass::attr1}  = $_[1];
                    $self->{MyClass::_attr2} = $_[2];
                    $self->{MyClass::__attr3}= $_[3];
                        
                    return $self;
            }

    In this case, the entries with the keys "attr1", "_attr2", and "__attr3"
    are all "owned" by the class MyClass. For reasons that will be made
    clear in the next section, an entry must be declared within its owner's
    package. In practice, that means that the qualifier for any entry
    declaration will always be the name of the current package, as in the
    example above.

    Key qualifiers are only required during the creation of entries (and
    occasionally to resolve ambiguities). After the declarations, they can
    usually be ignored:

            sub MyClass::set_attr2 {
                    my ($self, $newval) = @_;
                    $self->{_attr2} = $newval if @_>1;
            }

    though using the fully qualified key is always acceptable:

            sub MyClass::set_attr2 {
                    my ($self, $newval) = @_;
                    $self->{MyClass::_attr2} = $newval if @_>1;
            }

  Easier initialization
    It's annoying to have to repeat the same class name when declaring each
    attribute in the constructor, so Tie::SecureHash allows
    Tie::SecureHash::new to take extra parameters which declare attributes
    without individual qualifiers. Or rather, the qualifier for each
    attribute passed to "new" is assumed to be the class name that is passed
    as the first argument.

    For example, the constructor for MyClass could also be written like
    this:

            sub MyClass::new {
                    my $self = Tie::SecureHash->new($_[0],
                                                    attr1   => $_[1],
                                                    _attr2  => $_[2],
                                                    __attr3 => $_[3],
                    );
            }

    This is the only way that entries can be declared without an explicit
    qualifier.

  Access constraints
    Securehashes use an extension of a common Perl custom -- underscoring --
    to determine the accessibility of their various entries. In Perl, a
    leading underscore in the key of an entry suggests that the particular
    entry is "not for public use". Tie::SecureHash formalizes that idea by
    treating any entry whose key begins with a single underscore as being
    inaccessible outside its owner's class hierarchy. In other words, an
    underscored key indicates a "protected" method.

    Tie::SecureHash treats keys that begin with two (or more) underscores
    even more carefully. The entries for such keys are only accessible from
    code in their owner's package and in the same file as they were
    originally declared. In other words, a double underscored key indicates
    a "private" and "pseudo-lexical" key.

    The only other possibility is a key with no leading underscore.
    Predictably, no underscore indicates that an entry is "public" and
    universally accessible.

    This is reasonably consistent with existing Perl conventions about key
    naming, but the important difference is that securehashes enforce the
    convention at run-time. If a doubly-underscored key is accessed outside
    its owner's package or its declaration file, an exception is immediately
    thrown. The same thing happens if a singly-underscored key is accessed
    outside its native class hierarchy. For example:

            package Derived::Class;
            @ISA = qw( MyClass );
        
            sub dump {
                    my ($self) = @_;
                    print $self->{attr1};    # okay
                    print $self->{_attr2};   # okay
                    print $self->{__attr3};  # error
            }

    The first "print" is okay because the lack of a leading underscore
    indicates that 'attr1' is a public attribute, accessible from any
    package. The second "print" is okay too because the single leading
    underscore indicates that '_attr2' is a protected attribute, accessible
    for any package in Class's hierarchy. But the last "print" tries to
    access an attribute with two leading underscores, causing the exception:

            Private key 'MyClass::__attr3' of tied SecureHash
            is inaccessible from package Derived::Class.

    Likewise, an access attempt such as:

            package main;
            my $obj = MyClass->new();
            print $obj->{_attr2};

    would die with the message:

            Protected key 'MyClass::_attr2' of tied SecureHash
            is inaccessible from package main

    (unless "main" inherits from "MyClass", of course).

    Access constraints also apply to the functions "each", "keys", "values",
    and "delete", when applied to securehashes. A key will only be iterated,
    listed, or deleted if it is accessible at the point where the operation
    is invoked.

    This also has implications for direct assignment to a securehash. A
    statement such as:

            %securehash = ();

    is equivalent to a series of "delete" operations, and hence will only
    succeed if every key in the securehash is accessible from that point. If
    any key is inaccessible, an exception will be thrown (and the securehash
    will be unchanged).

    Another difficulty with reassigning a securehash is that every new key
    being assigned must be appropriately qualified with the name of the
    current package. In other words, the standard securehash entry
    declaration rules still apply. For example:

            package SomeClass;
            %securehash = (
                    attr1 => $val1,
                    attr2 => $val2,
            );

    will throw an exception because the keys 'attr1' and 'attr2' don't exist
    in the newly-cleared %securehash. To successfully reinitialize the
    securehash, each new key requires a fully qualified name:

            package SomeClass;
            %securehash = (
                    SomeClass::attr1 => $val1,
                    SomeClass::attr2 => $val2,
            );

  Ambiguous keys in a securehash
    The ability to access securehash entries by unqualified keys is an
    important convenience. It can also be a useful programming technique
    when using inheritance, since it provides "polymorphic" attributes (see
    below). But it creates problems under some circumstances.

    The convenience aspect is obvious. Requiring that securehash keys always
    be fully qualified would flout the cardinal virtue of Laziness. No-one
    would want to use a securehash if they always had to write
    "$self->{MyClass::__attr3}", instead of just "$self->{__attr3}". In most
    cases, each attribute of an object will be uniquely named, so each
    securehash will contain only a single matching unqualified key. The
    qualifier would be redundant and annoying.

    Inheritance, however, brings a difficulty known as the "data inheritance
    problem". When one class inherits from another, it's all too easy to
    accidentally reuse the name of a base class attribute in a derived
    class. For example:

            package Settable;
            $VERSION = 1.00;        #uses normal hashes
        
            sub new {
                    my ($class, $is_set) = @_;
                    my $self = {_set => $is_set};
                    bless $self, $class;
            }
        
            sub set {
                    my ($self) = @_;
                    # access Settable's _set attr
                    $self->{_set} = 1;
            }
        
            package Set;
            @ISA = qw( Settable );
        
            sub new {
                    my ($class, %items) = @_;
                    my $self = $class->SUPER::new();
                    $self->{_set} = { %items }
                    # Oops!
            }
        
            sub list {
                    my ($self) = @_;
                    print keys %{$self->{_set}};
                    # Err...was that Set's '_set'
                    # or Settable's '_set'?
            }

    The problem is both Settable and Set want to use a '_set' entry, but Set
    objects have to share the same hash as their Settable base parts, and
    hence there can be only one such entry.

    The use of qualified keys in a securehash solves the problem (in fact,
    it's the same solution as suggested in Perl Cookbook):

            package Settable;
            $VERSION = 2.00;        #uses securehashes
        
            sub new {
                    my ($class, $set) = @_;
                    my $self = Tie::SecureHash->new($class);
                    $self->{Settable::_set} = $set;
                    return $self;
            }
        
        
            sub set {
                    my ($self) = @_;
                    $self->{Settable::_set} = 1;
                    # Definitely Settable's _set
            }
        
            package Set;
            @ISA = qw( Settable );
        
            sub new {
                    my ($class, %items) = @_;
                    my $self = $class->SUPER::new();
                    $self->{Set::_set} = { %items };
                    # Different key so no "collision"
            }
        
            sub list {
                    my ($self) = @_;
                    print keys %{$self->{Set::_set}};
                    # Definitely Set's _set
            }

    But securehashes are even smarter than that. Any qualifier/key
    combination that is unique creates an entry whose unqualified key is
    unique within its owner's namespace. So it's also possible to write:

            package Settable;
            $VERSION = 3.00;        #uses securehashes
        
            sub new {
                    my ($class, $set) = @_;
                    my $self = Tie::SecureHash->new($class);
                    $self->{Settable::_set} = $set;
                    return $self;
            }
        
            sub set {
                    my ($self) = @_;
                    $self->{_set} = 1;
                    # Definitely Settable's '_set' (!)
            }
        
            package Set;
            @ISA = qw( Settable );
        
            sub new {
                    my ($class, %items) = @_;
                    my $self = $class->SUPER::new();
                    $self->{Set::_set} = { %items };
                    # Different key so no "collision"
            }
        
            sub list {
                    my ($self) = @_;
                    print keys %{$self->{_set}};
                    # Definitely Set's _set (!)
            }

    The unqualified keys are unambiguous because the Tie::SecureHash module
    keeps track of where an access was requested, and works out which key
    was intended from that context. When the "Set::list" accesses the '_set'
    key, it probably wants the entry for 'Set::_set', not 'Settable::_set'.
    The securehash is aware of the context of the access and returns the
    correct attribute.

    Another way of looking at it is to think of securehash entries that are
    defined in a base class as being "hidden" by derived class entries of
    the same name (just like inherited attributes are in most other
    object-oriented languages). Of course, if the inherited entry is needed
    in a derived class method, it can still be accessed by fully qualifying
    it:

            sub Set::list {
                    my ($self) = @_;
                    print keys %{$self->{_set}}
                    if $self->{Settable::_set};
            }

    That's not to say that a securehash can always correctly guess the
    intended entry for an unqualified key. Consider the following two
    classes:

            package Chemical;
        
            sub new {
                    my ($class, $chemname) = @_;
                    Tie::SecureHash->new($class, name => $chemname);
            }
        
            package Medicine;
            @ISA = qw( Chemical );
        
            sub new {
                    my ($class, $medname, $chemname) = @_;
                    my $self = Chemical->new($class, $chemname);
                    $self->{Medicine::name} = $medname;
                    return $self;
            }

    Within the Chemical class, the unqualified public key 'name' will always
    be assumed to be referring to 'Chemical::name'. Similarly, inside any of
    Medicine's methods, the same key is unambiguously resolved to
    'Medicine::name'. But what about accesses from the main package? For
    example:

            package main;
            my $medicine =  Medicine->new("Dydroxifen","dihydrogen oxide");
            print $medicine->{name};

    Since the 'name' entry isn't being accessed from a method of either
    class, there's no way to decide which entry was intended.
    Tie::SecureHash resolves the ambiguity by immediately throwing an
    exception.

    The solution is to explicitly qualify any ambiguous case:

            print $medicine->{Medicine::name};

    Problems of a similar type occur with protected keys as well, whenever a
    class inherits from two or more classes. If both classes use a protected
    attribute of the same name then, in a class than derives from both, it's
    impossible to tell which inherited attribute was intended:

            package Dessert::Topping;
        
            sub new { Tie::SecureHash->new($_[0], _shaken => 0) }
        
            sub shake { $_[0]->{_shaken} = 1 }
        
        
            package Floor::Wax;
        
            sub new { Tie::SecureHash->new($_[0], _shaken => 0 ) }
        
            sub shake { $_[0]->{_shaken}++ }
        
        
            package Jiffy::Whip;
            @ISA = qw(Dessert::Topping Floor::Wax);
        
            sub shaken { $_[0]->{_shaken} }     # Dessert::Topping's '_shaken'
                                                # orFloor::Wax's '_shaken'?

    Once again, since it can't decide which of the two attributes was
    intended, Tie::SecureHash simply throws an exception.

  Debugging a securehash
    In a more complicated hierarchy than the ones shown above, ambiguities
    can be quite difficult to detect and defuse. The Tie::SecureHash module
    provides a method (named "debug") that can be called to dump the
    contents of a securehash to "STDERR". The debug method can be called on
    any securehash -- regardless of the class into which it's been blessed
    -- with an explicit method call:

            sub Jiffy::Whip::shaken {
                    my ($self) = @_;
                    $self->Tie::SecureHash::debug();   # Find the source...
                    return $self->{_shaken};           # ...of this problem:
            }

    Tie::SecureHash::debug reports the current location details (package,
    file, line and subroutine) and the key and value of each entry of the
    securehash, categorized by owner. More importantly, debug reports the
    accessibility of each entry at the point where it was called (either
    "accessible", "inaccessible", or "ambiguous") and explains why.

   More Debugging
    Sometimes you want to disable Tie::SecureHash's features. See the CPAN
    module Tie::InSecureHash for one approach.

  "Fast" securehashes
    Securehashes provide an easy means of controlling the accessibility of
    object attributes on a per-attribute basis. Unfortunately, that ease and
    flexibility comes at a cost. For a start, accessing the entries of any
    kind of tied hash is significantly slower that for untied hashes, often
    taking 5 to 10 times as long per access. On top of that performance hit,
    securehashes have to perform some moderately expensive tests (involving
    the "Universal::isa" subroutine) before they can grant access to an
    entry. These tests can double the cost again, so accesses to
    securehashes are often 10 and 20 times slower than to untied hash. That
    makes the use of securehashes impractical in most production code.

    Fortunately, production code doesn't actually need the security of
    encapsulation. That's because all that checking of access restrictions
    is only actually required when a piece of code incorrectly attempts to
    violate those restrictions. Since production code is always thoroughly
    tested (ahem!), such bugs will have been caught and eliminated, so the
    checks are redundant. In other words, if no one can ever break the law,
    you no longer need any police to enforce it.

    Thus, the solution is to develop the application using Tie::SecureHash
    to enforce proper encapsulation, test it thoroughly to ensure that there
    are no improper accesses anywhere in the code, and then optimize the
    final code by converting every securehash to a normal hash.

    Because a securehash's interface mimics the interface of a regular hash,
    converting from securehashes to the regular kind is surprisingly easy.
    It's not necessary to change any of the code that accesses a securehash,
    only the code that creates it. In fact, that's exactly what
    encapsulation is all about: hiding implementation details behind a
    standard interface so that client code doesn't have to worry when those
    details change.

    Of course, in the typical large application where encapsulation is most
    useful, hunting for every situation where a securehash is created and
    then replacing it with a regular hash could still be time-consuming and
    error-prone. Fortunately, even that isn't necessary.

    Tie::Securehash provides a special "fast" mode, in which a call to
    Tie::SecureHash::new returns a reference to an ordinary hash, rather
    than to a securehash. Hence, in "fast" mode, there's no need to replace
    any code like:

            $self = Tie::SecureHash->new($_[0]);

    because it correctly adjusts its behaviour automatically.

    Of course, that doesn't solve the problem of any "raw" tie-ing:

            tie %$self, Tie::SecureHash;

    but that's just another reason to use Tie::SecureHash::new instead.
    Indeed, in "fast" mode, Tie::SecureHash generates a warning whenever a
    raw tie such as this is used.

    "Fast" mode is enabled by importing the entire module with an extra
    argument:

            use Tie::SecureHash "fast";

  "Strict" securehashes
    This "develop-with-restrictions-then-run-without-them" approach works
    well, but there are two caveats: "Tie::SecureHash::new" must always be
    used to create securehashes, and unqualified keys can never be used to
    access them.

    The need to use "Tie::SecureHash::new" was explained above:
    "Tie::SecureHash::new" knows about "fast" mode and can adjust for it,
    but the in-built "tie" function doesn't and can't.

    The second caveat imposes a more significant restriction. One of the
    useful features of a securehash is that, once an entry has been declared
    with its full qualifier, any code can refer to it without the qualifier
    and expect the securehash to do the right thing in all unambiguous
    cases. However, when the securehash is replaced with a regular hash,
    that "do what I mean" intelligence disappears. That can lead to subtle
    bugs, because regular hashes autovivify and will happily create
    unrelated entries when both qualified and unqualified versions of a key
    are used.

    These two restrictions are not particularly onerous, but they can be
    difficult to apply consistently in a large application. To make
    conversion to "fast" mode easier, Tie::SecureHash offers another mode,
    called "strict". Like "fast" mode, this mode can be invoked by importing
    the module with the appropriate argument:

            use Tie::SecureHash "strict";

    In "strict" mode, securehashes control access in their normal way,
    except that they also produce warnings whenever a hash is explicitly
    tied to Tie::SecureHash, and whenever an unqualified key is used to
    access a securehash. Thus, code that uses securehashes and runs without
    warnings in "strict" mode is guaranteed to have the same behaviour in
    "fast" mode.

  The formal access rules
    The access rules for a securehash are designed to provide secure
    encapsulation with minimal inconvenience and maximal intuitiveness.
    However, to produce this appearance of intelligence, the formal access
    rules are quite complicated...

    All entries

        *   No entry for an unqualified key is autovivifying. Each entry
            must be declared before it's used. Qualified keys do autovivify
            their entry, so an entry may be declared as part of its initial
            use.

        *   The key of each entry must be explicitly qualified (in the form
            "*owner*::*key*") when entry is declared.

        *   An entry is owned by the package whose name was used as the
            explicit qualifier in its declaration.

        *   Entries must be declared within of their owner's package.

        *   An unqualified key is always interpreted as referring to the key
            owned by the current package, if such a key exists, no matter
            how many other accessible matching keys the hash may also
            contain.

        *   Otherwise, accesses through an unqualified key throw an
            exception if the number of accessible matching keys in the
            securehash is not 1 (either "key does not exist" if the number
            is zero, or "key is ambiguous" if it is greater than 1).

        *   A fully qualified key is never ambiguous (though it may be
            non-existent, or inaccessible from a particular package).

    Public entries

        *   Public accessibility of entries is indicated by their
            unqualified key beginning with a character other than an
            underscore.

        *   Public entries may be subsequently accessed from any package in
            any source file.

        *   A public entry's key is ambiguous if it is not explicitly
            qualified, and there is not a matching key owned by the current
            package, and there exist two or more matching unqualified keys
            owned by any other packages.

    Protected entries

        *   Protected accessibility of entries is indicated by their
            unqualified key beginning with a single underscore.

        *   Protected entries may subsequently be accessed from any package
            ("P") in any source file, provided that at the point of access,
            "P" is (or inherits from) the entry's owner package (<Owner>).
            That is, a protected entry is accessible in any package "P",
            where "P->isa("Owner")".

        *   Protected keys that are declared to be owned by a given package
            will "hide" entries with the same unqualified key that are
            inherited from parent classes of that package. Any inherited
            entry that is hidden in this way is inaccessible from the scope
            of the derived class (unless accessed via a qualified key).

        *   A protected key is ambiguous if it's not explicitly qualified,
            and there is not a matching key owned by the current package,
            and there exist two or more accessible matching keys owned by
            two or more other packages, and those other packages are
            inherited by the current package through two distinct
            inheritance paths.

    Private entries

        *   Private accessibility of entries is indicated by their
            unqualified key beginning with two or more underscores.

        *   Private entries can be accessed only from within their owner's
            package, and only from the source file in which they were
            originally declared.

        *   Unqualified private keys are never ambiguous. Since private
            entries are only ever accessible from a single class, there can
            be at most only one accessible matching private key.

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 their "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 if the environment variable
        UNSAFE_WARN is true, 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.

REPOSITORY
    <https://github.com/singingfish/perl-Tie-SecureHash.git>

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)

POD ERRORS
    Hey! The above document had some coding errors, which are explained
    below:

    Around line 655:
        Unterminated C<...> sequence

    Around line 1156:
        Unterminated L<...> sequence

    Around line 1494:
        You forgot a '=back' before '=head1'

