Code-ART

 view release on metacpan or  search on metacpan

lib/Code/ART.pm  view on Meta::CPAN

=head1 VERSION

This document describes Code::ART version 0.000005


=head1 SYNOPSIS

    use Code::ART;

    # Convert source code fragment to sub and call...
    $refactored = refactor_to_sub( $source_code, \%options );

    # or:
    $refactored = hoist_to_lexical( $source_code, \%options );

    # Source code of sub or lexical...
    $sub_definition  = $refactored->{code};

    # Code to call sub with args, or to evaluate lexical...
    $sub_call_syntax = $refactored->{call};

lib/Code/ART.pm  view on Meta::CPAN

=head1 DESCRIPTION

This module provides a range of subroutines to help you refactor
valid Perl source into cleaner, better decomposed code.

The module also comes with a Vim plugin to plumb those
refactoring behaviours directly into that editor (see L<"Vim integration">).

For example, the module provides a subroutine (C<refactor_to_sub()>)
that takes a source code fragment as a string, analyzes it to determine
the unbound variables within it, then constructs the source code of an
equivalent subroutine (with the unbound variables converted to
parameters) plus the source code of a suitable call to that subroutine.

It is useful when hooked into an editor, allowing you to
(semi-)automatically convert functional code like:

    my @heatmap =
        map  { $config{$_} }
        sort {

lib/Code/ART.pm  view on Meta::CPAN

                        } @heatmap_keys;

        return @heatmap_keys;
    }




=head1 INTERFACE

=head2 Refactoring a fragment of Perl code

To refactor some Perl code, call the C<refactor_to_sub()>
subroutine, which is automatically exported when the
module is loaded.

    my $refactored = refactor_to_sub( $source_code_string, \%options );

Note that this subroutine does not actually rewrite the source code
with the refactoring; it merely returns the components with which you
could transform the original source yourself.

lib/Code/ART.pm  view on Meta::CPAN

The options specify where and how to refactor that code element, as follows:

=over

=item C<< from => $starting_string_index >>

=item C<<   to => $ending_string_index >>

These two options are actually required. They must be non-negative integer
values that represent the indexes in the string where the fragment you 
wish to refactor begins and ends.


=item C<< name => $name_of_new_sub >>

This option allows you to specify the name of the new subroutine.
If it is not provided, the module uses a bad generic name instead
(C<__REFACTORED_SUB__>), which you'll have to change anyway,
so passing the option is strongly recommended.

lib/Code/ART.pm  view on Meta::CPAN

The subset of the code you asked C<refactor_to_sub()> to refactor
could not be recognized by PPR as a refactorable sequence of Perl statements.

Check whether you caught an extra unmatched opening or closing brace, or
started in the middle of a string.


=item C<< failed => 'the code has an internal return statement' >>

If the code you're trying to put into a subroutine contains a (conditional) return
statement anywhere but at the end of the fragment, then there's no way to refactor it
cleanly into another subroutine, because the internal return will return from the newly
refactored subroutine, I<not> from the place where you'll be replacing the original 
code with a call tothe newly refactored subroutine. So C<refactor_to_sub()> doesn't try.


=item C<< failed => "code has both a leading assignment and an explicit return" >>

If you're attempting to refactor a fragment of code that starts with the
rvalue of an assignment, and ends in a return, there's no way to put
both into a new subroutine and still have the previous behaviour of the 
original code preserved. So C<refactor_to_sub()> doesn't try.


=item C<< failed => "because the target code is not a simple expression" >>

Only simple expressions (not full statements) can be hoisted into a lexical
variable or closure. You tried to hoist something "bigger" than that.