-
-
08 Apr 2021 13:54:02 UTC
- Distribution: OOB
- Module version: 1.00
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Issues
- Testers (170 / 0 / 0)
- Kwalitee
Bus factor: 1- 100.00% Coverage
- License: unknown
- Activity
24 month- Tools
- Download (10.25KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
and 1 contributors- Elizabeth Mattijsen (liz@dijkmat.nl)
- Dependencies
- Scalar::Util
- Sub::Identify
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
- THEORY OF OPERATION
- CAVEATS
- REQUIRED MODULES
- AUTHOR
- ACKNOWLEDGEMENTS
- COPYRIGHT
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 therefaddr
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 theOOB
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'sblessed
function, as well as the coreref
function.CAVEATS
Cloaking
The fact that the
OOB
module is wrapping the core functionsref()
and bless(), may produce unexpected results when theOOB
module is loaded late. Only code that gets compiled after theOOB
module has been loaded, will properly cloak the fact thatOOB
has blessed the data structure being tested withref()
. A similar issue exists with re-blessing objects and the wrapping of the core functionbless
. It may therefore be advisable set the PERL5OPT environment variable to include loading of theOOB
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
andbless
core functions directly, will bypass the cloaking mechanism and therefore report unblessed data structures as being blessed in theOOB
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.
Module Install Instructions
To install OOB, copy and paste the appropriate command in to your terminal.
cpanm OOB
perl -MCPAN -e shell install OOB
For more information on module installation, please visit the detailed CPAN module installation guide.