view release on metacpan or  search on metacpan

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

source code to be analysed.

It returns a hash containing two keys:

=over

=item C<'use_version'>

The value of this key is a C<version> object representing the
version that the source code claimed it required, via an 
embedded C<use VERSION> statement.

=item C<'vars'>

A hash of hashes, each of which represents one distinct variable
in the source code. The key of each subhash is the string index within
the source at which the variable was declared (or a unique negative number)
if the variable wasn't declared. Each subhash has the following structure:

    {
      decl_name      => '$name_and_sigil_with_which_the_variable_was_declared',
      sigil          => '$|@|%',
      aliases        => \%hash_of_any_known_aliases_for_the_variable,

      declarator     => "my|our|state|for|sub",
      declared_at    => $string_index_where_declared,
      used_at        => \%hash_of_indexes_within_source_string_where_variable_used,

      desc           => "text of any comment on the same line as the declaration",

      start_of_scope => $string_index_where_variable_came_into_scope,
      end_of_scope   => $string_index_where_variable_went_out_of_scope,
      scope_scale    => $fraction_of_the_complete_source_where_variable_is_in_scope,

      is_builtin     => $true_if_variable_is_a_standard_Perl_built_in,

      homograms      => \%hash_of_names_and_keys_of_other_variables_with_the_same_name,
      parograms      => \%hash_of_names_and_keys_of_other_variables_with_similar_names,
      is_cacogram    => $true_if_variable_name_is_pitifully_generic_and_uninformative,
    }

=back


=head2 Renaming a variable

To rename a variable throughout the source code, call the C<rename_variable()>
subroutine, which is exported by default.

The subroutine expects three arguments:

=over

=item *

The original source code (as a string),

=item *

A string index at which some usage of the variable is located
(i.e. a point in the source where a hypothetical cursor would be "over" the variable).

=item *

The new name of the variable.

=back

The subroutine returns a hash with a single entry:

    { source => $copy_of_source_string_with_the_variable_renamed }

If the specified string index does not cover a variable, a hash is
still returned, but with the single entry:

    { failed => "reason_for_failure" }


=head2 Vim integration

The module distribution includes a Vim plugin: F<vim/perlart.vim>

This plugin sets up a series of mappings that refactor or rename
code elements that have been visually selected or on which the
cursor is sitting.

For example, the <CTRL-S> mapping yanks the visual selection, refactors the
code into a subroutine, requests a name for the new subroutine, requests
a return value (if one seems needed), and then pastes the resulting
subroutine call over the original selected text.

The mapping also places the resulting subroutine definition code in the
unnamed register, as well as in register C<"s> (for "B<s>ubroutine"),
so that the definition is easy to paste back into your source somewhere.

The following Normal mode mappings re also available:

=over

=item <CTRL-N>

Rename the variable under the cursor.

=item <CTRL-S>

Search for all instances of the variable under the cursor.

B<I<WARNING>>: In some environments, C<CTRL-S> will suspend terminal
interactions. If your terminal locks up when you use this mapping,
hit C<CTRL-Q> to restart terminal interactions. In this case, 
you will need to either change the behaviour of C<CTRL-S> in
your terminal (for example:
L<https://coderwall.com/p/ltiqsq/disable-ctrl-s-and-ctrl-q-on-terminal>,
or L<https://stackoverflow.com/questions/3446320/in-vim-how-to-map-save-to-ctrl-s>),
or else change this mapping to something else.>

=item gd

Jump to the declaration of the variable under the cursor.

=item E<0x2a>

Jump to the next usage of the variable under the cursor.

=back

The following Visual mode mappings are also available:

=over

=item <CTRL-M>

Match all instances of the variable under the cursor.

=item <CTRL-H>

Hoist all instances of the visually selected code into a lexical variable.

=item <CTRL-C>

Hoist all instances of the visually selected code into a lexical closure.

=item <CTRL-R>

Refactor all instances of the visually selected code into a parameterized subroutine.

=item <CTRL-H><CTRL-H>

=item <CTRL-C><CTRL-C>

=item <CTRL-R><CTRL-R>

Same as the single-control-character versions above, but these only refactor
the code actually selected, rather than every equivalent instance throughout
the buffer.

=back


=head1 DIAGNOSTICS

The analysis and refactoring subroutines all return a hash, in all
cases. However, if any subroutine cannot perform its task (usually
because the code it has been given is invalid), then the returned hash
will contain the key 'failed', and the corresponding value will give a
reason for the failure (if possible).

The following failure messages may be encountered:

=over

=item C<< failed => 'invalid source code' >>

The code you passed in as the first argument could not be recognized
by PPR as a valid Perl.

There is a small chance this was caused by a bug in PPR,
but it's more likely that something was wrong with the code you passed in.


=item C<< failed => 'not a valid series of statements' >>

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