|
|
|
chafn renames files using regular-expression-based pattern substitutions applied to the file names. It is a command-line tool that I've built and used on Linux and Windows and Android and my Nintendo DS and ...
Invoking chafn without any arguments gives a brief list of the program's command-line options. Invoking it with the "-help" option results in more detailed usage information, including the syntax for regular expressions and substitution text. (The "-help" information is written to standard output, so it can be redirected to a file for future reference if desired.)
Command-line arguments are scanned left-to-right in one pass. When a non-option file name is encountered, the previously specified change options are applied to the file name. Consequently, you must specify options before the file names to which they apply.
When in doubt, verify the changes without making them using the "-test" ("-t") command-line option ... before the file names!
-test
-debug
If either of these options is present, chafn runs through the motions of renaming files, but does not actually rename them. This is useful for checking what files will be changed and how by your command line before running the program to actually change the file names.
Warning: the "-test" or "-debug" option must be specified before any file names. While scanning the command-line arguments, chafn renames files as it encounters them, so test/debug mode must be enabled before chafn gets to the files.
RIGHT:% chafn -test ...WRONG:% chafn ... -test
-glob
If this option is specified—again, like "-test", before any file names—chafn will treat each file name on the command line as a possibly wildcard file specification. A directory scan for matching file names is performed internally and matched files are renamed. If "-glob" is not specified, chafn treats each file name as the name of a single file.
This option is generally useful for command shells that do not perform globbing before invoking chafn. Assume a directory contains, among other files:
"09 - Dig A Pony [Rooftop Concert].mp3"
In a command shell without globbing,
WRONG: % chafn ... *.mp3
will only match a file whose name is literally "*.mp3".
RIGHT: % chafn -glob ... *.mp3
will match all the MP3 files, including the example above.
UNIX-like shells that perform globbing pass the matched file names as individual command-line arguments to the program. In this case, it's probably a good idea to not "-glob".
RIGHT: %chafn ... *.mp3
will pass the names of all the MP3 files to chafn, including "09 - Dig A Pony [Rooftop Concert].mp3", which chafn will correctly consider the literal name of a single file. However:
WRONG: %chafn -glob ... *.mp3
will miss the "Dig A Pony" file because the shell passes "09 - Dig A Pony [Rooftop Concert].mp3" to chafn and chafn's internal globbing will treat the "regular expression" square brackets in the file name as part of a wildcard file specification. The following is not necessary, but:
RIGHT: %chafn -glob ... '*.mp3'
will work, with chafn's internal globbing expanding '*.mp3'. (And this is what I had to do before I added the "-glob" option!)
chafn's default mode of operation is to perform a regular-expression match and replace on each file name. Therefore, the first two non-option arguments are the RE pattern and replacement strings. Subsequent non-option arguments are the file names to be changed. By default, only a single match/replace is performed on a file name; the number can be increased with the "-all" or "-max" options:
% chafn [-all] [-max substitutions]
pattern replacement
file(s)
Reminder: the "-test" option, specified before the files, is your friend if you don't know what you're doing!
The syntax for regular expressions and substitution strings is as used in the rex_util package and can also be viewed with the chafn -help command.
Note that backslash marks ("\") in REs may need to be doubled up depending on shell quoting conventions. For example, "\d" in an RE matches a decimal digit and must be entered in Unix shells as "\\d".
The RE match/replace is applied to the entire file name as a string,
including the extension and version number; e.g., "file.ext.123".
Do NOT combine the regular expression mode of operation with the other file name modification options below.
In contrast to the RE match/replace mode of operation, the other file name modification options treat ALL non-option arguments as file names to be changed. If chafn detects that a regular expression has already been defined when encountering one of these options, it will signal an error. (Some of the other options utilize internal RE patterns/replacements and the presence of more than one of these options will also result in an error.)
Capitalization is fairly simple and easily fooled by adjacent non-alphabetic characters, so double-check the changes after they're made.
% chafn [-capitalize] [-lower] [-upper]
file(s)
The translation string is a sequence of paired characters in which the first in a pair is the character to be translated and the second is the replacement character. For example, "-xlat abcdef" will convert every 'a' to 'b', every 'c' to 'd', and every 'e' to 'f'.
% chafn -xlat translation
file(s)
A shortcut for "-xlat '[(]){(})'":
% chafn -brackets
file(s)
For converting characters such as smart/curly single and double quotes to their straight ASCII equivalents.
% chafn -smart
file(s)
% chafn [-prefix text] [-suffix text]
file(s)
VAX/VMS files had/have version numbers appended to a file name after a
semicolon, e.g., "info.txt;1", "info.txt;2",
etc. The oldest version is version 1 and succeeding versions are
increasingly more recent. A version-less file name, e.g.,
"info.txt", refers to the most recent version.
Inspired by VAX/VMS, I long ago implemented a similar scheme
under Unix (and Cygwin on Windows) in which the latest version
of a file has no version number and earlier versions have 3-digit
versions beginning with 001; e.g., "info.txt.001",
"info.txt.002", ..., "info.txt".
The shell script I use to invoke my text editor automatically
makes a backup version of the file.
chafn can append or replace a file's version number on both VMS and non-VMS systems. The version track number is incremented after each file name to which it is applied; the default increment is 1.
% chafn [-increment n] -version number
file(s)
I frequently work with MP3 files and I have a personal preference for audio file names in one of the following styles:
"track - title.mp3"
"track - title - artist.mp3"
Audio files obtained from other people generally follow similar but not always identical conventions, so chafn has some name modification options to convert these to my obviously correct convention.
File names that have only a space between the track and song title
(e.g., "12 Get Back.mp3") are converted to my convention
with the -yphen option
(e.g., "12 - Get Back.mp3").
File names that have a tight hyphen between the track and song title
(e.g., "12-Get Back.mp3") are converted to my convention
with the -Yphen option
(e.g., "12 - Get Back.mp3").
File names with ". " between the track and song title (e.g.,
"12. Get Back.mp3") are converted to my convention with the
-dot option (e.g.,
"12 - Get Back.mp3").
If I have file names of the form,
"track - artist - title.mp3",
I usually swap the artist and title with a
-swap .mp3 option.
I don't use this option much anymore since, if the audio files have
ID3 tags, tag311 can rename the files
using the information in the tags.
chafn can prepend a track number (e.g., "12 - ") to an audio file name. The minimum field width is 2, so track numbers 1-9 have a leading zero; for example, "-track 7" produces "07 - " in the file name. The track number is incremented after each file name to which it is applied; the default increment is 1.
% chafn [-increment n] -track number
file(s)
If the file name already has a track number, you will get two track
numbers, e.g., "34 - 12 - Hello, Goodbye.mp3". The
earlier track number, " - 12", can be deleted with an RE match/replace:
% chafn ' - \\d\\d' "" file(s)
% chafn [-debug] [-test] [-help]
[-change] [-full] [-glob]
[-all] [-max substitutions]
[-brackets] [-xlat translation]
[-dot] [-hyphens] [-smart] [-spaces] [-underscores]
[-capitalize] [-lower] [-upper]
[-prefix text] [-suffix text]
[-swap extension] [-yphen] [-Yphen]
[-increment number] [-track number] [-version number]
[pattern replacement]
file(s)
where
-debug
-test- puts the program in debug/test mode. In either of these modes, the program does not rename the files. This is useful if you want to check beforehand that your invocation works the way you expect. In "-test" mode, the program generates the normal output. In "-debug" mode, the program generates additional debug messages.
-help- displays help information.
-change- begins the new specification of a file name change. This option allows you to specify a file name change for one set of files and then a different file name change for another set of files. The option is followed by a name change specification (e.g., pattern and replacement text or other options) and the files to which the name change is to be applied. (There is an implied "-change" at the beginning of the command line.)
-full- specifies if full path names should be printed. After each rename operation, the old and new file names are printed to the user's terminal. By default, only the file name, extension, and version are printed. With the "-full" option, the full path names of the old and new files are printed.
-glob- If this option is specified — again, like "-test", before any file names — chafn will treat each file name on the command line as a possibly wildcard file specification. A directory scan for matching file names is performed internally and matched files are renamed. If "-glob" is not specified, chafn treats each file name as the name of a single file.
- This option is intended for command shells that do not perform globbing before invoking a program, but I have have found it useful on rare occasions even in a UNIX shell. (Most recently, it was quicker and easier to let chafn match a problematic file name instead of painstakingly trying to get the shell to correctly package and pass the file name to chafn.)
-all-max substitutions- specify the maximum number of substitutions to perform. The default maximum is 1 for the usual pattern/replacement substitutions. The "-all" option causes global replacement. For case conversions, the default is to apply the conversion globally to the file name; this can be altered by specifying the "-max" option after the case-conversion option.
-brackets- converts square and curly brackets ("[]" and "{}") to parentheses. I occasionally work with MP3 files that have square brackets in their names and I like to convert them to parentheses. This translation is done before the regular expression, if any, is applied. (This option conflicts with the "-xlat" option, so chafn signals an error if both are used in the same command.)
-xlat translation- translates selected characters to other characters. The argument is a string of character pairs, the first character in a pair being a character to be translated and the second being the replacement character. For example, -xlat abcdef converts any 'a' in a file name to 'b', any 'c' to 'd', and any 'e' to 'f'. (This option conflicts with the "-brackets" option, so chafn signals an error if both are used in the same command.)
-dot- deletes dotted artist/album information from MP3 file names of the form, "track>. text - song.mp3". The ". text" part is removed, leaving "track - song.mp3".
-hyphens- replaces all hyphens ("-") in the file name with spaces.
-smart- converts "smart" UTF-8 code sequences and Microsoft characters into their normal ASCII equivalents. For example, left and right curly quotes are converted to straight ASCII quotes.
-spaces- replaces all spaces in the file name with hyphens ("-").
-underscores- replaces all underscores ("_") in a file name with spaces.
-capitalize-lower-upper- causes alphabetic characters in file names to be capitalized, converted to lower-case, or converted to upper-case, respectively. chafn uses the C Library's character types functions/macros (in <ctype.h>), so these conversions probably are limited to ASCII characters or a small superset of ASCII. (Capitalization employs a simple regular expression, so be sure to check the results for incorrect capitalization.)
-prefix text- inserts the text at the beginning of each file name. (This is just shorthand for the pattern, "^", and the replacement text, "text".)
-suffix text- appends the text to each file name. (This is just shorthand for the pattern, "$", and the replacement text, "text".)
-swap extension- swaps the second and third hyphen-separated fields in a file name. The file extension may or may not include the period (e.g., both ".mp3" and "mp3" are accepted). I frequently use this for music file names of the form:
"track - artist - title.mp3"
The result is:
"track - title - artist.mp3"-yphen- replaces the first space in a file name by " - " (space, 'yphen, space). For example, "01 Trams Of Old London.mp3" becomes "01 - Trams Of Old London.mp3".
-Yphen- replaces the first hyphen in a file name by " - " (space, hyphen, space). For example, "01-Toonerville Trolley.mp3" becomes "01 - Toonerville Trolley.mp3".
-increment number- is the increment added to track or version numbers when "-track" or "-version" are applied to multiple files. The default increment is 1.
-track number- inserts a track number, separated by a hyphen, at the beginning of each file name. A leading zero is added for numbers less than ten. Examples: "01 - ", "02 - ", ..., "10 - ", "11 - ", etc. When this option is applied to multiple files, the track number is incremented by 1 after each file (as in the example above). An increment other than 1 can be specified with the "-increment" option.
-version number- replaces the 3-digit version number at the end of a file name with a new version number. If the file name has no version number, the new version number is appended to the file name. If multiple file names are being processed, the version number is incremented after each file: ".023", ".024", ".025", etc. An increment other than the default, 1, can be specified with the "-increment" option. Under OpenVMS, version numbers are separated from the file name by a semi-colon instead of a period; e.g., ";023".
pattern- is a regular expression used to match the text to be replaced.
replacement- is the replacement text.
file(s)- specifies the file(s) to be renamed.