Main Content

Creating and Managing Class Aliases

Class aliasing allows you to rename classes while maintaining backward compatibility with code and MAT-files that use one or more older class names. In effect, MATLAB® recognizes more than one name for the same class. The matlab.alias.AliasFileManager provides an API for creating and maintaining alias definition files. The recommended process for creating and maintaining alias files is to use functions to automate the process. To share code that includes classes that have been renamed using aliasing, include one of the following:

  • The alias-creating function in the setup script of your application or toolbox

  • The alias definition file itself

The example Create Class Alias File shows a function that creates an alias file that defines the renaming of one class. You can also rename a class multiple times or rename multiple classes at once.

Rename a Class Multiple Times

The example Create Class Alias File shows how to create an alias definition file that renames FirstName to SecondName. To rename the class again to ThirdName, the ThirdName.m class file must be in Work, and the SecondName.m file must be removed. (MATLAB issues a warning when SecondName.m is no longer present.)

Work folder structure with class renamed twice, script, and alias file

To rename a class that already has one or more existing aliases, the addAlias method must take all the previous names as inputs, in order from newest to oldest. In this case, "ThirdName" is the new name and ["FirstName","SecondName"] is the list of old names. This version of createAliasFIle also includes the location argument in the AliasFileManager constructor because an alias file already exists.

function createAliasFile
    fileMgr = matlab.alias.AliasFileManager(pwd);
    addAlias(fileMgr,NewName="ThirdName",OldNames=["FirstName","SecondName");
    writeAliasFile(fileMgr);
end

Change the current working directory to the Work folder and call createAliasFile.

createAliasFile

Instantiating the class using the aliases and the current name shows that all three are recognized as ThirdName.

oldest = FirstName
older = SecondName
new = ThirdName
oldest = 

  ThirdName with no properties.


older = 

  ThirdName with no properties.


new = 

  ThirdName with no properties.

Rename Multiple Classes in a Single Function

You can also rename multiple classes using a single AliasFileManager instance. This modified createAliasFile function uses multiple calls to the addAlias method to include more than one class in the final alias definition file. The parent folder of the two class definitions is C:/Work.

function createAliasFile
    fileMgr = matlab.alias.AliasFileManager;
    addAlias(fileMgr,...
        NewName="myapp.ImageCropper",...
        OldNames="myapp.inprogress.ImageCropper");
    addAlias(fileMgr,...
        NewName="myapp.ImageDenoiser",...
        OldNames="myapp.inprogress.ImageDenoiser");
    writeAliasFile(fileMgr);
end

Change the current working directory to the Work folder and call createAliasFile.

createAliasFile

Work folder structure with two classes, script, and alias file

The aliasing feature does not support directly renaming packages. To rename a package, you must rename every class inside that package, as shown in this example.

Because fileMgr is scoped to the function, create another instance of AliasFileManager using the location parameter to get access to the alias definitions. Access the Aliases property of the new instance to see a summary of the class alias definitions.

aliasFile = matlab.alias.AliasFileManager("C:\Work")
aliasFile.Aliases
aliasFile = 

  AliasFileManager with properties:

    Aliases: [1×2 matlab.alias.AliasDefinition]


ans = 

1×2 AliasDefinition array showing old and new names:

          New Name                     Old Name(s)           
    _____________________    ________________________________

    "myapp.ImageCropper"     "myapp.inprogress.ImageCropper" 
    "myapp.ImageDenoiser"    "myapp.inprogress.ImageDenoiser"