NAME
Emacs::Rep - a find & replace engine for rep.pl and rep.el
SYNOPSIS
use Emacs::Rep qw( do_finds_and_reps parse_perl_substitutions );
my $substitutions =>>'END_S';
s/jerk/iconoclast/
s/conniving/shrewd/
s/(t)asteless/$1alented/i
END_S
my $find_replaces_aref =
parse_perl_substitutions( \$substitutions );
my $change_metatdata_aref =
do_finds_and_reps( \$text, $find_replaces_aref );DESCRIPTION
Emacs::Rep is a module that acts as a back-end for the rep.pl script which in turn is used by the emacs library. rep.el.
Emacs::Rep is a find and replace engine that can perform multiple perl substitution commands (e.g. s///g) on a given file, recording all metadata about each change so that an an external program (such as emacs) can interactively display and control the changes.
The end user isn't expected to need to use these routines directly.
An application programmer might use these routines to add support to an interactive front-end (Emacs or otherwise).
EXPORT
None by default. Any of the following may be requested (or all with the ':all' tag).
- parse_perl_substitutions
-
Breaks down a set of perl substitution command (i.e. "s///;", "s{}{};", etc.) into it's main components (the find pattern and the replace expression). It returns this in an an array of arrays data structure (which is the form used by do_finds_and_args).
Takes one argument, a scalar reference to a block of text containing one or more perl substitution commands, in any form (PPI is used internally to parse this).
The more elaborate "s{}{}xmsg;" is fine, as well as "s///g;".
End of line comments (after the closing semicolon) beginning with a "#", are allowed, as are embedded comments inside the find pattern if the /x modifier is in use.
Example usage:
my $substitutions =>>'END_S'; s/pointy-haired boss/esteemed leader/g; s/death spiral/minor adjustment/g; END_S
my $find_replaces_aref = parse_perl_substitutions( \$substitutions );
Where the returned data should look like:
[ ['pointy-haired boss', 'esteemed leader'], ['death spiral', 'minor adjustment'], ]Any trailing modifiers are automatically prefixed to the find_pattern, using the (? ... ) notation, *except* for /g and /e.
For purposes of do_finds_and_reps /e is always ignored (as of this writing), and /g is always assumed, irrespective of whether it was added explicitly.
- accumulate_find_reps
-
For internal use. Example usage:
accumulate_find_reps( \@find_reps, $find, $rep, $raw_mods ); - do_finds_and_reps
-
Does a series of finds and replaces on some text and returns the beginning and end points of each of the modfied regions, along with some other information about the matches.
Takes two arguments:
(1) The text to be modified, usually as a reference, though a scalar is okay (2) A series of find and replace pairs in the form of an aref of arefs, e.g.
$find_replaces_aref = [ ['jerk', 'iconoclast'], ['conniving', 'shrewd']. ['(?i)(t)asteless', '$1alented']. ]:(See parse_perl_substitutions.)
Example usage:
$locations_aref = do_finds_and_reps( \$text, $find_replaces_aref );
The returned change metadata is an aref of arefs of hrefs; an array of passes with an entry for each substitution pair, an an array of changes made by each pass. The href has keys: 'beg', 'delta', 'orig', 'rep'.
The fields 'orig' and 'rep' contain the modified string, before and after the change.
'delta' is the change in length due to the change.
'beg' is the beginning of the region that was modified, an integer counting from the start of the file, where the first character is 1.
This numbering does not change while a s///g is in progress, even if it is changing the length of the strings. And further, these change locations are recorded *during* each pass, which means that later passes throw off the numbering.
In practice, for the rep.el application, we apply this data on the emacs side in inverse order, so that the numbering is correct in the context we use it.
Note, error messages are routed to stdout, labeled with the prefix "Problem:". The elisp call shell-command-to-string merges stdout and stderr, but we use the 'Problem' prefix to spot error messages
- check_versions
-
Verify that all three pieces of the system have the same version: the *.pl, *.pm and *.el.
The elisp code is expected to run this command string with it's own version number:
perl rep.pl --check_versions="0.08"rep.pl then runs this check_versions routine, passing along the elisp version and the rep.pl version number:
Example usage:
check_versions( $elisp_version, $script_version );This compares those two versions with the module's version, and warns if they're not all the same.
SEE ALSO
The web page for this project is:
http://obsidianrook.com/repThe code is available on github (as well as on CPAN):
http://github.com/doomvox/repEmacs::Rep is the back-end for the script rep.pl which in turn is the back-end for the emacs lisp code rep.el.
If rep.el is not installed, look in the "elisp" sub-directory of this CPAN package.
A good discussion forum for projects such as this is:
http://groups.google.com/group/emacs-perl-intersectionAUTHOR
Joseph Brenner, <doom@kzsu.stanford.edu>
COPYRIGHT AND LICENSE
Copyright (C) 2010,2012 by Joseph Brenner
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
BUGS
None reported... yet.