matlab.alias.AliasFileManager Class

R2026b

Namespace: matlab.alias

Create and manage class alias definitions

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 that creates 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 argument is the path to the parent folder of the resources folder containing an alias definition file. 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 class.

Rename the class FirstName to SecondName using a function. In the createAliasFile function:

  1. fileMgr is an instance of class AliasFileManager.

  2. The addAlias method adds the new and old names of the class to fileMgr, with WarnOnOldName set to true.

  3. 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",WarnOnOldName=true);
    writeAliasFile(fileMgr);
end

Create a folder named Work. Save the class file with the new name, SecondName.m, and include the createAliasFile function in Work. Do not include any file named FirstName.m 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

Run createAliasFile. MATLAB creates a resources folder inside Work that includes the alias definition file.

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. Because the addAlias method call used the optional argument WarnOnOldName=true, MATLAB warns on the first use of the old class name after the alias is created.

old = FirstName
Warning: Using alias 'FirstName' is not recommended. Use 'SecondName' (new class name) instead. 

old = 

  SecondName with no properties.

Rename a class that has two existing aliases.

The class dataToolbox has an older name, dataUtility. The resources folder that contains the existing alias definition file is in a folder called Work. Rename dataToolbox to dataTool using a function. In the createAliasFile function:

  1. fileMgr is an instance of class AliasFileManager.

  2. The addAlias method adds the new and old names of the class to fileMgr. When you create an alias for a class that already has existing aliases, the OldNames argument must identify all the existing class names in order from newest to oldest. In this case, the most recent name is dataToolbox, and the older name is dataUtility, so OldNames is set to the vector ["dataToolbox","dataUtility"].

  3. The writeAliasFile method writes the alias definition file in the resources folder inside a folder named Work.

function createAliasFile
    fileMgr = matlab.alias.AliasFileManager;
    addAlias(fileMgr,NewName="dataTool",OldNames=["dataToolbox","dataUtility"]);
    writeAliasFile(fileMgr,"C:/Work");
end

Note

Under some circumstances, MATLAB issues warnings when an alias definition file already exists in the specified location. These warnings do not affect the creation of the alias definition file.

After running createAliasFile, you can instantiate the class using any of the three class names. MATLAB recognizes all three names as the same class.

oldest = dataUtility
older = dataToolbox
new = dataTool
oldest = 

  dataTool with no properties.


older = 

  dataTool with no properties.


new = 

  dataTool 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 createAliasFile in a folder named Work.

Work folder containing createAliasFIle function and myapp namespace folder

Change the current folder to Work and run createAliasFile.

cd Work
createAliasFile

Because fileMgr is scoped to the function, create another instance of AliasFileManager using the location argument 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

  • After aliasing a class to a new name, clear existing instances of the class from the workspace to avoid errors.

  • 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

expand all

See Also