Class::AutoPlug::ResultState - track the current state of a method call
# All at once:
my $hook_result = Class::AutoPlug::ResultState->new(
{
at_under => [qw(replacement params)], # use 1 element for scalar context
skip_method_call => 1, # true or false
result => [qw(some value here)], # use 1 element for scalar context
context => 'list',
}
);
# Little by little:
my $result = Class::AutoPlug::ResultState->new();
$result->at_under([$value]); # values in anonymous array
$result->skip_method_call(0);
$result->result([$some, $list, $of, $values]); # ditto
$result->context('scalar');
Class::AutoPlug::ResultState allows Class::AutoPlug to track the state of the results of method calls, including pre- and post-hooks. Hooks receive and return the state of the current method call via this object, thus vastly simplyfying the interface between the hooks and Class::AutoPlug::Pluggable.
On entry to your hook, context() will already be set. It is strongly recommended that you not change this value! Doing so will confuse things mightly if some other hook depends on accurately determining the context in which the original method call was made.
For pre-hooks, you may do any or all of the following:
This allows you to alter the parameters that will be passed to the hooked method when it is called.
This allows you to override the result from the method by preemptively returning your own value.
You can completely bypass the method call if you've already handled it.
Prehooks receive @_ (either as passed in, or as modified by other hooks), and the current return value. They should return only a HookResult object.
Post-hooks may alter @_ and the result, just like pre-hooks. @_ will not be used by the base method, however, unless the post-hook explicitly makes its own call to the base method. Replacement of the results is honored exactly as it would be for pre-hooks.
Post-hooks may set the "skip method call" flag, but it shoud be noted that unless a corresponding pre-hook has also done so, it's too late - the method has already been called.
The new() call constructs a new HookResult object. You may provide @_ and result data if you wish; you may also set skip_method_call. The default (if no parameters are supplied) has neither kind of data, and skip_method_call is set to a false value.
at_under allows your hook to see what was in @_ at the time the hook was called, and (optionally) to modify or replace this data. You must pass an array reference to this call; use an empty anonymous array if you want to set @_ to undef.
result allows you to set a (tentative) result for the method call. Note that if you do not set skip_method_call() to a true value in a pre-hook, this value will be overwritten when the method is called.
Sets/gets the context in which the original method call was made. Hooks will receive a ResultState object with this already set up; it is a bad idea to change it, as this will cause other plugins to return values which may be useless in the true context.
Again, Class::AutoPlug::Pluggable (and any derived classes) should set this; hooks should not.
Allows you to say whether or not you want the base method call to be skipped. Only useful in pre-hooks; in post-hooks, the call has already happened.
