Method::Declarative 0.03

Method::Declarative is a Perl module to create methods with declarative syntax.

SYNOPSIS

use Method::Declarative
(
--defaults =>
{
precheck =>
[
[ qw(precheck1 arg1 arg2) ],
# ...
],
postcheck =>
[
[ qw(postcheck1 arg3 arg4) ],
# ...
],
init =>
[
[ initcheck1 ],
# ...
],
end =>
[
[ endcheck1 ],
# ...
],
once =>
[
[ oncecheck1 ],
] ,
package => __CALLER__::internal,
},
method1 =>
{
ignoredefaults => [ qw(precheck end once) ],
code => __method1,
},
) ;

The Method::Declarative module creates methods in a using class namespace. The methods are created using a declarative syntax and building blocks provided by the using class. This class does not create the objects themselves.

The using class invokes Method::Declarative, passing it list of key-value pairs, where each key is the name of a method to declare (or the special key --default) and a hash reference of construction directives. The valid keys in the construction hash refs are:

code

The value corresponding to code key is a method name or code reference to be executed as the method. It is called like this:

$obj->$codeval(@args)

where $obj is the object or class name being used, $codeval is the coresponding reference or method name, and @args are the current arguments for the invocation. If $codeval is a method name, it needs to be reachable from $obj.

A code key in a method declaration will override any code key set in the --defaults section.

end

The value corresponding to the end key is an array reference, where each entry of the referenced array is another array ref. Each of the internally referenced arrays starts with a code reference or method name. The remaining elements of the array are used as arguments.
Each method declared by the arrays referenced from end are called on the class where the declared method resides in an END block when Method::Declarative unloads.

Each method is called like this:

$pkg->$codeval($name[, @args]);

where $pkg is the package or class name for the method, $name is the method name, and @args is the optional arguments that can be listed in each referenced list.

end blocks are run in the reverse order of method declaration (for example, if method1 is declared before method2, method2s end declaration will be run before method1s), and for each method they are run in the order in which they are declared.

Note that this is not an object destructor, and no objects of a particular class may still exist when these methods are run.

ignoredefaults

The value corresponding to the ignoredefaults key is an array reference pointing to a list of strings. Each string must corespond to a valid key, and indicates that any in-force defaults for that key are to be ignored. See the section on the special --defaults method for details.

init

The value corresponding to the init key is identical in structure to that corresponding to the end key. The only difference is that the declared methods/code refs are executed as soon as the method is available, rather than during an END block.

once

The value corresponding to the once key is identical in structure to that corresponding to the end key. The values are used when the method is invoked, however.

If the method is invoked on an object based on a hash ref, or on the class itself, and it has not been invoked before on that object or hash ref, the methods and code refs declared by this key are executed one at a time, like this:

$obj->$codeval($name, $isscalar, $argsref[, @args ]);

where $obj is the object or class on which the method is being invoked, $codeval is the method name or code reference supplied, $name is the name of the method, $isscalar is a flag to specify if the declared method itself is being executed in a scalar context, $argsref is a reference to the method arguments (@_, in other words), and @args are any optional arguments in the declaration.

The return value of each method or code reference call is used as the new arguments array for successive iterations or the declared method itself (including the object or class name). Yes, that means that these functions can change the the object or class out from under successive operations.

Any method or code ref returning an empty list will cause further processing for the method to abort, and an empty list or undefined value (as appropriate for the context) will be returned as the declared methods return value.

package

The value coresponding to the package key is a string that determines where the declared method is created (which is the callers package by default, unless modified with a --defaults section). The string __CALLER__ can be used to specify the callers namespace, so constructions like the one in the synopsis can be used to create methods in a namespace based on the calling package namespace.

postcheck

The value coresponding to the postcheck key is identical in structure to that coresponding to the end key. The postcheck operations are run like this:

$obj->$codeval($name, $isscalar, $vref[, @args ]);

where $obj is the underlying object or class, $codeval is the method or code ref from the list, $name is the name of the declared method, $isscalar is the flag specifying if the declared method was called in a scalar context, $vref is an array reference of the currently to-be-returned values, and @args is the optional arguments from the list.

Each method or code reference is expected to return the value(s) it wishes to have returned from the method. Returning a null list does NOT stop processing of later postcheck declarations.

precheck

The precheck phase operates similarly to the once phase, except that its triggered on all method calls (even if the underlying object is not a hash reference or a class name).
Any illegal or unrecognized key will cause a warning, and processing of the affected hashref will stop. This means a --defaults section will be ineffective, or a declared method wont be created.