bulkrn.pl - ReNumber Files  Version (0.0.2)

  A general purpose file name and file path transformation utility.
  Works on unix and cygwin and with ActiveState-Perl.

  Safely renumbers (numeric portions of a file(s) name) and/or renames files
  in the current directory. Watches for filename overlap/overwrite conditions
  what would result in a loss of a file and undoes any changes if there is a
  chance that data-loss might occur.

  By default, the rename process only runs in "test" mode, and you must add the
  -go option to perform the actual rename commands against the file system.
  This guards against the possibility of loosing file data (due to file a 
  overwrites occuring), or loosing file name information (in the case where the
  rename parameters are incorrect, and all files have been renamed as simple
  numeric strings).
  So, we always try to ensure that you check your final results first before
  committing your bulk file name changes with the -go option.

  Again, by default (even with the -go option), a simulated test is always
  run to ensure that no data-loss occurs before the actual file renames are
  performed. This default pre-test can be disabled by the [--run-only | -x]
  option. This is especially useful when using this program within a script.

  The -r and -c options may be used alone or in tandem to either rename or
  renumber some portion of the file name, given the set of files that match
  the -f file pattern.

  An additional level of safety is maintained with regard to file name
  information through session level undo. Consider that a session is when
  bulkrn.pl is called with the -go parameter. If all rename operations occur
  successfully for that session, the undo script for that execution of
  the bulkrn.pl program is saved out to a file in ~/.bulkrn/. Thus executing
  "bulkrn.pl -undo" will rollback the operations of the most recent execution
  of bulkrn.pl. By default, up to 10 prior sessions are saved may be undone.

  usage: bulkrn.pl [SourceDir]
                   [-a|-h|-t|-v-|-x] 
                   -f [FilePattern] 
                   [-r [br:n1|n1-n2:nn[!]]]
                   [-s [SequentialIncrement]]
                   [-d [ZeroPaddedLength]]
                   [-c [SubstitutionPattern]]
                   [-go]
		   [-noUndo]
		   [-undo]

  If not specified [SourceDir] defaults to the current dir './'.

  Requires that the first argument, be defined as a pattern that matches to
  a set of file-names of interest, where the pattern returns upto
  9 back-reference values. The parameter br is the Back Reference value which
  will be changed into a new number. So the return value of that back reference
  must be an integer value. Every portion of the file name that will
  become part of the new name must be held in a back reference. If it is not,
  that portion of the file name will be removed from the new file name.

  By only supplying the [--filePat | -f] option and a file pattern, you can test
  that your file pattern is picking up the files that you expect to rename. And,
  you can the how the file name splits up into its back-references.

$ ./bulkrn.pl -f '(mwlog\.wfiejb\d+)(\.\d\d\d\d)(08\d\d)' 
Testing the FilePattern...
FilePattern Test: applog.cluster1.20100810 => (applog.cluster1) (.2010) (0810)
FilePattern Test: applog.cluster1.20100811 => (applog.cluster1) (.2010) (0811)
FilePattern Test: applog.cluster1.20100812 => (applog.cluster1) (.2010) (0812)
...

 The file name pattern...

  -filePat|-f [filePattern RegExpp]

  '(applog\.cluster)(\d+)(\..*)'
    ^------------  ^--- ^--- 
    |              |    |
    |              |    +---: BackRef $3 -> $fn1
    |              +--------: BackRef $2 -> $fn2
    +-----------------------: BackRef $1 -> $fn3

  In the example above...
  For our example, we want to renumber the values of the 2nd back-reference, so
  the 2nd back-reference must allways return a numeric value.
  This numberic value is compared against n1. And, if there is a match, n1 is
  substitued with the value of nn. And the new file name is built...

  $newFn = $fn1.($fn+(n2-n1)).$fn3;


  -reNum|-r [br:n1|n1-|n1-n2:nn[!]]

      br: The back-reference index whos value will change to nn 
          (which increments, or which is static).
      n1: The Only value that will change.
     n1-: Change all values from n1 and greater.
   n1-n2: Change all values from n1 to n2.
      nn: Change n1 to this new value (nn).
     nn!: Don't increment nn relative to n1-n2. nn stays static.

  --reSeq|-s [SequentialIncrement] (-s 1)
  Resequence the numbers (n1-n2) begining with nn such that the new values are
  contiguous and optionaly incremented by [increment].

  --format|-d [LeadingZerosFormatLength]
  Format the new numberic value with leading zeros to a length of n.
  example: -d 5

  --change|-c [SubstitutionPattern] (-c 's/applog/mxx/i')
  A substitution pattern that changes some portion of the filename if found.
  The back-references $1..$9 may be used in the "matching" portion of the
  string substitution equation to refer to the back-refs in the original
  --filePat parameter. This is useful for upper and lowercasing portions of
  a filename.

  Other options:

  --autoDir|-a
  Automatically create directories along new file paths.
  With out this option, if new file paths do not exist, the rename operation
  will fail.

  --test|-t
  Test the renumbering/renaming process against the filenames in the current
  directory.

  --verbose | -v
  Print details of the renaming process.
  There are 3 levels of verbosity "-v", "-v -v" and "-v -v -v"

  --help|-h
  Output this help text.

  (See: "perldoc ./bulkrn.pl" for more details and examples of use.)