C-Kermit's RENAME Command

As of: C-Kermit 8.0.212 Dev.18, Wed Apr 26 12:02:35 2006

---

C-Kermit's RENAME command, which is used for changing the names of files or for moving files, has two basic forms:

RENAME [ optional-switches ] oldfilename newfilename

This form lets you change the name of a single file from oldfilename to newfilename. Example:
rename thismonth.log lastmonth.log

RENAME [ optional-switches ] filespec directoryname

This form lets you move (without renaming) one or more files (all the files that match the filespec, which may contain wildcard characters such as "*") to the given directory. Example:
rename *.txt ~/textfiles/

Traditionally, the optional switches have been:

RENAME /LIST oldname newname

Display the old and new name for each file while renaming. Synonyms: /LOG, /VERBOSE. Example:
rename /list *.txt ~/textfiles/

RENAME /NOLIST oldname newname

Don't display the old and new name for each file while renaming. This is the default behavior. Synonyms: /NOLOG, /QUIET. Example:
rename /nolist *.txt ~/textfiles/

Reminder: Every switch starts with a slash (/) and must be preceded by a space.

New RENAME Features for C-Kermit 8.0.212

/LOWER:	Convert the filename to lowercase
/UPPER:	Convert the filename to uppercase
/CONVERT:	Change the filename's character encoding
/REPLACE:	Do string substitutions on the filename

Since these actions, when applied to many files at once, can have consequences that are not easily undone, there are also some new controls, safeguards, and conveniences:

RENAME /SIMULATE

This switch tells Kermit to show you what the RENAME command would do without actually doing it. /SIMULATE implies /LIST.

RENAME /COLLISION:{FAIL,PROCEED,OVERWRITE}

This switch governs Kermit's behavior when renaming multiple files, and any of the names would collide with the name of a file that already exists. The default, for compatibility with earlier releases of C-Kermit, is OVERWRITE, i.e. write over the existing file. The other two protect existing files. PROCEED means to skip (not rename) the file that would cause the collision, and proceed to the next file, if any. FAIL means that no files will be renamed if there would be any collisions; for this Kermit makes two passes, checking each new name it constructs for existence before starting the second pass (however, there is no guarantee that in the second pass, it won't create the same new name for more than one file; in that case, it will stop before executing the second rename). Example:
rename /simulate /collision:proceed * ~/tmp/

Reminder: In switches such as /COLLISION that take arguments (operands), the switch name and its argument(s) are separated by a colon (:) with no intevening spaces. Also remember that Kermit keywords can always be abbreviated by leaving off characters from the right, as long as the result is still unique in its context. Thus "ren /col:f" would be equivalent to "rename /collision:fail".

You can change the following preferences for the RENAME command with the new SET RENAME command:

SET RENAME LIST { ON, OFF }

Tells the RENAME command whether to list its actions if you don't include a /LIST or /NOLIST or equivalent switch.

SET RENAME COLLISION { FAIL, OVERWRITE, PROCEED }

Tells the RENAME command how to handle filename collisions in the absence of a /COLLISION switch. That is, it replaces the default action of OVERWRITE with action of hour choosing, which is then used in any RENAME command that does not include an explicit /COLLISION switch.

And you can use SHOW RENAME to display these settings.

*** Add text to HELP RENAME and HELP SET RENAME ***

Changing the Case of Filenames

RENAME /UPPER:{ALL,LOWER} filespec [ directory ]
RENAME /LOWER:{ALL,UPPER} filespec [ directory ]

These switches let you change the alphabetic case of letters in all the files whose names match the filespec. If a directory name is given after the filespec, then the files are also moved to the given directory.

By default, all files that match the given filespec have their names changed (if necessary). This is what the ALL argument means, e.g.:

RENAME /LOWER:ALL *
RENAME /LOWER *

You can use either form: RENAME /LOWER is equivalent to RENAME /LOWER:ALL. The other argument (/LOWER:UPPER or /UPPER:LOWER) means to leave mixed-case filenames alone, and rename only those files whose names contain letters of only the given case. Examples:

RENAME /UPPER:ALL foo.bar

Changes the filename to FOO.BAR.

RENAME /UPPER foo.bar

Same as "rename /upper:all foo.bar".

RENAME /UPPER foo.bar ~/old/

Renames foo.bar to FOO.BAR and moves it to the user's old directory (Unix).

RENAME /LOWER *

Changes the names of all files to have only lowercase letters.

RENAME /LOWER:UPPER *

Changes the names of only those files whose names contain no lowercase letters to have only lowercase letters. For example, FOO.BAR would be changed, Foo.Bar would not be changed. foo.bar would not be changed either because it's already all lowercase.

RENAME /LOWER:UPPER * ~/new/

Same as the previous example, but also moves each file to the user's new directory (whether it was renamed or not).

Case conversion works reliably for ASCII characters only. Kermit uses the C library for this, which on any given platform might or might not handle non-ASCII letters, and if it does, then how it works would normally depend on your locale definitions (the LC_CTYPE and/or LANG environment variable in Unix). When non-ASCII letters are not handled by the C library, the RENAME command does change their case. For example, Olga_Tañón.txt might become OLGA_TAñóN.TXT.

String Replacement in Filenames

RENAME /REPLACE:{{String1}{String2}} filespec [ directory ]

Renames each matching file by changing occurrences of String1 in its name to String2. If a directory specification is included, the file is also moved to the given directory (even if the name was not changed). Note that in this case, the curly braces are part of the command. Example:

RENAME /REPLACE:{{.jpeg}{.jpg}} *

changes all *.jpeg files to *.jpg.

For greater control and flexibility, the /REPLACE: switch argument can take several distinct forms:

RENAME /REPLACE:String1 filespec

This means to remove all occurrences of String1 from the given filenames name. It is equivalent to /REPLACE:{{String1}{}}. A handy use for this option is to remove spaces from filenames, or to replace them with underscores, as in this example:

RENAME /REPLACE:{{ }{_}} *

RENAME /REPLACE:{{String1}{String2}} filespec

As already noted, this replaces every occurrence of String1 with String2 in each filename. Alphabetic case in string matching is done according to the current SET CASE setting.

RENAME /REPLACE:{{String1}{String2}{Options}} filespec

Options can be included that add more control to the process. The option string is a sequence of characters; each character in the string is an option. The choices are:

A String matching is to be case-sensitive, regardless of SET CASE. a String matching is to be case-independent, regardless of SET CASE. ^ String replacement will occur only at the beginning of the filename. $ String replacement will occur only at the end of the filename. 1 Only the first occurrence of the string will be replaced. 2 Only the second occurrence of the string will be replaced. ... 9 Only the ninth occurrence of the string will be replaced. 0 Only the final occurrence of the string will be replaced (same as -1). - (hyphen, minus sign) Before a digit: occurrences will be counted from the right.

Here are some examples showing how to use the /REPLACE options:

RENAME /REPLACE:{{foo}{bar}{^}} *

For all files whose names start with "foo", replaces the initial or only "foo" with "bar".

RENAME /REPLACE:{{}{New-}{^}} *

Prepends "New-" to the name of each file.

RENAME /REPLACE:{{.jpeg}{.jpg}{$}} *

Replaces ".jpeg" at the end of the filename with ".jpg".

RENAME /REPLACE:{{}{Old-}{$}} *

Appends "-Old" to the name of each file.

RENAME /REPLACE:{{foo}{bar}{A}} *

Replaces "foo", "FOO", "Foo", "fOO", etc, with "bar" in each filename.

RENAME /REPLACE:{{foo}{bar}{a}} *

Replaces only (lowercase) "foo" with "bar".

RENAME /REPLACE:{{a}{XX}} *

Changes every "a" to "XX". For example a file called "a.a.a.a" would become "XX.XX.XX.XX".

RENAME /REPLACE:{{a}{X}{2}}

Changes only the second "a" to "X". For example a file called "a.a.a.a" would become "a.X.a.a".

RENAME /REPLACE:{{a}{X}{-1}}

Changes only the final "a" in the filename (it doesn't have to be at the end) to "X". For example a file called "a.b.a.c.a.d" would become "a.b.a.c.X.d".

RENAME /REPLACE:{{foo}{NOTFOO}{-2}}

Changes the second-to-last "foo" (if any) in the filename to "NOTFOO".

RENAME /REPLACE:{{foo}{}{-2}}

Deletes the second-to-last "foo" (if any) from the filename.

Digits, ^, and $ are mutually contradictory. If you include more than one of these in the option string, only the last one is used. Similarly for 'a' and 'A':

RENAME /REPLACE:{{foo}{bar}{aA2$^}} *

This replaces "foo" with "bar" no matter what combination of upper and lower case letters are used in "foo" ('A' overrides 'a' in the option string), but only if "foo" is at the beginning of the filename ('^' overrides '$' and '2').

If you give an /UPPER or /LOWER switch and a /REPLACE switch in the same RENAME command, the /REPLACE action occurs first, then the case conversion:

RENAME /REPLACE:{{foo}{bar}} /UPPER * /tmp

For each file: changes all occurrences of "foo" in the name to "bar", then converts the result to uppercase, and then moves the file to the /tmp directory.

Changing the Character Encoding of Filenames

RENAME /CONVERT:charset1:charset2 filespec [ directory ]

Converts filenames from the first character set to the second one. The two character sets can be chosen from the SET FILE CHARACTER-SET list. For example suppose you have a file called "Olga_Tañón.txt" on a computer where ISO 8859-1 Latin Alphabet 1 is used, and you have transported it (e.g. on CDROM) to another computer where the text encoding is UTF8. Maybe you also have a lot of other files with similar names in the same directory. You can convert the filenames to UTF8 like this:

RENAME /CONVERT:latin1:utf8 *

/CONVERT can not be combined with /UPPER, /LOWER, or /REPLACE.

You should NOT use UCS2 for filenames since this encoding is not compatible with C strings used in Unix and elsewhere.

RENAME /CONVERT affects only the filename, not the file's contents. You can use the TRANSLATE command to convert the encoding of the contents of a text file.