Attribute::Context - Perl extension for automatically altering subroutine behavior based upon context

  use base 'Attribute::Context';

  sub foo    : Arrayref(NOVOID)  {...}
  sub bar    : Arrayref          {...}
  sub baz    : First(NOVOID)     {...}
  sub quux   : Count             {...}
  sub thing  : Custom(My::Class) {...}
  sub script : Custom(class => 'My::Class', NOVOID => 1) {...}

Attribute::Context creates attributes for subroutines to alter their behavior based upon their calling context. Three contexts are recognized:

* list

 my @array = foo();

Currently it is assumed that subroutines returning using these attributes will by default return a list. A scalar or void context will alter their return values.

* scalar

 my $scalar = foo();

Scalar context assumes that the result of the function call are being assigned to a scalar value.

* void

 foo();

Void context is a dangerous thing, so all attributes may have a NOVOID specification. If defined as NOVOID, calling the function in void context will be fatal.

Alteranately, a WARNVOID specification may be given. A WARNVOID function called in void context will only emit a warning.

* Arrayref

Functions with this attribute are assumed to return an array. If called in scalar context, they will return a reference to that array.

For example, the following function will return the reverse of an array, or a reference to the reverse of that array. Calling it in void context will be fatal:

 sub reverse_me : Arrayref(NOVOID)
 {
     return reverse @_;
 }

 my $reversed_reference = reverse_me(qw(1 2 3));
 reverse_me(qw(1 2 3)); # this is fatal

To allow this function to be called in void context, simply remove the NOVOID designation:

 sub reverse_me : Arrayref
 {
     return reverse @_;
 }
 reverse_me(qw(1 2 3)); # a no-op, but not fatal

* Last

Same as Arrayref but returns the last item in the array when called in scalar context.

* First

Same as Arrayref but returns the first item in the array when called in scalar context (like CGI::param).

* Count

Same as Arrayref but returns the number of items in the array when called in scalar context.

* Custom

This is a very experimental feature which is likely to change.

This attribute expects a class name. The class will be loaded, if required. The class must have a constructor named new and it must take an array reference.

 sub thing : Custom(My::Class) {
     return  @_;
 }
 my $thing = thing(@array);

The above method will result in the return value of My::Class->new(\@_) being assingned to $thing.

Note that the Custom attribute typically takes a single argument of a class name. If you need to specify NOVOID or WARNVOID, use named arguments as follows:

 sub foo : Custom(class => 'Some::Class', NOVOID => 1)   {...}
 sub bar : Custom(class => 'Some::Class', WARNVOID => 1) {...}

Your subroutines are expected to return a list or an array. Do not use wantarry in your subroutines as wantarray will always return true.

Nothing.

Attribute::Handlers

Curtis "Ovid" Poe, <eop_divo_sitruc@yahoo.com>

Reverse "eop_divo_sitruc" to send me email.

Probably. This is alpha software. The interface may change, the available attributes may change and the name may even change.

Copyright (C) 2003 by Curtis "Ovid" Poe

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of Perl 5 you may have available.