NAME

rep.pl - perform a series of find and replaces

SYNOPSIS

 rep.pl --backup <backup_file> --substitutions <filename> --target <file_to_act_on>

 rep.pl -b <backup_file> -f <file_to_act_on> 's/foo/bar/'

USAGE

  rep.pl -[options] [arguments]

  Options:

     -s                substitutions list file
     --substitutions   same
     -f                target file name to be modified
     --target          same
     -B                backup file name
     --backup          same

     --trial           report change metadata without modifying target file

     -d                debug messages on
     --debug           same
     -h                help (show usage)
     -v                show version
     --version         show version

     -T                make no changes to the input file, but report
     --trailrun        metadata for changes that would've been made.

DESCRIPTION

rep.pl is a script which does finds and replaces on a file, and records the beginning and end points of the modified strings.

It is intended to act as an intermediary between Emacs::Rep and the emacs lisp code which drives the "rep" process.

Emacs can then use the recorded locations to highlight the changed regions, and it can use information about what was replaced to perform undo operations.

The elisp code must choose a unique backup file name. This makes it possible to do reverts of an entire run of substitutions.

The script returns a data dump of the history of the changes to the text. This is in the form of an array of hashes, serialized using JSON.

The array is in the order in which the individual changes took place. Each row has fields:

  pass   the number of the "pass" through the file
         (one pass per substitution command)
  beg    begin point of changed string
  end    end point of changed string
  delta  the change in string length
  orig   the original string that was replaced
  rep    the replacement string that was substituted
  pre    up to ten characters found before the replacement
  post   up to ten characters found after the replacement

Note: in "beg" and "end" characters are counted from the beginning of the text, starting with 1.

AUTHOR

Joseph Brenner, <doom@kzsu.stanford.edu>

COPYRIGHT AND LICENSE

Copyright (C) 2010 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.

TODO

o Simplify the UI for command-line use:

   o If there's no -f or --target, could guess that the first
     item is the file, and the remaining arguments are
     substitution commands.

   o In the absence of -b of --backup, should have a default
     scheme.

   o Could it be that "rep.pl" is too short?  Possible name collison,
     and this isn't really for command-line use in any case.