addLabel

Attach label to project file

Syntax

addLabel(file,categoryName,labelName)

addLabel(file,categoryName,labelName,labelData)

Description

addLabel(file,categoryName,labelName) attaches the specified label in the specified category to the specified file.

addLabel(file,categoryName,labelName,labelData) attaches the label with the specified text or numeric data. You cannot add label data to built-in labels as they are read-only.

Examples

Attach a Label to a Project File

Open the Times Table App project. Use currentProject to create a project object from the currently loaded project.

matlab.project.example.timesTable
proj = currentProject;

Get a file by name.

myfile = findFile(proj,"source/timesTableGame.m")

mmyfile = 

  ProjectFile with properties:

                   Path: "C:\myProjects\examples\TimesTableApp\source\timesTableGame.m"
                 Labels: [1×1 matlab.project.Label]
               Revision: "286043ae7ee557100902fb645a6c97eca5d50472"
    SourceControlStatus: Unmodified

View the existing label by getting the Labels property of the file.

myfile.Labels

ans = 

  Label with properties:

            File: "C:\myProjects\examples\TimesTableApp\source\timesTableGame.m"
        DataType: 'none'
            Data: []
            Name: "Design"
    CategoryName: "Classification"

Attach the label "Artifact" to the file in the category "Classification".

addLabel(myfile,"Classification","Artifact")

ans = 

  Label with properties:

            File: "C:\myProjects\examples\TimesTableApp\source\timesTableGame.m"
        DataType: 'none'
            Data: []
            Name: "Artifact"
    CategoryName: "Classification"

There are now two labels, the original one and the added one. To view just the added one, index into the Labels property.

reviewlabel = myfile.Labels(1)

reviewlabel = 

  Label with properties:

            File: "C:\myProjects\examples\TimesTableApp\source\timesTableGame.m"
        DataType: 'none'
            Data: []
            Name: "Artifact"
    CategoryName: "Classification"

Detach the new label from the file. The file now only has one label.

removeLabel(myfile,reviewlabel)
myfile

myfile = 

  ProjectFile with properties:

                   Path: "C:\myProjects\examples\TimesTableApp\source\timesTableGame.m"
                 Labels: [1×0 matlab.project.Label]
               Revision: "286043ae7ee557100902fb645a6c97eca5d50472"
    SourceControlStatus: Unmodified

Attach a Label to a Subset of Files

Attach the label "Utility" in the "Classification" category to all files in the project that have the .m file extension.

Open the Times Table App project. Use currentProject to create a project object from the currently loaded project.

matlab.project.example.timesTable
proj = currentProject;

Get the list of files.

files = proj.Files;

Loop through each file. To get just the file extension, use the fileparts function and take the last part. If a file has the extension .m, attach the label "Utility".

for fileIndex = 1:numel(files)
   file = files(fileIndex);
   [~, ~, fileExtension] = fileparts(file.Path);
   if strcmp(fileExtension,".m")
       addLabel(file,"Classification","Utility");
   end
end

In the project Files view, the Classification column displays the label Utility for each .m file in the utilities folder.

Attach a Label and Label Data to a File

Create the label category "Review" and the label "To Review", and then attach the label and label data to a file. You cannot add label data to built-in labels as they are read-only.

Open the Times Table App project. Use currentProject to create a project object from the currently loaded project.

matlab.project.example.timesTable
proj = currentProject;

Create a new category "Review".

createCategory(proj,"Review","char");

For the new category, create a label "To Review".

reviewCategory = findCategory(proj,"Review");
createLabel(reviewCategory,"To Review");

Get a file by name.

myfile = findFile(proj,"source/timesTableGame.m")

myfile = 

  ProjectFile with properties:

                   Path: "C:\myProjects\examples\TimesTableApp\source\timesTableGame.m"
                 Labels: [1×1 matlab.project.Label]
               Revision: "c7603d5dd71a40484974c3f1c45d839819b7b061"
    SourceControlStatus: Unmodified

Attach the label "To Review" and a character vector of label data to the file.

addLabel(myfile,"Review","To Review","Whole team design review")

ans = 

  Label with properties:

            File: "C:\myProjects\examples\TimesTableApp\source\timesTableGame.m"
        DataType: 'char'
            Data: 'Whole team design review'
            Name: "To Review"
    CategoryName: "Review"

In the project Files view, for the timesTableGame.m file, the Review column displays the To Review label with label data.

Alternatively, you can set or change label data using the Data property.

mylabel = myfile.Labels(1);
mylabel.Data = "Final review";

Input Arguments

file — File to label

ProjectFile object

File to label, specified as a ProjectFile object. You can get the ProjectFile object by examining the project’s Files property (proj.Files), or by using findFile to find a file by name. The file must be in the project.

categoryName — Name of category for label

character vector | string scalar

Name of the category for the label, specified as a character vector or string scalar.

labelName — Name of label

character vector | string scalar | LabelDefinition object

Name of the label to attach, specified as a character vector, string scalar, or as a LabelDefinition object returned by the file.Label property or the findLabel function. You can specify a new label name that does not already exist in the project.

labelData — Data to attach to label

character vector | string scalar | numeric

Data to attach to the label, specified as a character vector, string scalar, or a numeric value. Data type depends on the label definition. Get a label to examine its DataType property using file.Label or findLabel.