OOB - out of band data for any data structure in Perl
This documentation describes version 1.00.
# 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:
OOB
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 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' );
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.
refaddr
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.
blessed
ref
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:
ref()
bless
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).
Scalar::Util (1.14) Sub::Identify (0.02)
Elizabeth Mattijsen, <liz@dijkmat.nl>.
maintained by LNATION, <thisusedtobeanemail@gmail.com>
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.
To install OOB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OOB
CPAN shell
perl -MCPAN -e shell install OOB
For more information on module installation, please visit the detailed CPAN module installation guide.