Help(v1.0):  fargs [OPTIONS] [-[%PATH_ADD][OPERATION]]...

  Process entries (lines) as if they are file/directory paths.
  Copy the input entries and perform processing operations on
  the copied entries leaving the originals intact.  Finally,
  output the original entries interleaved with the processed
  entries for easy processing as filenames/paths using the 'xargs'
  command with the '-l2' switch.  Simple renames and powerful
  directory manipulation schemes should become easy to formulate.

  Path Addresses:

    no_address  the last path section (usually the filename)
    %-          last path section
    %n          'n'th path section
    %-n         'n'th path section counting from the right
    %][n]:[[m]
               'n'th through 'm'th path sections.  An omitted
               'n' will be set to 1 and an omitted 'm' will
                be set to the last section.
    %|%0        the entire path

  Hold buffer path addresses are by default set to the same as
  the primary path address.  However, you may specify a hold
  buffer specific range by appending it after the primary
  path address separating the two addresses by another '%'.


  Operations:

   d[[^][~]pat] delete current path section (removes '/'s
                cleanly).  If 'pat' is specified, only delete
                path section if it is equal to 'pat'.  '^'
                signifies negation and '~' signifies an RE
                match instead of a full section fixed string
                comparison.

   p[path]      discard main buffer contents and fill with 'path'

   s/pat/rep/   perform substitution with 'sed'

   t[flags] [s1 [s2]]
                perform translation with 'tr'.  The following
                flags will be passed to 'tr': 'cCds' as options.
                The following additional flags 'u' and 'l'
                convert to 'upper' and 'lowercase' respectively
                and do not take any string arguments.  The 'd'
                and 's' flags only take one string argument
                unless used together.  All other flags take 2
                arguments.

   g[flags] pat filter entries with 'grep'.  The following flags
                will be passed to 'grep': 'Fwvix' as options.

   x cmd [arg]... ;
                process the main buffer by executing the args
                which follow 'x'.  The args list should be
                semi-colon ';' terminiated.  Don't forget to
                escape the semi-colon '\;' to bypass your
                shell (similar to 'find --exec'.)

   xk|xf[sep] cmd [arg]... ;
                execute keep/filter - like 'x', except that the
                output of the executed commands should be a list
                of line numbers to keep (like 'grep -n').  The
                first column of each line represents an entry to
                keep/filter.  The columns are delimited by 'sep'
                or ':' by default.  If column is not a number
                the line is ignored.

  Hold Buffer Operations:

   hy|hs        yank/swap main buffer into/with hold buffer
   ha|hp[s]     append/prepend hold buffer to main buffer, use 's'
                as the separator
   hc|hn        keep entries in the main buffer which are ('hn' not)
                the common entries with the hold buffer
   hi           place the contents of the (remaining) original
                entries in the hold buffer (filtered entries
                can never be restored)

  Extension Operations (operate on last path section only):

   +[+]eEXT     add EXT extension (2nd + forces addition when one exists)
   +e/EXT       set (replace or add) extension to 'EXT'
   -[n]e[EXT]   remove ('n'th) extension ('EXT' only) if it exists
   --[n]e       remove all (or up to 'n') extensions
   -[n]e/[OLD/]EXT
                replace ('n'th)('OLD') extension with 'EXT' if it exists

  Options:

   -h           short help (usage)
   --help       full help (*this*)
   -+v          toggle verbose
   --|++debug   toggle debug (lots of output)

  Output Specific Options:

   -of|--ofirst      start interleaving with output entries instead
                     of input entries
   -oo|--oonly       output entries only (omit input entries)
   -ob|--oblank      output pairs which contain blank input and/or output
                     entries
   -oc|--ocommon     output entries which would normally be filtered
                     because they are common to the input entries
   -os|--osepSEP     set output separator to 'SEP' (default is newline)
   -ot               set output separator to a tab (for easier analysis)
   -od|--odebug      --ounchanged -ot
   -oa|oall          --ocommon --oblank


  Processing the copied entries consists of either modifying
  or filtering out entries.  By default only entries which have
  been modified will be output.

  OPERATIONS which are not Extension Operations, Operations and
  Hold Buffer Operations, may be preceeded by a PATH_ADD to
  designate which part of each entry to operate on, see Path
  Addresses above.  Operations are performed in the order that
  they appear.  The default behavior is to operate only on the
  last section of the path if no Path Address is specified for the
  current operation.  It is possible to change the Path Address
  for all subsequent operations by specifying a Path Address
  without an operation: '-%ADD'.

  Most processing operations operate on the main buffer with each
  operation using the main buffer as input and placing its output
  back in the main buffer.  However, there are a few operations
  which operate on a hold buffer.  The hold buffer is initially
  populated with the original input lines, but it may be
  populated by certain operations and applied to the main buffer
  by others.  It is also possible to recall the original entries
  buffer (minus filtered entries) at any time even after
  modifying the main and hold buffers.

  If entries are filtered from the main buffer, the respective
  original and hold buffer entries are also removed.  The final
  output will interleave original and new entries on separate
  lines (unless a different separator is specified) which makes
  the use of spaces safe within entries.  The only character
  restriction on entries should be newlines.  The creation of
  original/new path pairs is optimized for use with commands
  such as 'xargs -l2 mv' which will perform renames on line
  pairs.

  Examples:

  1) Rename files with 'jpeg' to 'JPG' extensions while
     uppercasing the whole filename (but not the directories):

    find . -type f| PROG -e/jpeg/JPG/ -tu | xargs -l2 mv


  2) Restore all .bak files to their original filenames:

    find . -type f -name '*.bak' | fargs -ebak |xargs -l2 mv

   More selectively, get a list of backup files which are not
   the same as their originals:

    find foo -type f | fargs -ebak | xargs -l2 cmp | awk '{print $1}'

   Or, alternatetively, find all the backup files which are the
   same as their originals and delete them:

    find foo -type f | fargs -ebak |      xargs -l2 sh -c 'cmp -s "$0" "$1" && echo "$0"'|xargs -l rm


  3) Replicate a directory hierarchy (no files):

    find foo -type d | fargs -%1s/foo/bar/ -oo | xargs -l mkdir -p

   Now, replicate all the files to the new directory structure
   while running dos2unix on them:

    find foo -type f | fargs -%1s/foo/bar/ |       xargs -l2 sh -c 'dos2unix < "$0" > "$1"'


  4) Perform a subversion mv on many c files, one entry per
     command (old subversion limitation):

    ls mypath/to/files/*/*.c | fargs -%p./newdir -%ha/ |       xargs -l2 svn mv


  Bugs:

  -Does not support gnu find -print0 (all user -x executed
   utilities would need to support it)
  -One tr option should be able to support 2 arguments
  -Reverse address range insertion is not supported
  -Failed operations do not cause the entire program to fail
  -Dot files and current directory entries may confuse extension
   manipulations