/ 
Module-AnyEvent-Helper-v0.0.5
River stage one • 1 direct dependent • 1 total dependent
/ Module::AnyEvent::Helper::PPI::Transform

NAME

Module::AnyEvent::Helper::PPI::Transform - PPI::Transform subclass for AnyEvent-ize helper

VERSION

version v0.0.5

SYNOPSIS

Typically, this module is not used directly but used via Module::AnyEvent::Helper::Filter. Of course, however, you can use this module directly.

my $trans = Module::AnyEvent::Helper::PPI::Transform->new(
    -remove_func => [qw()],
    -translate_func => [qw()]
);
$trans->file('Input.pm' => 'Output.pm');

NOTE that this module itself does not touch package name.

There are some helper functions can be exported.

use Module::AnyEvent::Helper::PPI::Transform qw(function_name);
function_name($element); # returns function name whose definition includes the element

# or you can call them as class methods
Module::AnyEvent::Helper::PPI::Transform->function_name($element);

DESCRIPTION

To make some modules AnyEvent-frinedly, it might be necessary to write boiler-plate codes. This module applys the following transformations.

  • Emit use AnyEvent;use Module::AnyEvent::Helper; at the beginning of the document.

  • Translate (ordinary) methods to _async methods.

    • Emit my $___cv___ = AE::cv; at the beginning of the methods.

    • Emit return $___cv___; at the end of the methods.

    • Replace method calls with pairs of Module::AnyEvent::Helper::bind_scalar and shift->recv.

  • Delete methods you need to implement by yourself.

  • Create blocking wait methods from _async methods to emit Module::AnyEvent::Helper::strip_async_all();1; at the end of the packages.

Additionally, this module inherits all of PPI::Transform methods.

Furthermore, there are some helper functions. It might be helpful for implementing additional transformer of Module::AnyEvent::Helper::Filter.

OPTIONS

-remove_func

Specify array reference of removing methods. If you want to implement async version of the methods, you specify them in this option.

-translate_func

Specify array reference of translating methods. You don't need to implement async version of these methods. This module translates implementation.

-replace_func

Specify array reference of replacing methods. It is expected that async version is implemented elsewhere.

-delete_func

Specify array reference of deleting methods. If you want to implement not async version of the methods, you specify them in this option.

METHODS

This module inherits all of PPI::Transform methods.

FUNCTIONS

All functions described here can be exported and can be called as class methods.

# The followings are identical
Module::AnyEvent::Helper::PPI::Transform::function_name($word);
Module::AnyEvent::Helper::PPI::Transform->function_name($word);

function_name($element)

$element MUST be PPI::Element object. If $element is included in a function definition, its function name is returned. Otherwise, undef is returned.

is_function_declaration($word)

$word MUST be PPI::Token::Word object. If $word points a function name of a function declaration, true is returned. Otherwise, false is returned.

delete_function_declaration($word)

$word MUST be PPI::Token::Word object and SHOULD be is_function_declaration is true. Delete the function declaration from the document.

copy_children($prev, $next, $target)

$prev specifies the where elements are inserted after. $next specifies the where elements are inserted before. One of the two MUST be valied PPI::Element object. If both are valid, the first paramter is used and the second parameter is ignored.

$target specifies PPI::Element holding elements inserted at the place specified by $prev or $next.

emit_cv($block)

$block is PPI::Structure::Block object.

my $___cv___ = AE::cv;

is inserted at the beginning of the block, and

return $___cv___;

is inserted at the end of the block.

emit_cv_into_function($word)

$word is PPI::Token::Word object and SHOULD be is_function_declaration is true. emit_cv is called for the block of the function declaration.

replace_as_async($element, $name, $is_array)

$element is a PPI::Element object and SHOULD point the name of the function call. $name is the function name that will be set as the contents of $element. $is_array is a boolean flag spcifying whether returning context is list context or not.

If the first argument points at call in the following code:

my $var = 42 + $some->[$idx]{$key}->call($arg1, $arg2) * func();
# codes follows ...

after the call of this function with replace_as_async($elem, 'call_async', 0), converted into as follows:

Module::AnyEvent::Helper::bind_scalar($___cv___, call_async($arg1, $arg2), sub {
my $var = 42 + shift->recv() * func();
# codes follows ...
});

For the case of replace_as_async($elem, 'call_async', 1), converted into as follows:

Module::AnyEvent::Helper::bind_array($___cv___, call_async($arg1, $arg2), sub {
my $var = 42 + shift->recv() * func();
# codes follows ...
});

See also Module::AnyEvent::Helper.

AUTHOR

Yasutaka ATARASHI <yakex@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Yasutaka ATARASHI.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.