Function Repository Resource:

FileNameEdit

Source Notebook

A convenience function for renaming files

Contributed by: Michael Sollami

ResourceFunction["FileNameEdit"][file]

edits the base name of a file and optionally copies or moves it on disk.

Details and Options

The file should be a String path or File object
ResourceFunction["FileNameEdit"] returns the edited filename as a String
The file should exist as a valid path if the option "Action" is set to "Copy" (as is done by CopyFile) or "Move" (as done by RenameFile)
ResourceFunction["FileNameEdit"] takes the following options:
"AddMissingExtension"Falsewhether to add the proper extension if it is missing
"Append"""a string which is appended to FileBaseName[file]
"Edit"Nonea string valued function which is applied to FileBaseName[file]
"Lowercase"Falsewhether to force entire filenames to be lowercase
"LowercaseExtension"Falsewhether to force extensions to be lowercase
"NewDirectory"Noneabsolute directory (as a string) of the new filename
OverwriteTargetFalsespecifies whether to overwrite an existing target file
"Action"Falsewhether to perform a file system operation, either
"Copy" (non-destructive) or "Move" (destructive)
"Prepend"""a string which is prepended to FileBaseName[file]
ResourceFunction["FileNameEdit"] applies "Edit" before both "Append" and "Prepend" and converts the results of these options into strings automatically
The option "NewDirectory" will attempt to create a given directory if it doesn't exist and setting "NewDirectory" "Temp" will use $TemporaryDirectory
ResourceFunction["FileNameEdit"] uses CopyFile and DeleteFile to perform requested file operations

Examples

Basic Examples (6) 

Easily alter the FileBaseName of a file:

In[1]:=
ResourceFunction["FileNameEdit"]["img.jpg", "Append" -> " (1)"]
Out[1]=

Simultaneously append and prepend:

In[2]:=
ResourceFunction["FileNameEdit"][File@"/a/b/c/IMG.PNG", "Append" -> "-456", "Prepend" -> "123-"]
Out[2]=

Apply arbitrary functions to base names of files:

In[3]:=
ResourceFunction["FileNameEdit"]["ABCDEFGHI.JPEG", "Edit" -> StringLength]
Out[3]=

Use a custom function and then lowercase all characters:

In[4]:=
ResourceFunction["FileNameEdit"]["ABCDEFGHI.JPEG", "Edit" -> (StringJoin[Reverse@Characters[#]] &), "Lowercase" -> True]
Out[4]=

Use the "NewDirectory" option to copy or move files to a different directory:

In[5]:=
f1 = $InstallationDirectory <> "/Documentation/English/System/ExampleData/50states.txt";
f2 = ResourceFunction["FileNameEdit"][f1, "NewDirectory" -> "~/Downloads", "Action" -> "Copy"]
Out[6]=

which equivalent to this:

In[7]:=
DeleteFile[f2];
f2 = FileNameJoin[{"~/Downloads", "ocelot.jpg"}];
CopyFile[f1, f2]
Out[9]=

Files are not actually edited (copied or moved/renamed) on disk unless the option "Action" is specified:

In[10]:=
old = "older_image.jpg"; img = RandomImage[10]; Export[old, img];
f = StringReplace[#, "older" -> "newer"] &;
new = ResourceFunction["FileNameEdit"][old, "Edit" -> f];
In[11]:=
FileExistsQ /@ {old, new}
Out[11]=

To non-destructively copy a file to one with new name, set the option "Action" to "Copy":

In[12]:=
new = ResourceFunction["FileNameEdit"][old, "Edit" -> f, "Action" -> "Copy"];
FileExistsQ /@ {old, new}
Out[12]=

Setting the option "Action" to "Move" changes the file in-place:

In[13]:=
new = ResourceFunction["FileNameEdit"][old, "Edit" -> (# <> "-1" &), "Action" -> "Move"];
In[14]:=
FileExistsQ /@ {old, new}
Out[14]=

Options (3) 

The option "AddMissingExtension" uses FileFormat to add an appropriate extension:

In[15]:=
Print[f = Export["test", RandomImage[100], "JPEG"]];
ResourceFunction["FileNameEdit"][f, "AddMissingExtension" -> True]
Out[16]=

If a file with the new name already exists it will fail unless you set OverwriteTarget True:

In[17]:=
old = "~/image.jpg"; Export[old, RandomImage[10]];
CopyFile["~/image.jpg", "~/image-new-name-exists.jpg"];
new = ResourceFunction["FileNameEdit"][old, "Edit" -> (# <> "-new-name-exists" &), "Action" -> "Move"]
Out[17]=
In[18]:=
new = ResourceFunction["FileNameEdit"][old, "Edit" -> (# <> "-new-name-exists" &), "Action" -> "Move", OverwriteTarget -> True];
FileExistsQ /@ {old, new}
Out[18]=

Use "LowercaseExtension" or "Lowercase" to lower-case the extension or entire filename, respectively:

In[19]:=
f = Export["TestNumber1.JPEG", RandomImage[100]]
Out[19]=
In[20]:=
ResourceFunction["FileNameEdit"][f, "LowercaseExtension" -> True]
Out[20]=
In[21]:=
ResourceFunction["FileNameEdit"][f, "Lowercase" -> True]
Out[21]=

Possible Issues (1) 

Be careful when renaming files with option "Action""Move". In this case, FileNameEdit performs a CopyFile and DeleteFile in sequence:

In[22]:=
f = $InstallationDirectory <> "/Documentation/English/System/ExampleData/ocelot.jpg";
new = ResourceFunction["FileNameEdit"][f, "Action" -> "Copy", "NewDirectory" -> "Temp"];
ResourceFunction["FileNameEdit"][new, "Edit" -> Identity, "Action" -> "Move", OverwriteTarget -> True]
Out[22]=
In[23]:=
FileExistsQ[new]
Out[23]=

Publisher

Michael Sollami

Version History

  • 1.0.0 – 06 January 2021

Related Resources

License Information