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

This documentation describes version 0.11.

 # 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

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.

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

The functional interface gives more flexibility but may not be as easy to type. The functional interface binds the given attribut names to thei 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' );        # attribute in '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' );

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.

The fact that the OOB module is wrapping the core functions ref() and blessed(), 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 blessed 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.

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

Elizabeth Mattijsen, <liz@dijkmat.nl>.

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

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 (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.