Main Content

matlab.alias.AliasFileManager Class

Namespace: matlab.alias

Create and manage class alias definitions

Since R2021b

expand all in page

Description

The matlab.alias.AliasFileManager class enables you to create and manage class alias definitions. The alias definitions map one or more old class names to a new name. Use this functionality to change the name of an existing class while maintaining compatibility with code and MAT-files that use the older names of the class. The recommended process for creating aliases is to write a function to create an instance of AliasFileManager.

For more information, see Creating and Managing Class Aliases.

The matlab.alias.AliasFileManager class is a handle class.

Class Attributes

Sealed
true

For information on class attributes, see Class Attributes.

Creation

Description

fileMgr = matlab.alias.AliasFileManager creates an AliasFileManager instance with no alias definitions.

example

fileMgr = matlab.alias.AliasFileManager(location) creates an AliasFileManager instance and loads the alias file in the specified location. The location is the path to the parent folder of the resources folder containing an alias definition file. Using this syntax provides a convenient way to view all of the defined class aliases at location.

Input Arguments

expand all

Path to a folder containing an existing class alias definition, specified as a string scalar. The path must point to the parent folder of the resources folder containing an alias definition file. If no alias file exists at that location, MATLAB® errors.

location can be a full or relative path. Full paths are not recommended for code that is packaged for use by others because installation paths might vary.

Properties

expand all

Class alias definitions, specified as an array of AliasDefinition objects. The property contains the current class name and all active aliases for all classes in a given folder.

Attributes:

Transient
true

Methods

expand all

Examples

collapse all

Rename a class using the AliasFileManager API.

Rename the class FirstName to SecondName using a function. The createAliasFile function creates fileMgr, an instance of class AliasFileManager. The addAlias method adds the new and old names of the class to fileMgr. Finally, the writeAliasFile method writes the alias definition file inside a resources folder. The method creates the folder if it does not already exist.

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

Save the class file with the new name, SecondName.m, and the createAliasFile function in a folder named Work. No file called FirstName.m should be in the current folder or anywhere else on the path, so that once the alias is created, MATLAB finds the new alias definition.

Work folder containing createAliasFile and SecondName files

Change the active directory to Work and run createAliasFile. MATLAB creates a resources folder that includes the alias definition file.

cd Work
createAliasFile

resources folder added, containing alias definition file

MATLAB now recognizes both class names, and instances constructed using either name are defined as instances of SecondName.

old = FirstName
new = SecondName
old = 

  SecondName with no properties.


new = 

  SecondName with no properties.

Rename a class that has two existing aliases.

The class SecondName has an older alias, FirstName. Rename SecondName to ThirdName using a function. The createAliasFile function creates fileMgr, an instance of class AliasFileManager. The addAlias method adds the new and old names of the class to fileMgr. For classes with two or more existing aliases, the OldNames argument for addAlias must include all of the previous aliases in order from newest to oldest. In this case, "ThirdName" is the new name and ["SecondName","FirstName"] is the list of old names. Finally, the writeAliasFile method updates the existing alias definition file inside the resources folder. 

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

Change the active directory to Work and run createAliasFile.

cd Work
createAliasFile

Instantiate the class using all three of the class aliases. MATLAB now recognizes all three names as the same class.

oldest = FirstName
older = SecondName
new = ThirdName
oldest = 

  ThirdName with no properties.


older = 

  ThirdName with no properties.


new = 

  ThirdName with no properties.

You cannot directly rename an entire namespace using AliasFileManager, but you can change the name of each class in the namespace.

Rename the classes myapp.inprogress.ImageCropper and myapp.inprogress.ImageDenoiser using a function. The createAliasFile function creates fileMgr, an instance of class AliasFileManager. The addAlias method adds the new and old names of the class to fileMgr. Finally, the writeAliasFile method writes the alias definition file inside a resources folder. The method creates the folder if it does not already exist.

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

Save the class files in the new namespace folder and the createAliasFile in a folder named Work.

Work folder containing createAliasFIle function and myapp namespace folder

Change the active directory to Work and run createAliasFile.

cd Work
createAliasFile

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("\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"

Tips

  • The function workflow demonstrated in the examples has the advantage of automatically clearing the instance of AliasFileManager.

  • Deprecating old class aliases is not recommended. Removing the old aliases risks compatibility issues for the users of your code. To access an existing alias definition file, use the fileMgr = matlab.alias.AliasFileManager(location) constructor and read its Aliases property.

  • When a function and a class alias have the same name, introspection identifies the alias even if the function would otherwise have precedence. For example, if there is a function named MyOldClass.m and a class that has "MyOldClass" as an alias, the statement mc = matlab.metadata.Class.fromName('MyOldClass'); returns a metaclass instance of the class that defines the alias, even if the function has precedence because of path order.

Version History

Introduced in R2021b

See Also