view release on metacpan or  search on metacpan

lib/Attribute/GlobalEnable.pm  view on Meta::CPAN

=item ALL_'SPECIAL_KEY' (or just 'SPECIAL_KEY')

This turns the attributes functionality on for ALL of those subroutines that
have the attribute.  This trumps all other settings, except for the NO_
pre-string.

=item NO_'SPECIAL_KEY'

This is essentially the default behaviour, turning the attribute stuff off.
This trumps everything... Other 'SPECIAL_KEY's, and any ENABLE_FLAGS.

=back

You can append package names, or even subroutines to the end of the
'SPECIAL_KEY', in order to turn the attribute functionality on for a specific
package or subroutine.  Just separate the 'SPECIAL_KEY' and your specific
string with an underscore.  Neato eh?  There is one caveat to this.  The regular
perl package (namespace) separator is replaced with two underscores, so if
you wanted to turn on attribute behaviour for MyPackage::ThisPackage, your
key would look like so:

'SPECIAL_KEY'_MyPackage__ThisPacakge

I did this so that you can just pass in the %ENV hash, and set your 
attribute 'SPECIAL_KEY's on the command line or whathave you.

Finally, the '#'s that you must name each of your special subs with,  represent
a level for a particular functionality.  This level is checked each time,
and the appropriate subroutine will be called, or it will try the next level
down.  So, forexample:  If you just have attr'Attribute_name'_1, but you set
your 'SPECIAL_KEY' to 3, then attr'Attribute_name'_1 will be executed.
if you had an attr'Attribute_name'_2, then that subroutine would be executed
instead of 1.  This will not call each subroutine as it goes, it simply executes
the first one it finds.


=head3 (required) ENABLE_CHK => $hash_ref

This must be set to a hash ref whos structure is laid out as:

  SOME_FLAG => $integer,

$integer should be positive, and represents the attribute level you wish to
do attribute stuff at. (see ENABLEL_ATTR above for more info on that).  The
actual hash can be empty, but the reference must exist.

This represents the actual user set triggers for the attributes.  Telling
GlobalEnable which to... well... enable, and which to skip.

See the previous section for a description on special characters etc...

=head3 ENABLE_FLAG => $hash_ref

The $hash_ref structure must be:

  { Attribute_name => [ list of flags ], Attribute_name_2 ... }

The ENABLE_FLAG is optional, and describes flags that can be set for the
exported 'Attribute_name' subroutines.  These are exported as global
constants, so it looks nice and neat in your code.  This essentially links
that sub call to that flag.  The flag is still set like it would normally be
set in the ENABLE_CHK hash,  however, you still must use the 'SPECIAL_KEY'
(see above) in the assignment, so your assignment will look like:

  'SPECIAL_KEY'_'FLAG'

=head2 attr'Attribute_name'_#

See ENABLE_ATTR above for a description on the layout naming scheme for this
particular subroutine name.

This is your attribute hook for a particular level.  This must return a
subroutine.  The subroutine that it returns replaces the one the attribute is
currently assigned to.  You can do anything you wish at this point, as you'll
have access to everything that's being passed in, everything that's being
passed out, and whatever else you want.

It will always get these variables when it's called:

=over

=item [0] : package name ala $package->attr'Attribute_name'_1

=item [1] : callers package name

=item [2] : the code symbol (GLOB)

=item [3] : the code reference of the sub that has this attribute turned on.

=item [4] : the attribute name that triggered this.

=item [5] : any attribute data assigned to the attribute.

=item [6] : the current phase this was activated in.

=back

See perldoc Attribute::Handlers for more descirption on what these values
are, or how to utilize them.

=head2 our'Attribute_name'_#

This is the sub that's pointed to from our exported 'Attribute_name' subroutine.
If you pass in a valid flag, it'll clear that out before it sends the rest
of the arguments your way.  There is no need to return a sub, as this is the
actual subroutine that's executed when you trigger this special sub.

=head1 EXAMPLES

For right now, see the tests for some examples.  There's a test module in
the test dir as well.  I'll fill in some examples a little later.

=head1 SEE ALSO

perldoc perlsub, Attribute::Handlers

=head1 AUTHOR

Craig Monson (cmonson [at the following]malachiarts com)