renameFiles

#!/usr/bin/env perl -w
#
# renamefiles: Absurdly flexible bulk file-renaming.
# Written 2006-12-18 by Steven J. DeRose.
#
use strict;
use Getopt::Long;
use Encode;
use POSIX qw(strftime);

use sjdUtils;
use alogging;

our %metadata = (
    "title"        => "renameFiles",
    "description"  => "Absurdly flexible bulk file-renaming.",
    "rightsHolder" => "Steven J. DeRose",
    "creator"      => "http://viaf.org/viaf/50334488",
    "type"         => "http://purl.org/dc/dcmitype/Software",
    "language"     => "Perl 5.18",
    "created"      => "2006-12-18",
    "modified"     => "2024-06-05",
    "publisher"    => "http://github.com/sderose",
    "license"      => "https://creativecommons.org/licenses/by-sa/3.0/"
);
our $VERSION_DATE = $metadata{"modified"};

=pod

=head1 Usage

renameFiles [options] [regex] [files]

Apply a regular expression, or any of a range of built-in operations,
to rename a file(s). Can do systematic changes such as (see below for more):

  * imposing or removing camel or other case patterns,
  * normalizing date strings,
  * moving date strings to the front for sortability,
  * getting rid of unwelcome characters (even by file-system type)
  * padding sequence numbers,
  * inserting the values of various file attributes
(date, owner id, or even the source URI when available) into the name.

For files under git control, set I<--gitMoves> to check status
and attempt "git mv" instead of a regular rename when applicable.

=head2 Examples

A commonly useful case is to turn all characters not in C<[-.\\w]> into "_":

    renameFiles --clean *

The same thing via an equivalent (Perl-style) regular expression change:

    renamefiles --expr "s/[^-.\\w]/_/g" *.htm

To pad numbers to a uniform number of digits (in this case 4):

    renamefiles --expr 's/^(\d+)/\$1/'"' --ePad 4 *.htm

Be sure to backslash or quote '$' (such as when used for back-references
as in this example).

Renames all .htm files in the current directory whose names contain
"myFile", "myStuff", or "myData" to refer to "Herodotuses" in place of the "my".

    renamefiles --expr "s/my(File|Stuff|Data)/Herodotuses_\$1/" *.htm

B<Note>: Changes apply to each filename, not the path leading to it,
nor to an extension (unless you set certain options).
They do apply to names of directories, unless you set I<--no-dirs>).

There are options to:

=over

=item * normalize dates or numbers in names, and/or move them to the front
(I<--dates>, I<--epad>, etc.),

=item * modify character-set and case usage (I<--camelize>, I<--clean>, I<--lc>),

=item * convert names to conform to various file-systems
(I<--fileSystem [name]>, such as by removing or replacing prohibited characters.
Use I<--help-filesystem> to get a list of names.

=item * insert ancestor directory names into the filename (I<--pull>),

=item * insert content extracted from the file's contents (I<--pullContent>),

=item * insert names extracted from the URI from which a file was downloaded
(I<--pullURI>, MacOS only),

=item * insert serial numbers to avoid conflicts (I<--resolve>, I<--pad>),

=item * fiddle with extensions (I<--addExtension>, I<--extChanges>,
I<--onlyExtensions>, I<-x>),

=item * prepend file access, creation, or modification dates, etc. (I<--addStat>),

=item * handle conventions for naming duplicates and backups (I<--copies>),

=item * fix URI-style %XX special-character codes (I<--unescapeURI>),

=back

=head2 Order of changes

Renaming actions happen in the order (listed by option names):
copies, pull, pullURI, xattrAdd, unescapeURI, lc, uc, bactrianize,
camelize, addStat, dates, expr, clean. The easiest way to force a
different order is probably to use multiple C<renameFiles> commands.


=head1 Options

(prefix "no" to negate where applicable)

=over

=item * B<--addExtension> I<ext>

Add an extension to files that don't already have one.
Use I<ext> as the extension (don't specify the "."), except that if I<ext> is
set to "!", use the *nix C<file> command to figure out what the file is, and
provide the appropriate extension from an internal list. C<file> is not
complete, nor is the internal list. For example, a Java source file (at
least on Mac OS when I checked) comes back merely as "ASCII text",
which the list maps to extension "txt".
See also I<--extChanges>.

=item * B<--addStat> I<n>

Prefix a piece of file-system information (from C<stat>) to the filename.
For example, specify I<mtime> or I<9> to insert the modification date
of the file (see the following list).
Times are converted to dates in yyyy-mm-dd form
(time and datetime will likely be added as well).
See also I<--dates>, which can be used to normalize date formats in filenames.

The fields of I<stat> can be specified by number or by the short names here:

  0 dev      device number of filesystem
  1 ino      inode number
  2 mode     file mode  (type and permissions)
  3 nlink    number of (hard) links to the file
  4 uid      numeric user ID of file's owner
  5 gid      numeric group ID of file's owner
  6 rdev     the device identifier (special files only)
  7 size     total size of file, in bytes
  8 adate    last access time in seconds since the epoch
  9 mdate    last modify time in seconds since the epoch
 10 cdate    inode change time in seconds since the epoch (*)
 11 blksize  preferred I/O size in bytes for interacting with the
file (may vary from file to file)
 12 blocks   actual number of system-specific blocks allocated
on disk (blocks are often, but not always, 512 bytes each)

=item * B<--ancestor>

As the first step I<when resolving name conflicts>,
prefix the name of the parent directory, plus the
I<--separator> character (default "_"), to the filename.
See also I<--pull>, I<--pullURI>, and I<--pullContent>
(which do a similar operation
regardless of whether there is any name conflict).

=item * B<--bactrianize> OR B<--camelToSpace>

Insert a space before each non-initial capital letter in names (except where
there already is such a space).
For example, "TodaysNewsHeadlines" becomes "Todays News Headlines".
B<Note>: A Bactrian camel has two humps with a gap between; this option
inserts a "gap". This does not do anything special for names like "DeRose".
See also I<--camelize>.

=item * B<--camelize>

Remove whitespace runs from names, but capitalize the character following each.
For example, "Todays news headlines" becomes "TodaysNewsHeadlines".
If you also specify I<--lc>, I<--lc> is done first.
See also I<--bactrianize>.

=item * B<--clean>

Change unusual characters to "_".
"Unusual" means characters that are not among C<[-.\\w]>.

=item * B<--copies>

Scan for various OS conventions for duplicate files, such as
"Copy 4 of foo", "foo - Copy (4)", "foo (another copy)", etc.
Where found, replace them with a trailing I<--separator>
character and number (left zero-padded if you specify I<--pad>).
If there are already numbered editions, avoid overwriting them.
However, nothing is done to ensure that the editions are numbered in
order by mod date or some other criterion.
Experimental.

=item * B<--dateOutput> I<formatString>

Change the format that dates are converted to with I<--dates>.
Takes an argument of the form expected by I<strftime()> (the code uses
strftime, and accounts for it wanting 0-based days and 1900-based years).
Default: "%Y-%m-%d", which produces the ISO 8601 date format (yyyy-mm-dd),
which sorts right, avoids ambiguity between US and UK forms, etc.

=item * B<--dates>

Notice simple dates embedded in names, change them to yyyy-mm-dd form
(see ISO 8601), and move them to the beginning of the filenames. See also I<--addStat>.

The formats recognized include:
    02/28/1776 (US style (mm/dd/yyyy)
    Feb. 28, 1776
    28 Feb 1776
    1776-02-28
    1776-02 (day defaults to 1)
    17760228
    Feb 1776

To recognize European style (dd/mm/yyyy) instead of US, set I<--uk>.

All matches must begin and end at word boundaries (regex "\\b").
Month names are recognized spelled out in full or
abbreviated, as set for the current C<locale>. Dots, commas, and the amount and type
of whitespace can be varied. 4-digits years alone are not affected; for
that see I<--dateyears>.

=item * B<--dateyears>

This option is similar to I<--dates>, but recognizes lone 4-digit years beginning
with "1" or "2", and merely moves them to the front (a 4-digit year by itself
is a valid ISO 8601 data representation). This option will I<not> move
them if followed by a hyphen or digit.

=item * B<--dirs>

Rename directories just like anything else (defaults to be on; use
I<--no-dirs> to turn off). Compatible with, but not the same as, I<--recursive>.
There is no setting (yet) to operate I<only> on directories.

=item * B<--dot>

Include hidden files (that is, files whose names begin with ".").

=item * B<--dropExtensions>

Delete file extensions.

=item * B<--dropOriginal>

Don't include the original name in the result. For the moment, this only
applies when I<--pullContent> is used; it should be extended to other
options that similarly append brand-new, likely-unique strings to the filenames.

=item * B<--ePad> I<num>

With I<--expr>, left-pad the I<to> value to a minimum of I<num> characters.
The pad character used can be controlled via I<--ePadChar>.

This can be useful, among other things, for normalizing the length of
embedded numbers.
The padding is applied to the right hand side as a whole:

    renameFiles -epad 6 -e "s/([\d+])/$1/" *.foo

This would, for example, rename F<zork37> to F<zork000037>.

See also I<--pad>, which instead affects numbers appended to avoid conflicts
while renaming.

=item * B<--ePadChar> I<c>

The character to use when padding right-hand sides with I<--ePad>. Default: "0".
With I<--expr>, left-pad the I<to> value to a minimum of I<num> characters.

=item * B<--expr> I<'s/lhs/rhs/'> OR B<-e> I<'s/lhs/rhs/'>

Apply the given regex to filenames (several examples are given near the start of
this help). All matches are changed, not just the first.

This uses PERL regexes, and respects the I<--ignorecase> option.
To use a capture, use $1 etc. on the right-hand side, not \\1.
But remember to backslash or quote the "$" to protect it from the shell.
This change does not affect filename extensions unless you
also specify I<--extChanges>.
See also I<--ignoreCase>.
This option is I<not> repeatable.

=item * B<--extChanges> OR B<--extensions>

Apply the I<--expr> change to full filenames including any file extensions,
instead of to the basenames excluding the extensions.
Experimental. See also I<--onlyExtensions>.

=item * B<--filesystem> I<name>

Ensure that all filenames conform to the requirements of a certain filesystem.
For example, MacOSX prohibits colons, Windows backslashes, and various systems
have different maximum name lenths. To see a list of supported file systems,
with their names and constraints, use I<--help-filesystems>.

B<Note>: Maximum filename lengths for different file systems may not be
measured the same. For example, both Mac and ext4 (at least on Synology)
say 255, but if the Mac name includes UTF-8 the byte count can apparently
go over 255, in which case copying to ext4 seems to fail.

=item * B<--force>

Overwrite conflicting output files with prejudice. Experimental.
This is not intended to overwrite output directories.

=item * B<--gitMoves>

Do "git mv" rather than regular mv (when applicable).

=item * B<--ignoreCase> OR I<-i>

Add the "i" option to the regex change specified by I<--expr>,
so the change ignores case distinctions.

=item * B<--xattrAdd> I<itemName>

Append to the filename, the specified item extracted from MacOS file-system
metadata for the file (when available). Such items can be accessed by the
shell command C<mdfind>, and have names beginning C<xattrItem> (that prefix may
be omitted when using this option). This option should be, but is not, repeatable.
However, you can run C<renameFiles> multiple times to add one item at a time.

The available items can be listed by using the I<--xattrList> option.

=item * B<--xattrList>

List all available items that can be specified for the I<--xattradd>.

=item * B<--lc> OR B<--lower>

Force filenames entirely to lower case.
This does not affect extensions.

=item * B<--lowerExtensions> OR B<--lcExtensions>

Force file extensions to lower case.

=item * B<--onlyExtensions>
Apply any I<--expr> changes to file extensions only (not to the
basename, nor to the full name including the extension). Do not include the ".".
Experimental. See also I<--extChanges>.

=item * B<--pad> I<num>

With I<--resolve>, left-pad the number to a minimum of I<num> digits.
In case of name conflicts, padded numbers are tried, from 0 up to 10**I<num>.
If no filename in that range is available, the rename fails.

<Note>: See also I<--ePad>, to pad the "to" side of an I<--expr> change.

=item * B<--pull> I<n>

Add the names of the I<n> nearest containing directories into the filename
proper, separated by the I<--separator> character (default "_").
See also I<--ancestor> and I<--pullURI>.
For example, with I<--pull 2> a file at

    /home/jsmith/pix/pets/rover_12.jpg

becomes

    /home/jsmith/pix/pets/pix_pets_rover_12.jpg

=item * B<--pullContent>

Extract content from the beginning of the file and put it into the name.
The first record is read, and any HTML or XML tags are stripped out
(for actual HTML or XML, it would typically be better to extract a title or
similar). Unusual characters are removed, spaces are changed to "_", and
the result is truncated at 40 characters, then appended to the filename.

=item * B<--pullNoEntities>

If set, then I<--pullContent> will discard not only tags, but also entity
and numeric character references.

=item * B<--pullURI> I<n>

Extract the URI from which the file was downloaded (Mac only,
obtained via the C<xattrs> command).
Then add the names of the last I<n> directories from the URI (assuming
it's a directory-style URI) into the filename proper
(see also I<--ancestor> and I<--pull>, and the C<whereFrom> command).
The directory names are separated by the I<--separator> value
(since a literal "/" would be at least inconvenient).

=item * B<--quiet> OR B<-q>
Suppress most messages.

=item * B<--recursive> OR B<-r>

Run through subdirectories, too. Experimental. See also I<--dirs>.

=item * B<--resolve>

If a rename leads to a conflict, suffix a serial-number. See also I<--pad>.
Default (unset with I<--no-resolve>).

=item * B<--separator> I<s>

Use I<s> (default "_") in place of any characters to be removed
by I<--clean>, and to separate directory names prepended to
the filename by I<--ancestor>, I<--pull>, etc.

=item * B<--test> OR B<--dry-run> OR B<--dryrun>

Run through and show what would be done, but don't actually rename anything.
B<Note>: This is not a perfect test, since actual renaming of early files
might produce conflicts later (which will not be noticed with I<--test>).

=item * B<--uc> OR B<--upper>

Force filenames entirely to upper-case.
This does not affect extensions.

=item * B<--uk>

Look for dates as dd/mm/yyyy instead of mm/dd/yyyy.

=item * B<--unescapeURI>

Expand %xx special characters (such as used in URIs).
This functionality is also available by itself, with the
separate command C<unescapeURI>.

=item * B<--unroman>

Find roman numerals within filenames and convert them to Arabic numerals
(subject also to I<--pad>).
Roman numerals are defined (too loosely) as sequences of [ivxlcm], without
an adjacent letter on either side (enforced using regex C<\\b>).
A single match must be in consistent case, but either case is ok.
Experimental. Requires installing Perl's C<Roman> module
(L<http://search.cpan.org/~chorny/Roman/lib/Roman.pm>).

=item * B<--verbose> OR B<-v>
Provide more detailed messages. Repeatable.
In particular, show what each filename changes to as it progresses through the
selected optional changes.

=item * B<--version>

Display version info and exit.

=item * B<-x> OR B<--normalizeExtensions>

Normalize a variety of extensions to 3-letter lower-case form
(use I<--help-x> to display a list).
See also I<--addExtension> and I<--extChanges>.

=back


=head1 Known bugs and limitations

Need a conflict resolution suffix for case-insensitive file systems if the
rename only changes case (and thus looks different to the code, but not to a
case-insensitive filesystem).

I<--filesystem> is unfinished.

Changes with I<--extensions> put in 2 dots.

Unicode filenames are not thoroughly tested (and handling may depend on how
your locale is set).

Serial numbers with I<--resolve> may be placed after a file extension;
the fix is little tested.

There is no option to change the set of allowed characters with I<--clean>.

There is no option to change the set of extension mappings used by I<-x>.

Regexes may include an C<options> portion, but it is not used.

Does not know about some backup conventions, such as foo~, #foo#, or
C<emacs>'s ability to put backups into a separate directory:

    (setq backup-directory-alist `(("." . "~/.saves")))

I<--pull> doesn't do anything smart if there are
embedded "//", "/./", or "/../" in any paths. It should probably
call C<realpath> or similar first.

It would be nice to be able to pull user- and group-names,
image and/or file-system metadata, etc. into filenames. On Mac OS,
file-system metadata (xattrs)is available with commands like:

    mdls [files]
    mdls -name kMDItemWhereFroms [files]

Date formats should be more flexible, controllable, and localizable.

There should be an option to remove a matched date, not just copy it to
the front.

=head2 Security implications

Because regex changes (see I<-e>) can include back- and variable-references
on the right-hand side ($1, \1, etc.), the changes are carried out using an
I<eval>(). This could lead to injection vulnerabilities.


=head1 Related commands

=head2 *nix commands

The *nix C<rename> command is similar, and commonly available on Linux
(but not on BSD and Mac OSX).
However, it can only do shell wildcards (not full regular expressions).
Some Linuces have a C<rename> that uses Perl regexes.
However, the usual C<rename>s lack features such as
I<--ancestor>, I<--bactrianize>, I<--camelize>, I<--clean>, I<--dates>,
I<--moddates>, I<--resolve>, I<--pad>, I<--pull>, and I<-x>.
Most also lack name conflict resolution, a I<--dry-run> mode, etc.

Simple batch renames can also be done with the C<bash for> command:

    for x in abc*; do
        y=`echo "$x" | sed "s/foo/bar/g"`
        echo "Renaming file '$x' to '$y'"
        mv $x $y
    done

In `zsh` as opposed to `bash` you can use `zmv` to achieve renames like:

    zmv "(*).jpeg" "$1.jpg"
    zmv "(*)-backup.(*)" "backups/$1.$2"


=head2 SJD commands

C<whereFrom> -- Has a I<--pull> option that does renaming like
the I<--pullURI> option here (by default it just displays the source URI).
C<whereFrom> can also re-organize files into directory trees based on the paths
in their source URIs.

C<flattenDirs> -- Move all descendants of the current directory up into the
current directory, prefixing the intermediate directory names to the filenames
(separated by "_") instead of "/").

C<groupFiles> -- Normalize file names and move files into sub-folders
based on common parts of their names, ignoring any final digits.

C<lowerExtension> -- Force file extensions to lower case.

C<splitBigDir> -- Group files into several other directories, based on the
first letter(s) of the files' names (or a few other things).


=head1 To do

=over

=item * Apparently MacOS favors Unicode NFD (Canonical Decomposition),
while others like NFC (Canonical Decomposition + Composition). Deal.

=item * Add synonym options for case types like:

    camelCase (or lowerCamelCase) — myVariableName
    PascalCase (or UpperCamelCase) — MyClassName
    snake_case — my_variable_name
    SCREAMING_SNAKE_CASE — MY_CONSTANT
    kebab-case (or lisp-case) — my-function-name
    SCREAMING-KEBAB-CASE — MY-CONSTANT (rare)
    Train-Case — My-Function-Name (HTTP headers)
    flatcase — myvariablename (no separators at all)
    UPPERFLATCASE — MYVARIABLENAME

=item * Watch for filesystem-specific reserved names, etc:

Windows:
    Always reserved (any extension or none):
        CON, PRN, AUX, NUL
        COM1 through COM9
        LPT1 through LPT9
    Can't end with space or period (gets silently stripped)
    <>:"|?* are illegal in names
    Path component can't be just . or ..

macOS:
    : is illegal (legacy from HFS using it as path separator)

Unix/Linux:
    Only / and null are truly illegal, but newlines are problematic

For munging reserved names, common strategies:
    Prefix with _ → _CON.txt
    Append _ → CON_.txt
    Add tilde → CON~.txt
    Percent-encode → %43ON.txt (ugly but reversible)

=item * Check and warn on git files even if they don't ask?

=item * Warn/fix hyphen-initial filenames, names w/ spaces
(in *nix these are annoying though not illegal).

=item * Option to operate *only* on directories.

=item * I<--clean> should also do I<--addExtension> 'txt' (for non-dirs).

=item * Option to make I<--camelize> and I<--bactrianize> use (e.g.) "_" instead
of " " (can do with a regex change in the meantime).

=item * Make I<--bactrianize> not put space after hyphens.

=item * Unicode issues, esp nbsp (U+A0) with I<--dates>.

=item * "To" vs "_to_" vs "2"?

=item * Feature to increment, or make contiguous, numeric portions of filenames?
Cf C<nextFilename>.

=item * Do something better with case-change-only renames on case-insensitive systems.

=item * Option to affect only the first (or Nth?) match with I<--expr>.

=item * Make --dropOriginal apply to other
options (not just --pullContent), that similarly apend brand-new,
likely-unique strings to the filenames.

=item * Port to Python and integrate PowerWalk.py.

=item * Options to set properties on files, like Mac OS label? (see list below)
l<http://superuser.com/questions/168927/>
com.apple.metadata:_kMDItemUserTags

=item * Idea of pulling metadata from PDF into filename.
L<https://stackoverflow.com/questions/44598758> or "cermine".
Cf L<https://academia.stackexchange.com/questions/139733/how-to-manage-publications-on-a-local-computer?rq=1>
L<https://stackoverflow.com/questions/50575957/how-to-robustly-extract-author-names-from-pdf-papers>
L<https://www.tutorialexample.com/python-extract-pdf-paper-title-by-content-not-by-metadata-a-step-guide-python-tutorial/>
L<https://stackoverflow.com/questions/1813427/extracting-information-from-pdfs-of-research-papers>
L<https://pypi.org/project/scholarly/>
PyPDF2, cb2bib, TET, Cermine.

=item * Add a way to reference Mac fs metadata in I<--expr> RHS.

=item * pull checksum of the file into metadata or name?

=item * I<--ePad> only allows I<left> padding at present.

=item * Various date/time improvements:

=over

=item * Option to add periodic dates (esp. by month) to a series of files,
for example downloaded bank statements that the bank just sends as "statement.pdf".
Just do in the order specified; that works whether they're in dated folders
(those could also be done via --pull), or all in one with OS-generated
names like "foo copy 5.pdf". E.g.:
    renameFiles --startMonth 2022-03 ./bankOfSumeria/statement*.pdf

=item * Access to additional data to pull into name.

=item * Allow localized date formats and month names, or C<strftime> formats.

=item * Add times and datetimes to I<--addstat>.

=item * Option to extract MIME "Date:" from .eml files.

=item * Option to normalize date format without moving to start/end.

=item * Make sure pulling in [abcm]time doesn't duplicate date already present?

=back

=back


=head1 History

=over

=item * 2006-12-18: Written by Steven J. DeRose.

=item * 2007-01-23: Tweak doc. Add -p, -x.

=item * 2007-12-03 sjd: strict.

=item * 2009-06-24 sjd: Debug....

=item * 2009-08-20 sjd: Debug....

=item * 2010-09-12 sjd: Cleanup, Getopt.

=item * 2011-05-25 sjd: More cleanup. Don't skip first file listed. Add I<--dirs>.

=item * 2012-02-06 sjd: Move regex to option. Allow non-Latin \\w,  I<--test>.
Add C<doRename()> and change from system C<mv> to Perl rename(). sjdUtils.
Put serializers before extension! Add I<--pull> to pack ancestor dir
name(s) onto front of filenames.

=item * 2012-04-10 sjd: Add I<--force>, I<--recurse>, I<--ancestor>, I<--lc>.

=item * 2013-01-09 sjd: Clean up. Add I<--camelize>. OS stuff like "Copy N of ...".
Add I<--dates>, I<--addExtension>, I<--toEnd>, I<--copies>.

=item * 2013-10-15: I<--pull> w/o I<--expr>. Add I<--ignoreCase>, I<--sep>.
I<--copies> earlier. Use C<vMsg()>. Clean up path vs. name distinction.

=item * 2013-12-21: Add I<--pullURI>.

=item * 2014-01-09ff: Fix I<--dates>, I<--pullURI>. Add I<--moddates>.

=item * 2014-03-27: Add I<--ePad>.

=item * 2014-05-09ff: Add I<--unescapeURI>, I<-x>. Count/report extension changes.

=item * 2014-08-22: Fix recursion. Separate splitPath, joinPath.

=item * 2014-12-15: Add I<--bactrianize>.

=item * 2015-02-25ff: Fix bugs that prevented backreferences with I<-e>,
and RHS like "11-4" becoming "7" due to eval. Add I<--dot>, fix I<--dates>.

=item * 2015-08-04: Remember to include Encode. Use C<strftime()> for month names.
Change I<--moddate> to I<--addStat statName>.

=item * 2017-01-31: Add I<--unroman> to convert Roman to Arabic numerals.

=item * 2018-01-26: Add conflict check immediately before C<doRename()> acts.

=item * 2018-04-12: Missing return for I<--expr>. Add I<-v> messages. Fix I<--addStat>.

=item * 2018-08-09: Finish I<--extChanges>. Add I<--uc>. Split out variousChanges().

=item * 2018-10-16: Use C<file> command with I<--addExtension> "!".

=item * 2019-10-29: Clean up expr parsing logic. Add I<--dropExtensions>, I<--onlyExt>.
Start I<--kmdAdd>, I<--kmdList>.

=item * 2020-06-26: New layout. Add I<--dateYears>.

=item * 2020-10-12: Rename I<--kmdXXX> to I<--xattrXXX>, I<--onlyExt> to
I<--onlyExtensions>. Add I<--extensions> synonym.

=item * 2021-02-16: Add I<--lcExtensions>.

=item * 2021-04-27: Start I<--filesystem>.

=item * 2022-01-07: Fix bug with name conflicts when there's no extension.
Still not great for case-insensitive file-systems when you change only case.
But now notices and reports them, at least.

=item * 2022-03-30: Clean up doc. Drop alogging.

=item * 2022-07-18: Put alogging back.

=item * 2022-08-14: Add --dropOriginal.

=item * 2022-09-29: Add "git mv" support via my C<versionStatus.py>.

=item * 2022-12-08: Clean up help text and file-system spec table.

=item * 2024-06-05: Improve stat reporting. Drop use of C<versionStatus.py>.
Make --dateOutput an option, and integrate strftime. Add --dateTest.

=back


=head1 Rights

Copyright 2006-12-18 by Steven J. DeRose. This work is licensed under a
Creative Commons Attribution-Share Alike 3.0 Unported License.
For further information on this license, see
L<https://creativecommons.org/licenses/by-sa/3.0>.

For the most recent version, see L<http://www.derose.net/steve/utilities> or
L<https://github.com/sderose>.


=cut


###############################################################################
# Get month names from locale (see http://perldoc.perl.org/perllocale.html
# and man(7) strftime (days of week are %a %A)
#
my %monthDict = ();
for (my $i=0; $i<12; $i++) {
    # strftime counts months from 0-11, we want 1-12....
    my $m = strftime("%B", 0, 0, 0, 1, $i, 96);  # Full name
    $monthDict{$m} = $i + 1;
    $m = strftime("%b", 0, 0, 0, 1, $i, 96);  # Abbreviated name
    $monthDict{$m} = $i + 1;
}

my $monthExpr = join("|", keys(%monthDict));
# Allow for no-break space U+00A0, which is NOT included in \s!
my $nbsp = chr(0xA0);

# TODO: \\b is bad if adjacent char is "_".... neg lookbehind: (?<![\w_])
# TODO: Accepts mdays like 39, mon like 29, period after full month name,....
#
my $date1expr  = qr/\b([01]?\d)\/([0-3]?\d)\/(\d{4})\b/;    # 12/31/1999
my $dateUKexpr = qr/\b([0-3]\d)\/([01]\d)\/(\d{4})\b/;      # 31/12/1999
my $date2expr  = qr/\b($monthExpr)\.?[\s\xA0]*([0-3]?\d?)?[,\s\xA0][\s\xA0]*(\d{4})\b/;
my $date3expr  = qr/\b([0-3]?\d?)[,\s\xA0]($monthExpr)\.? (\d{4})\b/;  # 31 Dec 1999
my $date4expr  = qr/\b(\d{4})-([01]\d)(?:-([0-3]?\d))?\b/;  # 1999-12-31 (ISO 8601)
my $date5expr  = qr/\b(\d{4})([01]\d)([0-3]\d)\b/;          # 19991231

# Names and indexes of the fields of a file stat block.
# Strings that user can use to specify what to add with --addStat.
#
my %statKeys = (
      0          => 0,
      1          => 1,
      2          => 2,
      3          => 3,
      4          => 4,
      5          => 5,
      6          => 6,
      7          => 7,
      8          => 8,
      9          => 9,
     10          => 10,
     11          => 11,
     12          => 12,
    "adate"      => 8,
    "cdate"      => 10,
    "mdate"      => 9,
#    "atime"      => 8,
#    "ctime"      => 10,
#    "mtime"      => 9,
#    "adatetime"  => 8,
#    "cdatetime"  => 10,
#    "mdatetime"  => 9,
    "blksize"    => 11,
    "blocks"     => 12,
    "dev"        => 0,
    "gid"        => 5,
    "ino"        => 1,
    "mode"       => 2,
    "nlink"      => 3,
    "rdev"       => 6,
    "size"       => 7,
    "uid"        => 4,
);

# Mac filesystem xattr metadata (all keys start with "kMDItem").
# See metadata attributes for a file with "mdls" command on Mac.
# Planning to add a way to reference these in --expr RHS.
#
my %macMeta = (
    # Name                              Example value
    "kMDItemContentCreationDate"     => "2015-03-17 15:28:56 +0000",
    "kMDItemContentModificationDate" => "2015-03-17 15:28:56 +0000",
    "kMDItemContentType"             => "public.tab-separated-values-text",
    "kMDItemContentTypeTree"         => [
        "public.tab-separated-values-text",
        "public.delimited-values-text",
        "public.text",
        "public.data",
        "public.item",
        "public.content"
    ],
    "kMDItemDateAdded"               => "2015-03-17 15:28:56 +0000",
    "kMDItemDisplayName"             => "lexicon.tsv",

    "kMDItemFSContentChangeDate"     => "2015-03-17 15:28:56 +0000",
    "kMDItemFSCreationDate"          => "2015-03-17 15:28:56 +0000",
    "kMDItemFSCreatorCode"           => "",
    "kMDItemFSFinderFlags"           => "0",
    "kMDItemFSHasCustomIcon"         => "(null)",
    "kMDItemFSInvisible"             => "0",
    "kMDItemFSIsExtensionHidden"     => "0",
    "kMDItemFSIsStationery"          => "(null)",
    "kMDItemFSLabel"                 => "0",
    "kMDItemFSName"                  => "lexicon.tsv",
    "kMDItemFSNodeCount"             => "(null)",
    "kMDItemFSOwnerGroupID"          => "20",
    "kMDItemFSOwnerUserID"           => "501",
    "kMDItemFSSize"                  => "15957",
    "kMDItemFSTypeCode"              => "",

    "kMDItemKind"                    => "Plain Text Document", # see below
    "kMDItemLogicalSize"             => "15957",
    "kMDItemPhysicalSize"            => "16384",

    "kMDItemAuthor"                  => "",  # Some programs set this: many don't
    "kMDItemContributors"            => "",  #
    "kMDItemCountry"                 => "",  #
    "kMDItemCreator"                 => "",  #
    "kMDItemLastUsedDate"            => "",  #
    "kMDItemTextContent"             => "",  #
    "kMDItemTitle"                   => "",  #
    "kMDItemWhereFroms"              => "",  # URI downloaded from (when applicable)
    "kMDItemComposer"                => "",  # iTunes often sets this

    # Additional Image meta (see C<spot -h>)
    "kMDItemAlternateNames"          => [
        "Screen Shot 2014-05-10 at 8.06.13 PM.png"
    ],
    "kMDItemBitsPerSample"           => "32",
    "kMDItemColorSpace"              => "RGB",
    "kMDItemContentTypeTree"         => [
        "public.png",
        "public.image",
        "public.data",
        "public.item",
        "public.content"
    ],
    "kMDItemHasAlphaChannel"         => "0",
    "kMDItemIsScreenCapture"         => "1",
    "kMDItemOrientation"             => "0",
    "kMDItemPixelCount"              => "101952",
    "kMDItemPixelHeight"             => "216",
    "kMDItemPixelWidth"              => "472",
    "kMDItemProfileName"             => "Color LCD",
    "kMDItemResolutionHeightDPI"     => "144",
    "kMDItemResolutionWidthDPI"      => "144",
    "kMDItemScreenCaptureType"       => "selection",
);

# Some values, there are many more. Some of these seem redundant or
# inconsistent. Where do they actually come from?
#
my @kMDItemKind_values = (
    "Alias",
    "Disk Image",
    "Folder",
    "gzip compressed archive",
    "ZIP archive",

    # Code
    "C Source",
    "C++ Source",
    "Emacs Lisp Source File",
    "JavaScript script",
    "Objective-C++ Source",
    "Perl Source",
    "PHP Script",
    "Python Bytecode Document",
    "Python Script",
    "Python Source",
    "Script",
    "Shell Script",
    "Unix Executable File",

    # Document-ish
    "BBEdit text document",
    "CSS style sheet",
    "CSV Document",
    "Document Type Definition",
    "Document",
    "HTML document",
    "Markdown Document",
    "JSON Document",
    "Keynote Presentation",
    "Microsoft Excel Document",
    "Microsoft Word Document",
    "OpenDocument Text (.odt) Document",
    "Oxygen XML Editor project",
    "Pages Document",
    "Rich Text Document",
    "SimpleText Document",
    "Text",
    "TSV Document",
    "vCard",
    "XML document",
    "XML Document",
    "XML Schema Document",

    # Image-ish
    "ConceptDraw CDDZ Document",
    "Graph Markup Language",
    "JPEG image",
    "Panasonic raw image",
    "PDF document",
    "Plain Text Document",
    "PNG image",
    "PostScript document",
    "PostScript",
);

# See https://en.wikipedia.org/wiki/Comparison_of_file_systems
#
my $BY = "bytes"; my $UC = "UChar";
my $AS = "ASCII"; my $MS = "cp1252";
my $U8 = "UTF-8"; my $U2 = "UCS-2"; my $U6 = "UTF-16";
my $KB = 1<<9; my $MB = 1<<19; my $GB = 1<<29;
my $TB = 1<<39; my $PB = 1<<49; my $EB = 1<<59; my $ZB = 1<<69;
my $UNLIM = -1;
my $XX = 0;  # Unknown or unspecified value

# Expressions for banned characters
my $NULL = "[\\x00]";
my $NULLSOL = "[\\x00/]";
my $CPMBAN = "[<>.,;:=?*\\[\\]]";
my $FAT16BAN = "[\\x00-\\x1F \"*+,./:;<=>?\\\\[\\]]";
my $FAT16LFN = "[\\x00\"*/:<>?\\\\|]";
my $GEMBAN = "[\\x00-\\x1F *./:?\\\\{}]";
my $NSFW32BAN = "[\\x00/\\:*\"?<>|]";

# Column numbers for the data items below
#
my $FS_MAXNAME = 0;      # If not an int, fractional part is extension limit (always 3?)
my $FS_CASE_REGARD = 1;  # Does it regard case?
my $FS_UNIT = 2;         # Is FS_MAXNAME measured in bytes or chars?
my $FS_ENCODING = 3;
my $FS_MAXPATH = 4;      # Max char/bytes length of entire path (not # components)
my $FS_MAXFSIZE = 5;     # Max supported filesize
my $FS_MAXVOL = 6;       # Max supported volume size
my $FS_BANCHARS = 7;     # Characters just not permitted.

my %filesystemsAvailable = (
    # Name =>      MxName,cs,unit, Enc,MxPath,MxFSize,  MxVol, BanChars
    "BeeGFS" =>     [ 255, 1, $BY, $XX, $XX,   16*$EB, 16*$EB, $NULL ],
    "CP/M" =>       [ 8.3, 1, $BY, $AS, 0,     32*$MB,512*$MB, $CPMBAN ],
    "RT-11 " =>     [ 6.3, 0, $BY, $AS, 0,     32*$MB, 32*$MB, "[^A-Z0-9\$]" ],
    "V6FS" =>       [  14, 1, $BY, $XX, $XX,   16*$MB, 32*$MB, $NULLSOL ],
    "CBM DOS" =>    [  16, 1, $BY, $XX, 0,     16*$MB, 16*$MB, $NULL ],
    "V7FS" =>       [  14, 1, $BY, $XX, $XX,    1*$GB,  2*$TB, $NULLSOL ],
    "exFAT" =>      [ 255, 1, $UC, $XX, 32760, 16*$EB, 64*$ZB, $XX ],
    "FAT8" =>       [ 6.3, 1, $BY, $AS, 0,        $XX,    $XX, "[\\x80-\\xFF]" ],  # ??
    "FAT16 base" => [ 8.3, 1, $BY, $MS, $XX,   32*$MB, 32*$MB, $FAT16BAN ],
    "FAT16 LFN" =>  [ 255, 1, $UC, $XX, $XX,    4*$GB, 32*$MB, $FAT16LFN ],
    "FAT16B" =>     [ 8.3, 1, $BY, $MS, $XX,    2*$GB,  4*$GB, $XX ],
    "FAT32" =>      [ 8.3, 1, $BY, $MS, 32760,  4*$GB, 16*$TB, $XX ],
    "FATX" =>       [  42, 1, $BY, $AS, $XX,    2*$GB,  2*$GB, $XX ],
    "GEMDOS" =>     [ 8.3, 1, $BY, $AS, $XX,      $XX,    $XX, $GEMBAN ],
    "APFS" =>       [ 255, 1, $UC, $U8, $XX,    8*$EB,    $XX, $XX ],
    "F2FS" =>       [ 255, 1, $BY, $XX, $XX, 3.94*$TB, 16*$TB, $NULLSOL ],
    "MFS" =>        [ 255, 1, $BY, $XX, 0,    256*$MB,256*$MB, ":" ],
    "HFS" =>        [  31, 1, $BY, $XX, $UNLIM, 2*$GB,  2*$TB, ":" ],
    "HPFS" =>       [ 255, 1, $BY, $XX, $XX,    2*$GB,  2*$TB, $NULL ],
    "NTFS_Win32" => [ 255, 0, $UC, $U6, 32767, 16*$EB, 16*$EB, $NSFW32BAN ],
    "NTFS_POSIX" => [ 255, 1, $UC, $U6, 32767, 16*$EB, 16*$EB, $NULLSOL ],
    "HFS Plus" =>   [ 255, 1, $UC, $U6, $UNLIM, 8*$EB,  8*$EB, $XX ],
    "UFS1" =>       [ 255, 1, $BY, $XX, $XX,  256*$TB, 16*$EB, $NULL ],
    "UFS2" =>       [ 255, 1, $BY, $XX, $XX,   32*$PB,512*$ZB, $NULL ],
    "ext" =>        [ 255, 1, $BY, $XX, $XX,    2*$GB,  2*$GB, $NULL ],
    "ext2" =>       [ 255, 1, $BY, $XX, $XX,    2*$TB, 32*$TB, $NULL ],
    "ext3" =>       [ 255, 1, $BY, $XX, $XX,    2*$TB, 32*$TB, $NULL ],
    "ext4" =>       [ 255, 1, $BY, $XX, $XX,   16*$TB,  1*$EB, $NULL ],
    "ISO9660:881" =>[ 8.3, 1, $XX, $XX, $XX,    4*$GB,  8*$TB, $XX ],
    "ISO9660:882" =>[ 180, 1, $XX, $XX, $XX,    4*$GB,  8*$TB, $XX ],
    "ISO9660:883" =>[ 180, 1, $XX, $XX, $XX,    8*$TB,    $XX, $XX ],
    "Joliet_CDFS" =>[  64, 1, $UC, $U2, $XX,    8*$TB,  8*$TB, "[*/\\:;?]" ],
    "Rock Ridge" => [ 255, 1, $BY, $XX, $XX,    8*$TB,  8*$TB, $NULLSOL ],
    "UniFS" =>      [ $XX, 1, $XX, $XX, $XX,      $XX,    $XX, $XX ],
    "ISO9660:1999"=>[ $XX, 1, $XX, $XX, $XX,      $XX,    $XX, $XX ],
    "HighSierra" => [ $XX, 1, $XX, $XX, $XX,      $XX,    $XX, $XX ],
);


###############################################################################
# Options
#
my $addExtension    = "";
my $addStat         = "";
my $ancestor        = 0;
my $bactrianize     = 0;
my $camelize        = 0;
my $clean           = 0;
my $cleanChars      = "-\\.\\w";
my $color           = ($ENV{CLI_COLOR} && -t STDERR) ? 1:0;
my $copies          = 0;
my $dates           = 0;
my $dateOutput      = "%Y-%m-%d";
my $dateTest        = 0;
my $dateYears       = 0;
my $dirs            = 1;
my $dot             = 0;
my $dropExtensions  = 0;
my $dropOriginal    = 0;
my $dryRun          = 0;
my $expr            = "";
my $ePad            = 0;
my $ePadChar        = "0";
my $extChanges      = 0;
my $filesystem      = '';
my $force           = 0;
my $gitMoves        = 0;
my $ignoreCase      = 0;
my $xattrAdd        = "";
my $lc              = 0;
my $lcExtensions    = 0;
my $onlyExtensions  = 0;
my $padWidth        = 3;
my $pull            = 0;
my $pullNoEntities  = 0;
my $pullContent     = 0;
my $pullURI         = 0;
my $quiet           = 0;
my $recursive       = 0;
my $resolve         = 1;
my $separator       = "_";
my $toEnd           = 0;
my $uc              = 0;
my $uk              = 0;
my $unescapeURI     = 0;
my $unroman         = 0;
my $verbose         = 0;
my $x               = 0;

my %extensionMap = ();
my @fileToExt    = ();
my %suffixes     = ();
makeExtensionMap();


my %getOptHash = (
    "addExtension=s"   => \$addExtension,
    "addStat=s"        => \$addStat,
    "ancestor!"        => \$ancestor,
    "bactrianize|camelToSpace|camel2Space!" => \$bactrianize,
    "camelize!"        => \$camelize,
    "clean!"           => \$clean,
    "color!"           => \$color,
    "copies!"          => \$copies,
    "dateOutput=s"     => \$dateOutput,
    "dates!"           => \$dates,
    "dateTest!"        => \$dateTest,
    "dateYears!"       => \$dateYears,
    "dirs!"            => \$dirs,
    "dot!"             => \$dot,
    "dropExtensions!"  => \$dropExtensions,
    "dropOriginal!"    => \$dropOriginal,
    "dryRun|dry-run|test!" => \$dryRun,
    "e|expr=s"         => \$expr,
    "ePad=o"           => \$ePad,
    "ePadChar=s"       => \$ePadChar,
    "extChanges|extensions!" => \$extChanges,
    "filesystem=s"     => \$filesystem,
    "force!"           => \$force,
    "gitMoves!"        => \$gitMoves,
    "h|help"           => sub { system "perldoc $0"; exit; },
    "help-filesystem"  => sub {
        warn "File system properties:\n";
        warn "    (see https://en.wikipedia.org/wiki/Comparison_of_file_systems)\n";
        warn "Name      MaxFname case unit   Encod   MaxPath  " .
          " MaxFileSz  MaxVol BannedChars\n";
        my $fmt="%-12s %5d %4s %-6s %-6s %8s %8sB %8sB %s\n";
        for my $x (sort keys %filesystemsAvailable) {
            my @f = @{$filesystemsAvailable{$x}};
            (scalar @f == 8) || die "Bad rec: " . join(@f, ", ") . "\n";
            warn sprintf($fmt, $x, $f[0], $f[1] ? "R":"I", $f[2], $f[3], $f[4],
                sjdUtils::toHNumber($f[5]), sjdUtils::toHNumber($f[6]),
                sjdUtils::showInvisibles($f[7]));
        }
        exit;
    },
    "help-x"           => sub {
        warn "Extensions mapped by the -x option:\n";
        for my $x (sort keys %extensionMap) {
            my $m = sprintf "%8s -> %s\n", $x, $extensionMap{$x};
            warn $m;
        }
        exit;
    },
    "i|ignoreCase!"    => \$ignoreCase,
    "xattrAdd=s"       => \$xattrAdd,
    "xattrList"        => sub {
        warn "Item names for the --xattrAdd option (see also the 'mdfind' command:\n";
        for my $k (sort keys %macMeta) {
            if (ref $macMeta{$k} eq ref) {
                print ("        Omitted some...\n");
            }
            print ("    $k\n");
        }
        exit;
    },
    "lc|lower!"        => \$lc,
    "lcExtensions|lowerExtensions!" => \$lcExtensions,
    "onlyExtensions!"  => \$onlyExtensions,
    "pad=o"            => \$padWidth,
    "pull=o"           => \$pull,
    "pullContent!"     => \$pullContent,
    "pullNoEntities!"  => \$pullNoEntities,
    "pullURI=o"        => \$pullURI,
    "q|quiet!"         => \$quiet,
    "r|recursive!"     => \$recursive,
    "resolve!"         => \$resolve,
    "separator=s"      => \$separator,
    "toEnd!"           => \$toEnd,
    "uc|upper!"        => \$uc,
    "uk!"              => \$uk,
    "unescapeURI!"     => \$unescapeURI,
    "unroman!"         => \$unroman,
    "v|verbose+"       => \$verbose,
    "version"          => sub {
        die "Version of $VERSION_DATE, by Steven J. DeRose.\n";
    },
    "x|normalizeExtensions!" => \$x,
    );

Getopt::Long::Configure ("ignore_case");
GetOptions(%getOptHash) || die "Bad options.\n";

sjdUtils::setVerbose($verbose);
sjdUtils::setColors($color);

my $cleanExprC  = qr/[^$cleanChars]/;
my $cleanExtensions = 0;

if ($dateTest) {
    testDates();
    exit;
}

($padWidth >= 1) || die "Invalid --padwidth value '$padWidth'.\n";

if ($addStat && !defined $statKeys{$addStat}) {
    die "Unknown stat field name/number '$addStat' for --addStat. Known: " .
        join(", ", sort keys %statKeys) . ".\n";
}

($filesystem && !defined $filesystemsAvailable{$filesystem}) && die
    "--filesystem $filesystem not known. Check --help-filesystems.\n";

# The user's -e change expression (if any)
$expr =~ s/^\s*s?//;
my $xx         = "";
my $frExpr     = "";
my $toExpr     = "";
my $op         = "";
if ($clean) {
    if ($expr) {
        eMsg(-1, "Cannot use both --clean and --expr.");
    }
    $frExpr = "[^" . $cleanChars . "]";
    $toExpr = $separator;
}
elsif ($expr) {
    my $delim = "\\" . substr($expr,0,1);
    my @tokens = split(/$delim/, $expr);
    vMsg(1, sprintf("delim '%s', split regex '%s' to: #%s#].",
        $delim, $expr, join("#", @tokens)));
    $xx = (scalar @tokens >= 1) ? $tokens[0] : "";   #  "s" optional
    $frExpr = (scalar @tokens >= 2) ? $tokens[1] : "";
    $toExpr = (scalar @tokens >= 3) ? $tokens[2] : "";
    $op = (scalar @tokens >= 4) ? $tokens[3] : "";

    vMsg(1, "Parsed -expr as: from '$frExpr', to '$toExpr', options '$op'.");
    ($frExpr eq "") &&
        die "Can't have nil 'from' value in change expression '$expr'.\n";
    ($frExpr =~ m/\\\.\w+/ && !$onlyExtensions && !$extChanges) &&
        vMsg(0, "Warning: Your 'from' looks like an extension (see --extChanges and --onlyExtensions)");
    ($op && !$quiet) &&
        vMsg(0, "-expr /options are not yet supported.");
    vMsg(1, "Changing:\n  /$frExpr/$toExpr/");
}
elsif (!$pull && !$pullURI && !$pullContent && !$xattrAdd &&
       !$dates && !$dateYears && !$addStat &&
       !$x && !$bactrianize && !$camelize && !$unescapeURI) {
    vMsg(0, "Did you specify an action?");
}

(scalar(@ARGV)>0) || die
    "Example: renameFiles -e 's/from/to' [files]\n";

if ($xattrAdd) {
    if ($xattrAdd !~ m/^kMDItem/) { $xattrAdd = "kMDItem" . $xattrAdd; }
    (defined $macMeta{$xattrAdd}) || die
        "MacOS mdfind metadata item not found for -xattrAdd: '$xattrAdd'.\n";
}


###############################################################################
# Main
#
# Stats for report() to show at end.
my $fileCount        = 0;
my $dirCount         = 0;
my $weirdCount       = 0;  # Neither dir nor file
my $notFoundCount    = 0;
#
my $unchanged        = 0;
my $simpleCount      = 0;
my $extFixes         = 0;
my $forceCount       = 0;
my $resolveCount     = 0;
my $conflictCount    = 0;
my $caseIssueCount   = 0;
my $failCount        = 0;
my $gitCount         = 0;
my $path             = "";

my $roman = "\b([ivxlcm]+|[IVXLCM]+)\b";
my $romanC = qr/$roman/;
my $frC  = qr/$frExpr/;

foreach my $fullPath (@ARGV) {
    $fullPath = decode("utf8", $fullPath);
    doOneItem($fullPath);
} # foreach

($quiet) || report();

exit;


###############################################################################
#
# Separate path, name, and extension
sub rfsplitPath {
    my ($fullPath) = @_;
    my $path = my $name = my $ext = "";
    my $lastSlash = rindex($fullPath, "/");
    if ($lastSlash>=0) {
        $path = substr($fullPath,0,$lastSlash);
        $name = substr($fullPath,$lastSlash+1);
    }
    else {
        $path = "";
        $name = $fullPath;
    }

    if ($name =~ m/(.*)\.([^.]{1,4})$/) {
        $name = $1;
        $ext = $2;
    }
    vMsg(2, "\nParsed '$fullPath' as:\n" .
        "  path '$path', name '$name', ext '$ext'");
    return($path, $name, $ext);
}

# Put together path, name, and extension
sub rfjoinPath {
    my ($path, $name, $ext) = @_;
    my $fullPath = ($path) ? "$path/$name" : $name;
    $fullPath = extensionJoin($fullPath, $ext);
    return($fullPath);
}

# The path comes in as UTF-8, at least on MacOSX.
#
sub doOneItem {
    my ($fullPath) = @_;
    if ($fullPath =~ m/([^ -~]+)/) {
        vMsg(1, showInvisibles("Warning: Non-ASCII in filename '$fullPath': '$1'\n"));
    }
    vMsg(1, "====\nStarting item: '" . $fullPath . "'");

    #if (my $vcs = whatVCS($fullPath)) {
    #    vMsg(0, "====Seems to be owned by $vcs: $fullPath.");
    #    return;
    #}

    my ($path, $name, $ext) = rfsplitPath($fullPath);
    my $fullName = extensionJoin($name, $ext);

    my $newExt = "";  # See also under -expr with -extChanges
    if ($x && ($newExt = $extensionMap{lc($ext)})) {
        vMsg(2, "extensionMap");
        $ext = $newExt;
        $extFixes++;
    }
    my $nameescaped = $name;
    # $nameescaped =~ s/'/\\'/g;

    if (!-e "$fullPath") {
        $notFoundCount++;
        ($quiet) || eMsg(0, "File '$fullPath' not found.");
        return;
    }

    if (-d "$fullPath") { # Recurse before renaming dir
        vMsg(2, "Got a directory: '$fullPath'");
        $dirCount++;
        if ($recursive) {
            opendir(my $dirh, $name);
            while (my $child = readdir($dirh)) {
                $child = decode("utf8", $child);
                next if ($child eq "." || $child eq "..");
                next if (!$dot && substr($child,0,1) eq ".");
                doOneItem("$fullPath/$child");
            }
            close($dirh);
        }
        if (!$dirs) {
            vMsg(1, "Skipping directory '$name'.");
            return;
        }
    }
    elsif (-f "$fullPath") {
        $fileCount++;
    }
    else {
        vMsg(0, "Item is not directory or file: $fullPath.\n");
        $weirdCount++;
        return;
    }

    vMsg(2, "Before changes:  '$name' '$ext'.");
    my $newItems = variousChanges($fullPath, $path, $name, $ext);

    my $name2 = $newItems->[0];
    my $ext2 = $newItems->[1];
    my $fullName2 = extensionJoin($name2, $ext2);
    my $fullPath2 = ($path ? "$path/":"") . $fullName2;

    vMsg(2, "After changes:  '$fullName' ('$name' '$ext') -> '$fullName2' " .
        "('$name2' '$ext2').\n    '$fullPath'\n    '$fullPath2'");

    if ($fullName2 eq $fullName) {                # No net change
        ($quiet) || vMsg(1, "Filename is unchanged: '$fullName'");
        $unchanged++;
    }
    elsif (!-e $fullPath2) {                      # Simple case (dirs & files)
        vMsg(2, "No conflict found for result name '$name2'");
        $simpleCount++;
        doRename($fullPath, $fullPath2);
    }
    # TODO Check for case-insensitive file-system match
    else {                                        # Handle output name conflict
        vMsg(2, "Result name is already in use: '$fullPath2'");
        $conflictCount++;
        if (lc($fullPath) eq lc($fullPath2)) { $caseIssueCount++; }
        if ($force) {
            vMsg(2, "Forcing...");
            $forceCount++;
            system "rm $fullPath2" || eMsg(
                0, "Unable to remove output item '$fullPath2'");
            doRename($fullPath, $fullPath2);
        }
        elsif (!$resolve) {
            ($quiet) || vMsg(0,
                "File '$fullPath' was not renamed, target '$fullPath2' exists.");
        }
        elsif (my $name3 = findFreeFilename($path, $name2, $ext2)) {
            my $path3 = rfjoinPath($path, $name3, $ext2);
            vMsg(1, "Found free filename: '$name3' (path '$path', ext '$ext2') -> '$path3').");
            doRename($fullPath, $path3);
            $resolveCount++;
        }
        else {
            ($quiet) || eMsg(0, "Unable to resolve '$name' -> '$name2'.");
            $failCount++;
        }
    }
} # doOneItem

# Implement the many kinds of changes that can be requested.
# Never changes the path before the final file/dir name.
#
sub variousChanges {
    my ($fullPath, $path, $name, $ext) = @_;

    my $name2 = $name;
    my $ext2 = $ext;
    if ($ext2 && $dropExtensions) {              # dropExtension
        $ext2 = "";
    }
    elsif ($ext2 && $lcExtensions) {             # lcExtensions
        $ext2 = lc($ext2)
    }

    if (!$ext2 && $addExtension ne "") {         # addExtension
        $extFixes++;
        if ($addExtension eq "!") {  # Try via "file" command
            my $fileInfo = `file "$fullPath`;
            for (my $i=0; $i < scalar(@fileToExt); $i++) {
                my $expr = $fileToExt[$i][0];
                if ($fileInfo =~ m/$expr/) {
                    $ext2 = $fileToExt[$i][1];
                    last;
                }
            }
        }
        else {
            $ext2 = $addExtension;
        }
    }


    if ($copies) {                               # dropExtension
        $name2 = doOsStuff($name2);
        vMsg(1, ">copies: '$name2'");
    }

    if ($pull > 0) {
        my @dirs = split("/",$path);
        while (scalar(@dirs)>0 && $dirs[-1] eq "") { pop @dirs; }
        for my $pcount (1..$pull) {
            last unless (scalar(@dirs)>=$pcount);
            vMsg(2, "        Prepending '$dirs[-$pcount]'");
            $name2 = $dirs[-$pcount] . $separator . $name2;
        }
        vMsg(1, ">pull  $pull: '$name2'");
    }

    if ($pullContent) {
        open(IFH, "<$fullPath");
        my $rec1 = <IFH>;
        close(IFH);
        chomp $rec1;
        $rec1 =~ s/<.*?>//g;
        if ($pullNoEntities) { $rec1 =! s/&.*?;//g; }
        $rec1 =~ s/[^\w.]+/_/g;
        $rec1 =~ s/^\._?/_/;
        if (!$rec1) {
            vMsg(0, "pullContent got '', nothing to pull.\n");
        }
        else {
            if ($dropOriginal) { $name2 = $rec1; }
            else { $name2 = $name2 . "_" . $rec1; }
        }
    }

    if ($pullURI > 0) {
        my $uri = getSourceURI($fullPath);
        if (!$uri) {
            vMsg(0, "Can't get source URI via 'xattrs' for '$fullPath'");
        }
        else {
            vMsg(1, "xattr returned: " . $uri);
            $uri =~ s@^\w+://@@;
            $uri =~ s/[#?].*//;
            my @dirs = split("/",$uri);
            while (scalar(@dirs)>0 && $dirs[-1] eq "") { pop @dirs; }
            pop @dirs;
            for my $pcount (1..$pullURI) {
                last unless (scalar(@dirs)>=$pcount);
                vMsg(2, "    Prepending '$dirs[-$pcount]'");
                $name2 = $dirs[-$pcount] . $separator . $name2;
            }
            vMsg(1, ">pullURI $pullURI:   '$name2'");
        }
    }

    if ($xattrAdd) {
        die "--xattrAdd is not yet finished.\n";

    }

    if ($unescapeURI) {
        vMsg(2, "unescapeURI");
        $name2 = sjdUtils::unescapeURI($name2);
    }

    if ($lc) {
        vMsg(2, "lc");
        $name2 = lc($name2);
        vMsg(1, "After -lc:    '$name2'");
    }
    if ($uc) {
        vMsg(2, "uc");
        $name2 = uc($name2);
        vMsg(1, "After -uc:    '$name2'");
    }

    if ($bactrianize) {
        vMsg(2, "bactrianize");
        $name2 =~ s/([^ [:upper:]])([[:upper:]])/$1 \U$2\E/g;
        $name2 =~ s/([- _])([[:lower:]])/ \U$2\E/g;

        $name2 =~ s/$separator / /g;
        vMsg(1, ">bactr: '$name2'");
    }

    if ($camelize) {
        vMsg(2, "camelize");
        $name2 =~ s/\s+(\S)/\U$1\E/g;
        vMsg(1, ">camel: '$name2'");
    }

    if ($addStat) {
        vMsg(2, "addStat for '$addStat'.");
        my $st = stat($fullPath);
        my $statNum = 0;
        if (!$st) { eMsg(0, "Can't stat '$fullPath' for --addStat."); }
        elsif ($addStat =~ m/^\d+$/) {
            $statNum = $addStat + 0;
        }
        else {
            $statNum = $statKeys{$addStat};
            ($statNum) || die "Unknown stat item '$addStat'.\n";
        }
        vMsg(2, "Stat index is $statNum.");
        my $statVal = ($st)[$statNum];
        if ($statNum==8 || $statNum==9 || $statNum==10) {
            $statVal = sjdUtils::isoDate($statVal);
        }
        $name2 = $statVal . $separator . $name2;
    }

    if ($dates) {
        vMsg(2, "dates for '$name2'.");
        $name2 = fixDates($name2);
    }

    if ($dateYears) {
        vMsg(2, "dateYears for '$name2'.");
        if ($name2 =~ s/([^-0-9])([12]\d\d\d)([^-0-9]|$)/$1$3/) {
            my $date = $2;
            if ($toEnd) { $name2 = insertBeforeExtension($name2, $date); }
            else { $name2 = "$date $name2"; }
            $name2 =~ s/\s+$//;
        }
    }

    if ($expr) {
        if ($onlyExtensions) {
            vMsg(1, "changing ext '$frExpr' to '$toExpr', fromC = /$frC/.");
            $ext2 = applyRegex($ext2, $frC, $toExpr);
            vMsg(1, "--expr, changed EXTENSION '$ext' to '$ext2'.");
        }
        if ($extChanges) {
            my $fullName = extensionJoin($name2, $ext);
            vMsg(1, "changing full name '$fullName': '$frExpr' => '$toExpr'.");
            my $fullName2 = applyRegex($fullName, $frC, $toExpr);
            ($name2, $ext2) = extensionSplit($fullName2);
            vMsg(1, "--expr, changed FULL NAME '$fullName' to '$fullName2' ('$name2', '$ext2').");
        }
        else {
            vMsg(1, "expr, changing '$frExpr' to '$toExpr', fromC = /$frC/.");
            $name2 = applyRegex($name2, $frC, $toExpr);
            vMsg(1, "--expr gives:  '$name2'");
        }
    }

    # Annoying case: avoid changing line 'i' etc. earlier in name?
    if ($unroman) {
        vMsg(2, "unroman");
        try_module("Text::Roman") || die "Cannot find Perl Roman module.\n";
        $name2 =~ s/$romanC/{ arabic($roman) if isroman($roman); }/e;
        vMsg(1, ">unrom: '$name2'");
    }

    if ($clean) {
        vMsg(2, "clean");
        $name2 =~ s/\s\s+/ /g;
        $name2 =~ s/$cleanExprC/$separator/g;
        vMsg(1, ">clean: '$name2'");
    }

    if ($filesystem) {
        $name2 = fixForFilesystem($fullPath, $name, $filesystem);
    }

    return [ $name2, $ext2 ];
} # variousChanges

# This is subtle because the user's "to" expression can have \1 or $1, etc.
# But it's worse: The "to" could also be "11-4" -- which evals to 7.
#
sub applyRegex {
    my ($name2, $lhs, $rhs) = @_;
    my $R = "";
    my $EV = '$R = ' . '"' . $rhs . '"';
    vMsg(2, "Eval for s/$lhs/$rhs/ in RHS will be: $EV.");
    vMsg(2, "Matches /$lhs/i? " . (($name2 =~ m/$lhs/i) ? "YES" : "NO"));
    if ($ePad) {
        if ($ignoreCase) {
            $name2 =~ s@$lhs@{ eval($EV); lpad($R,$ePad,$ePadChar); }@eig;
        }
        else {
            $name2 =~ s@$lhs@{ eval($EV); lpad($R,$ePad,$ePadChar); }@eg;
        }
    }
    else {
        if ($ignoreCase) { $name2 =~ s@$lhs@{ eval($EV); $R; }@eig; }
        else             { $name2 =~ s@$lhs@{ eval($EV); $R; }@eg;  }
    }
    return $name2;
}

# http://stackoverflow.com/questions/2405305
sub whatVCS {
    my ($fullPath) = @_;
    # Try GIT
    my $g = `git ls-files --error-unmatch $fullPath ; echo $?`;
    my $s = `git status --porcelain $fullPath `;
    #if ("$?") return 'git';
    # Try SVN
    # ...
    return '';
}

sub getSourceURI {
    my ($fullPath) = @_;
    my $cmd = "xattr -p com.apple.metadata:kMDItemWhereFroms '$fullPath'" .
        " | xxd -r -p";
    my $buf = `$cmd`;
    if (!$buf) { return(""); }
    $buf =~ s/^.*?http/http/;
    $buf =~ s/\x08\n.*//;
    return($buf);
}

sub extensionSplit {
    my ($fullName) = @_;
    my $name = $fullName;
    $name =~ s/\.[^.]*//;
    my $ext = substr($fullName, length($name));
    return ($name, $ext);
}

sub extensionJoin {
    my ($name, $ext) = @_;
    ($ext) || return $name;
    return $name . "." . $ext;
}

# FS_MAXNAME, FS_CASE_REGARD(UNUSED), FS_UNIT(TODO), FS_ENCODING,
# FS_BANCHARS, FS_MAXPATH, FS_MAXFSIZE(UNUSED), FS_MAXVOL(UNUSED).
# What do filesystems do about Unicode canonical forms?
#

sub fixForFilesystem {
    my ($path, $orig, $filesystem) = @_;
    my $name = $orig;
    my $sub = "_";
    my @fsProps = @{$filesystemsAvailable{$filesystem}};
    my $encoding = $fsProps[$FS_ENCODING];
    if ($encoding eq "ASCII") {
        $name =! s/[\x80-\xFF]//g;
    }
    elsif ($encoding ne "cp1252") {
        $name =~ s/[\x80-\x9F]//g;
    }
    my $bannedChars = $fsProps[$FS_BANCHARS];
    if ($bannedChars ne "" && $bannedChars != 0) {
        $name =~ s/$bannedChars/$sub/g;
    }
    my $maxFilename = $fsProps[$FS_MAXNAME];
    my $maxExtension = int(($maxFilename - int($maxFilename)) * 10);
    my $dotIndex = rindex($name, ".");
    my $extension = ($dotIndex > 1 && $dotIndex+1<len($name)) ?
      substr($name, $dotIndex) : "";
    if ($extension ne "" && $maxExtension > 0 && len($extension) > $maxExtension) {
        $extension = substr($extension, 0, $maxExtension);
        $name = substr($name, 0, $dotIndex) . $extension;
    }
    if ($maxFilename > 0 && len($name) > $maxFilename+$maxExtension) {
        $name = substr($name, 0, $maxFilename+$maxExtension);
    }
    my $maxPath = $fsProps[$FS_MAXPATH];
    if ($maxPath > 0 && len($path > $maxPath)) {
        eMSg(0, "ERROR: path length > $maxPath for '$path'\n");
    }
    ($name ne $orig) &&
        vMsg(1, "Name fixed for filesytem:\n    <$orig\n    >$name\n");
    return $name;
}


###############################################################################
# Append serial numbers, possibly padded, until we find an unused one.
# Maybe should also allow adding ancestor directories, or Mac image-file
# metadata.
#
sub findFreeFilename {
    my ($path, $name, $ext) = @_;
    if ($ancestor) {
        (my $anc1 = $path) =~ s/^.*\///;
        $name = $anc1 . $separator . $name;
    }
    for my $ser (0..(10**$padWidth)) {
        my $serPadded = sjdUtils::lpad($ser,-$padWidth);
        my $testFN = $path . $name . $separator . $serPadded . ($ext ? ".$ext" : "");
        vMsg(1, "    Checking target '$testFN'");
        if (!-e $testFN) { return($testFN); }
    }
    return(undef);
}


###############################################################################
# Do an actual rename (or not, if testing).
# *** Names passed here must include extension if any ***
#
sub doRename {
    my ($fp1, $fp2) = @_;
    if ($fp2 =~ m/_0\.$/) {
       die "Fail! '$fp1' -> '$fp2'.\n"  # Some gory bug...
    }
    if ($dryRun || $verbose) {
        vMsg(0, "  from: '$fp1'\n" .
                "    to: '$fp2'");
    }
    if (-e $fp2) {
        eMsg(0, "  *** Rename skipped, target exists: '$fp1'\n  to: '$fp2':\n    $!");
        $failCount++;
        return;
    }

    # TODO Should we check and warn even if they don't ask?
    my $useGit = 0;
    if ($gitMoves) {
        #my $gitStatus = system("versionStatus.py --nosystem '$fp1'");
        system("git ls-files --error-unmatch '$fp1' 2>&1 >/dev/null");
        my $rc = $? >> 8;
        if ($rc == 0) {
            $useGit = 1;
            if ($verbose || $dryRun) { vMsg(0, "git mv for '$fp1'\n"); }
            $gitCount++;
        }
    }
    if ($dryRun) { return; }

    if ($useGit) {
        system("git mv '$fp1' '$fp2'");
    }
    else {
        my $rc = rename($fp1, $fp2);
        if (!$rc) {
            ($quiet) || eMsg(0, "  *** Rename failed: '$fp1'\n  to: '$fp2':\n    $!");
            $failCount++;
        }
    }

    return;
}


###############################################################################
#
sub report {
    warn("\nTotals:\n");
    ($dryRun) && warn("(testing only, no files renamed)\n");
    my $fmt = "    %-20s %6d\n";
    warn sprintf($fmt, "Files",             $fileCount);
    warn sprintf($fmt, "Directories",       $dirCount);
    ($weirdCount) && warn
         sprintf($fmt, "Not file or dir",   $weirdCount);
    warn sprintf($fmt, "Rename attempts",   $simpleCount+$resolveCount);
    warn sprintf($fmt, sjdUtils::colorize("green/bold", "Simple renames")
        . "      ", $simpleCount);  # Allow for the color escapes
    ($gitCount) && warn
         sprintf($fmt, "git mv(s)",         $gitCount);
    ($extFixes) && warn
         sprintf($fmt, "Extensions fixed",  $extFixes);
    ($notFoundCount) && warn
         sprintf($fmt, "Not found",         $notFoundCount);
    ($unchanged) && warn
         sprintf($fmt, "No net change",     $unchanged);

    if ($conflictCount) {
        warn sprintf($fmt, "Name conflicts",    $conflictCount);
        warn sprintf($fmt, "  Case-only",       $caseIssueCount);
        warn sprintf($fmt, "  Forced",          $forceCount);
        warn sprintf($fmt, "  Resolved",        $resolveCount);
        warn sprintf($fmt, "  Failed",          $failCount);
    }
}


###############################################################################
# Deal with OS-specific conventions for naming copies
# Cf PowerWalk.py::isBackupFile().
#
sub doOsStuff {
    my ($name) = @_;
    my $n = "";
    if ($name =~ s/^Copy( \d+)? of //i) {         # Mac OS: Copy 2 of foo
        $n = $1;
    }
    elsif ($name =~                               # Ubuntu: foo (copy)
           s/ \((another |(\d+)(st|nd|rd|th) )?copy\)$//i) {
        $n = $1 || "1";
    }
    elsif ($name =~                               # Win 7: foo - Copy
           s/ - Copy$//i) {
        $n = $1 || "1";
    }
    elsif ($name =~ m/\bcopy\b/i) {
        eMsg(0, "Unrecognized pattern for filename containing 'copy': '$name'");
        return($name);
    }
    my $nPadded = sjdUtils::lpad($n, $padWidth);
    $name = insertBeforeExtension($name, $nPadded);
    return($name);
}

# TODO: Would be nicer to integrate strftime generality....
#
sub fixDates {
    my ($name, $toEnd) = @_;
    vMsg(1, "FixDate for: '$name'.");

    my $date = "";
    if (!$uk && $name =~ s/$date1expr//) {             # 02/28/1776
        vMsg(2, "    Date matched ($date1expr): $1, $2, $3");
        $date = formatYMD($3, $1, $2);
    }
    elsif ($uk && $name =~ s/$dateUKexpr//) {          # 28/02/1776
        vMsg(2, "    Date matched ($dateUKexpr): $1, $2, $3");
        $date = formatYMD($3, $2, $1);
    }
 elsif ($name =~ s/$date2expr//) {                     # Feb. 28, 1776
        vMsg(2, "    Date matched ($date2expr): $1, $2, $3");
        $date = formatYMD($3, $monthDict{$1}, $2 || "01");
    }
    elsif ($name =~ s/$date3expr//) {                  # 28 Feb 92
        vMsg(2, "    Date matched ($date3expr), year '$3'");
        my $yr = (int($3) < 100) ? "20$3" : $3;  # shouldn't happen currently
        $date = formatYMD($yr, $monthDict{$2}, $1);
    }
    elsif ($name =~ s/$date4expr//) {                  # 1776-02-28
        vMsg(2, "    Date matched ($date4expr)");
        $date = formatYMD($1, $2, (defined $3 && $3>0) ? $3 : 1);
    }
    elsif ($name =~ s/$date5expr//) {                  # 20150328
        vMsg(2, "    Date matched ($date5expr)");
        $date = formatYMD($1, $2, $3);
    }
    else {
        vMsg(1, "    ******* Date did not match any regex ******* ");
    }

    if ($date) {
        vMsg(1, "    Date reconstructed is: $date.");
        if ($toEnd) { $name = insertBeforeExtension($name, $date); }
        else { $name = "$date $name"; }
        $name =~ s/\s+$//;
    }
    return($name);
}

sub formatYMD {
    my ($y, $m, $d) = @_;
    vMsg(1, "y $y, m $m, d $d.\n");
    return itemftime($dateOutput, 0, 0, 0, $d, $m, $y);
}

sub itemftime {
    # Like strftime() but takes 1-based days and years. E.g.:
    #     itemftime("%m/%d/%Y",   0,  0,  0, 31, 12, 2024)
    # TODO: Add support for month names and abbrevs?
    #
    my ($format, $sec, $min, $hr, $mday, $mon, $year, $wday, $yday, $isdst) = @_;

    # Imperfect test -- like for '%%%'.
    # (list based on man strftime on MacOS)
    # Also doesn't know Gnu %-* %_* %0* extensions or POSIX %E* %O*.
    my $extensionFlags = "CDegGhklnrRstTuVz+";
    my $badFlagExpr = "%[^aAbBcdFHIjmMpSUvwWxXyYZ%+$extensionFlags]";
    ($format =~ m/%\w/) || die "Bad format arg '$format'.\n";
    ($format =~ m/($badFlagExpr)/) && die "Bad %-sequence '$1'.\n";

    ($sec>=0 && $sec<=59) || die "Bad second arg '$sec'.\n";
    ($min>=0 && $min<=59) || die "Bad minute arg '$min'.\n";
    ($hr>=0 && $hr<=59) || die "Bad hour arg '$hr'.\n";
    ($mday>=0 && $mday<=31) || die "Bad mday arg '$mday'.\n";
    ($mon>=0 && $mon<=12) || die "Bad month arg '$mon'.\n";
    ($year>=1582) || die "Bad year arg '$year' (min 1582).\n";
    if (defined $wday && $wday!=-1) { die "Bad wday arg '$wday'.\n"; }
    if (defined $yday && $yday!=-1) { die "Bad yday arg '$yday'.\n"; }
    if (defined $isdst && $isdst!=-1) { die "Bad dst arg '$isdst'.\n"; }

    my $buf = strftime($format, $sec, $min, $hr, $mday, $mon-1, $year-1900);
    return $buf;
}

sub testDates {
    print "\nTesting various date formats...\n";
    my @data = (
        "02/28/1776",                   # expr 1
        "2/1/1776",                     # expr 1
        "Feb. 28, 1776",                # expr 2
        "Feb.  \t\r\n\xA0 28, 1776",    # expr 2
        "Feb. 28 1776",                 # expr 2
        "Feb 28, 1776",                 # expr 2
        "February 28, 1776",            # expr 2
        "Feb 1776",                     # expr 2
        "28 Feb 1776",                  # expr 3
        "1776-02-28",                   # expr 4
        "1999-12",                      # expr 4
        "17760228",                     # expr 5

        # Fails
        # "1492-01-12", "31/31/1999", "28 Zork 1998", "1999", "Sept.99.9999"
    );
    sjdUtils::setVerbose($verbose+1);
    for my $k (@data) {
        my $src = "fileName for $k.txt";
        print "\nTrying '$src'\n";
        my $tgt = fixDates($src, 0);
        printf("    => '%s'\n", $tgt);
    }
    sjdUtils::setVerbose($verbose-1);
}

sub insertBeforeExtension {
    my ($name, $n) = @_;
    if ($name =~  m/\.[^.]{1,4}$/) {
        $name =~ s/(\.[^.]{1,4})$/$separator$n$1/;
    }
    else {
        $name .= "$separator$n";
    }
    return($name);
}


###############################################################################
# Make a hash that maps extensions to their preferred form (unused).
#     docx docm dotm dotx potm potx ppsm ppsx pptm pptx sldm sldx
#     xlsb xlsm xlsx xltm xltx
#     emlx mbox mail epub icns
#     sfil webp itdb plist gzip yaml
#     prop (github stuff)
#     make scad java data sexp perl
#
sub makeExtensionMap {
    %extensionMap = ( # All lower case!
        # Image
        "aiff"   => "aif",
        "jpeg"   => "jpg",
        "moov"   => "mov",
        "mpeg"   => "mpg",
        "pict"   => "pct",
        "tiff"   => "tif",
        # Audio
        "wave"   => "wav",
        # Markup
        "gml"    => "sgm",
        "html"   => "htm",
        "sgml"   => "sgm",
        "xhtm"   => "xht",
        "xhtml"  => "xht",
        "xslt"   => "xsl",
        # Other
        "mime"   => "mim",
        "text"   => "txt",
        "json"   => "jsn",
        );
}

# List of what *nix 'file' command says, and extension to apply.
# Apply in order, due to cases like:
#     timeDiff:           Python script text executable, ASCII text
# 'file' doesn't seem to distinguish sql, java, properties, etc.
#
@fileToExt = (
    # DOCUMENTS
    [ "HTML document"                 , "htm"  ],
    [ "XML document text"             , "xml"  ],

    # IMAGES
    [ "JPEG image data"               , "jpg"  ],
    [ "GIF image data"                , "gif"  ],
    [ "OpenDocument Drawing"          , "odg"  ],
    [ "PNG image data"                , "png"  ],

    # Document images
    [ "PDF document"                  , "pdf"  ],
    [ "Postscript document"           , "ps"   ],

    # SCRIPTS/PROGRAMS
    [ "Bourne-Again shell script"     , "sh"   ],
    [ "C source"                      , "c"    ],
    [ "Perl script"                   , "pl"   ],  # Includes .pm
    [ "Python script"                 , "py"   ],
    [ "python \\d\\.\\d byte-compiled", "pyc"  ],

    [ "directory"                     , ""     ],

    # TEXT
    [ "ASCII text"                    , "txt"  ],
    [ "ISO-8859 text"                 , "wtxt" ],
    [ "UTF-8 Unicode text"            , "utxt" ],
);

%suffixes = (
    [ "with very long lines"          , ""     ],
);