Rename Files

This statement will rename the selected files based on a chosen rename template. The rename template can be chosen from the popup list or manually entered. The only reason to manually enter the template name is if you wish to specify the name at runtime. The template field may contain any of the escape sequences described in Escape Sequences. Note that regardless of the execution mode, the template field is only evaluated once. As this is the case it may be more appropriate to indirectly specify a template in a named variable as opposed to a track variable.

The function sets the Retained Path 1 property to the new path on success. The Retained Path 2 property is set to the original path on success. On failure, both properties are emptied.

Largely for historic reasons, an error message is displayed if a rename fails. You can disable the display of error messages by setting the silent option. Note that silent is always treated as enabled when batch processing. Regardless of this setting, action processing is always terminated if a required template does not exist.

When a file is renamed, if the file is linked to an Apple App, the file's location in the Apple App will be updated.

Runtime Previews

If a track variable is chosen for runtime preview, no renaming or modification of the Retained Path # properties takes place. The template is applied for each selected file and the resultant path is saved to the specified track variable. This is useful if for any reason you want to see the effects of a rename prior to actually renaming. In the case of an error, the track variable's contents will not begin with a / character and may contain text describing the error.

Note that IfDup sequences are not processed.

The following example shows how to do a preview and verify that the path components are identical for all files:

Rename Files (my rename template), preview to Variable 1
Test if the Variable 1 field does not start with "/" (Set test state and Variable 2)
if Variable 2 is true
    ' These files had errors
else
    Remove the last path component in Variable 1
    Test if Variable 1 is the same in every file, Set result
    if true
        ' These files have a consistent path
    else
        ' These files do not have a consistent path
    endif
endif

Overriding Settings in the Supplied Rename Template

If you want to override the settings specified in a rename template, you can specify an alternate rename template to be used for the settings. The name of the alternate rename template is placed in the Rename Template Settings Override named variable.

All settings are taken from the specified rename template while only the list of rename tokens are taken from the template specified directly to the statement. It is a good idea to clear the named variable immediately after the rename is performed.

If an alternate template is specified and it does not exist, action processing will be terminated.