/ 
OOB-1.00
River stage one • 1 direct dependent • 1 total dependent
/ OOB

NAME

OOB - out of band data for any data structure in Perl

VERSION

This documentation describes version 1.00.

SYNOPSIS

# object oriented interface
use OOB;

# register attributes
use OOB qw( ContentType EpochStart Currency Accept );

or:

OOB->ContentType;
OOB->EpochStart;
OOB->Currency;
OOB->Accept;
OOB->Filename;

# scalars (or scalar refs)
OOB->ContentType( $message, 'text/html' );
my $type = OOB->ContentType($message);
print <<"MAIL";
Content-Type: $type

$message
MAIL

# arrays
OOB->EpochStart( \@years, 1970 );
my $offset = OOB->EpochStart( \@years );
print $offset + $_ , $/ foreach @years;

# hashes
OOB->Currency( \%salary, 'EUR' );
my $currency = OOB->Currency( \%salary );
print "$_: $salary{$_} $currency\n" foreach sort keys %salary;

# subroutines
OOB->Accept( \&frobnicate, \@classes );
my $classes = OOB->Accept( \&frobnicate );

# blessed objects
OOB->Filename( $handle, $filename );
my $filename = OOB->Filename($handle);

# functional interface
use OOB qw( OOB_set OOB_get OOB_reset );

package Foo;
OOB_set( $scalar, key => $value );
my $value = OOB_get( \@array, 'key' );
OOB_reset( \%hash );

package Bar;
my $value = OOB_get( $arrayref, 'key', 'Foo' ); # other module's namespace

DESCRIPTION

This module makes it possible to assign any out of band data (attributes) to any Perl data structure with both a functional and an object oriented interface. Out of band data is basically represented by a key / value pair.

Object Oriented Interface

The object oriented interface allows you to easily define globally accessible meta-data attributes. To prevent problems by poorly typed attribute names, you need to register a new attribute at least once before being able to set it. Attempting to access any non-existing meta-data attributes will not result in an error, but simply return undef.

Registration of an attribute is simple. Either you specify its name when you use the OOB module, at compile time:

use OOB qw( ContentType );

Just calling it as a class method on the OOB module at runtime is also enough to allow the attribute:

use OOB;
OOB->ContentType; # much later

After that, you can use that attribute on any Perl data structure:

OOB->ContentType( $string,  'text/html' ); # scalars don't need to be ref'ed
OOB->ContentType( \$string, 'text/html' ); # same as above
OOB->ContentType( \@array,  'text/html' );
OOB->ContentType( \%hash,   'text/html' );
OOB->ContentType( \&sub,    'text/html' );
OOB->ContentType( *FILE,    'text/html' ); # globs
OOB->ContentType( $handle,  'text/html' ); # blessed objects

Functional Interface

The functional interface gives more flexibility but may not be as easy to type. The functional interface binds the given attribut names to the namespace from which it is being called (but this can be overridden if necessary).

use OOB qw( OOB_set OOB_get OOB_reset ); # nothing exported by default

package Foo;
OOB_set( $string, ContentType => 'html' );
my $type = OOB_get( $string, 'ContentType' );        # same namespace ("Foo")

package Bar;
my $type = OOB_get( $string, 'ContentType', 'Foo' ); # other namespace
OOB_set( $string, ContentType => "text/$type" );     # attribute in "Bar"

OOB_set( $string,  ContentType => 'text/html' ); # scalars don't need refs,
OOB_set( \$string, ContentType => 'text/html' ); # equivalent to object
OOB_set( \@array,  ContentType => 'text/html' ); # oriented examples, but
OOB_set( \%hash,   ContentType => 'text/html' ); # limited to the current
OOB_set( \&sub,    ContentType => 'text/html' ); # namespace
OOB_set( \*FILE,   ContentType => 'text/html' );
OOB_set( \$handle, ContentType => 'text/html' );

THEORY OF OPERATION

The functional interface of the OOB pragma basically uses the refaddr of the given value as an internal key to create an "inside-out" hash ref with the given keys and values. If the value is not blessed yet, it will be blessed in the OOB class, so that it can perform cleanup operations once the value goes out of scope.

If a blessed value is specified, the DESTROY method of the class of the object is stolen, so that OOB can perform its cleanup after the original DESTROY method was called. This is only supported if the Sub::Identify module is also installed. If that module cannot be found, a warning will be issued once to indicate that no cleanup can be performed for blessed objects, and execution will then continue as normal.

To prevent clashes between different modules use of the out-of-band data, the package name of the caller is automatically added to any key specified, thereby giving each package its own namespace in the OOB environment. However, if need be, a module can access data from another package by the additional specification of its namespace.

The object oriented interface is really nothing more than synctactic sugar on top of the functional interface. The namespace that is being used by all of the attributes specified with the object oriented interface is the OOB package itself.

To hide the fact that Perl data structures have suddenly become blessed, the OOB module cloaks itself from being seen by Scalar::Util's blessed function, as well as the core ref function.

CAVEATS

Cloaking

The fact that the OOB module is wrapping the core functions ref() and bless(), may produce unexpected results when the OOB module is loaded late. Only code that gets compiled after the OOB module has been loaded, will properly cloak the fact that OOB has blessed the data structure being tested with ref(). A similar issue exists with re-blessing objects and the wrapping of the core function bless. It may therefore be advisable set the PERL5OPT environment variable to include loading of the OOB module as the very first thing to load. The can be e.g. be done by prefixing:

PERL5OPT=-MOOB

to the call to your script, or to add a:

use OOB;

to the startup Perl script in a mod_perl environment.

Unfortunately, any XS code accessing the builtin ref and bless core functions directly, will bypass the cloaking mechanism and therefore report unblessed data structures as being blessed in the OOB class (or a sub class of that).

REQUIRED MODULES

Scalar::Util (1.14)
Sub::Identify (0.02)

AUTHOR

Elizabeth Mattijsen, <liz@dijkmat.nl>.

maintained by LNATION, <thisusedtobeanemail@gmail.com>

Please report bugs to <perlbugs@dijkmat.nl>.

ACKNOWLEDGEMENTS

Juerd Waalboer for the insight that you don't need to keep a reference on a blessed Perl data structure such as a scalar, array or hash, but instead can use any reference to that data structure to find out its blessedness.

Dave Rolsky for pointing out I meant "out-of-band" data, rather than "out-of-bounds". Oops!

Johan Lodin for pointing out potential problems with ref() and late loading of the OOB module.

COPYRIGHT

Copyright (c) 2008 Elizabeth Mattijsen <liz@dijkmat.nl>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.