NAME

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

SYNOPSIS

  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) {...}

DESCRIPTION

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

Contexts

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

Attributes

• 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) {...}
  

CAVEATS

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

EXPORT

Nothing.

SEE ALSO

Attribute::Handlers

AUTHOR

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

Reverse "eop_divo_sitruc" to send me email.

BUGS

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

COPYRIGHT AND LICENSE

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.