NAME

Devel::StrictObjectHash - A strict access-controlled hash for debugging objects

SYNOPSIS

    # do nothing
    use Devel::StrictObjectHash;
    
    # replace CORE::GLOBAL::bless
    use Devel::StrictObjectHash strict_bless => 'global';
    
    # turn on debugging
    use Devel::StrictObjectHash debug => 1;
    
    # turn on both
    use Devel::StrictObjectHash (
                        strict_bless => 'global',
                        debug => 1
                        );
    
    # replace bless in these modules only
    use Devel::StrictObjectHash (
                        strict_bless => [ qw(MyModule HisModule HerModule) ]
                        );
                        
    # allow autovivification in routines other than 'new'
    
    # as a string
    use Devel::StrictObjectHash (
                        allow_autovivification_in => "_init"
                        );   
                        
    # as a reg_ex
    use Devel::StrictObjectHash (
                        allow_autovivification_in => qr/create_.*|_init/
                        );                                                                         

DESCRIPTION

NOTE: This code is not finished, I have uploaded it to solicit comments and suggestions. It is under active development, so updates can be expected soon. If you like the idea and would like to see some other features implemented please feel free to email me about them.

The goal of this module is to provide a drop in bless replacement for debugging object field access issues during development. It should never be used in production, as it has performance costs.

What does this module do?

This module implements a tied hash which has OO style access control. It only provides protected style access control for regular hash keys, and private style access control for hash keys that are prefixed with a underscore (_). Currently this does not implement any form of public access.

How do I use this module?

The idea is that you configure this module at the top of your script (or in your mod_perl startup.pl file) to turn it on. Your application will then blow up (die) if you try to access your object fields incorrectly. It will quickly help you to find where someone (possibly you) is doing bad things with your objects.

Do I need to change my code to use this module?

Yes and No.

No - If your code is well written OO code, then you should not have to make any other changes then to load and configure Devel::StrictObjectHash. I have tried (and am trying) to make this object as configurable as possible to cover many styles of hash-based OO code. However, if I am not accomadating your style (and you would like me too), let me know.

Yes - If your OO is not so good and you do things like allow private fields to be accessed by subclasses, or access fields outside of object methods or other such nastiness. Then you will likely either not want to use this module at all, or you will need to recode.

However, if your goal is to recode/refactor "bad-style" OO, then you actually may find this module very useful.

METHODS

strict_bless

This is the method that Devel::StrictObjectHash uses to replace bless with. It can also be used on its own if you like, although it kind of defeats the whole purpose of the module.

Dump

Since this module doesn't play to well with Data::Dumper's Dump method, we supply a replacement method here. This will essentially dump the underlying tied hash that Devel::StrictObjectHash uses.

CAVEATS

Does not work well with Data::Dumper, as it gets caught in the tied hash access routines. Use our Dump instead to see the tied hash that Devel::StrictObjectHash uses.

TO DO

Make access control more flexible

This object does not allow public access at all, which I think is a good thing. But it should allow it as an option for those less paranoid than I.

An option would be to allow the user to somehow define a $PRIVATE_METHOD_REG_EX, $PUBLIC_METHOD_REG_EX, and $PROTECTED_METHOD_REG_EX which I would use to test access controls. A value of undef would mean 'dont check for this'. This would probably be the most flexible, but it could get tricky.

Improve handling of errors

Allow for a choice of die or warn in the reporting of errors. Possibly allow hooking in of something like Log4Perl with warnings/errors.

Fix command-line interface

Ideally you wouldn't even touch your own code at all. But instead, just do something like this:

  perl -MDevel::StrictObjectHash=strict_bless,global,debug,1 my_script.pl
  

And the module would do its magic. But for some reason, that doesn't work, and I have no clue why.

BUGS

Probably plenty of them. This code is an early release to solicit comments and suggestions. If you find a bug, let me know, and I will be sure to fix it.

SEE ALSO

Clearly this module was inspired by Tie::StrictHash. The difference is that Tie::StrictHash is a general purpose hash with access controls, while this module is meant for debugging object field access issues only. It is a more specialized and actually stricter implementation compared to Tie::StrictHash.

AUTHOR

stevan little, <stevan@iinteractive.com>

COPYRIGHT AND LICENSE

Copyright 2004 by Infinity Interactive, Inc.

http://www.iinteractive.com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Devel::StrictObjectHash

perl -MCPAN -e shell
install Devel::StrictObjectHash