resolvePath

Resolve path that contains tokens

collapse all in page

    Syntax

    resolvedPath = resolvePath(taskObj,pathWithTokens)

    Description

    resolvedPath = resolvePath(taskObj,pathWithTokens) resolves a path that uses tokens like $TIMESTAMP$ to the actual path.

    Note

    You can only call this function during the execution of the run method or dryRun method of a task.

    example

    Examples

    collapse all

    Suppose you want the task Collect Model Maintainability Metrics to generate reports into different subfolders based on the username of the current user. Since the username is dynamic, you can add a custom token that acts as a placeholder for the username in the path and then the task can resolve the tokenized path when the task runs. Inside the task definition file, the Collect Model Maintainability Metrics task uses the resolvePath method inside the run method and dryRun method of the task to resolve tokenized paths for the ReportPathproperty.

    Open the Process Advisor example project. The model AHRS_Voter opens with the Process Advisor pane to the left of the Simulink® canvas.

    processAdvisorExampleStart

    In Process Advisor, open the process model by clicking the Edit process model button .

    Inside the process model, add a custom token to the process model object, pm, by using the addToken function. This example creates a new token, "$USER:USERNAME$", that resolves to the username of the current user by getting the 'USERNAME' environment variable. This example token does not require information about the task iteration artifact, so the input argument is specified as ~.

    addToken(pm,"$USER:USERNAME$",@(~)getenv('USERNAME'));

    The built-in tasks automatically resolve tokenized names and paths for commonly tokenized properties such as OutputDirectory, ReportPath, and ReportName. For example, the Collect Model Maintainability Metrics task organizes reports into folders by using tokens in the ReportPath property. By default, the task generates reports in the path $DEFAULTOUTPUTDIR$/$ITERATIONARTIFACT$/metrics, which the task resolves for each task iteration.

    To organize the reports by user, customize the ReportPath property of the task to include a username by using the custom token $USER:USERNAME$.

    mmMetricTask = pm.addTask(padv.builtin.task.CollectMetrics());
mmMetricTask.ReportPath = fullfile(mmMetricTask.ReportPath,"$USER:USERNAME$");

    To see how the Collect Model Maintainability Metrics task resolves the tokenized ReportPath property value, you can inspect the use of the resolvePath method inside the task definition file. Inside the run method, the task resolves the ReportPath property by using the resolvePath method and assigns the resolved path as the output directory for the generated report.

    open padv.builtin.task.CollectMetrics
    To add this functionality to other task properties, you can create a custom task and use the resolvePath method inside the run and dryRun methods in the task definition file.

    In Process Advisor, refresh task information by clicking the Refresh Tasks button in the warning banner.

    Dry run the Collect Model Maintainability Metrics task by pointing to the task, opening the options menu (...), and then clicking Dry Run Task. Dry runs allow you to quickly generate representative task outputs without actually running the task.

    The reports for each model go into a subfolder with the username of the current user, as shown in this example build log with the example username myusername.

    ...
## Task: Collect Model Maintainability Metrics
#### Input Artifacts:
####      02_Models/AHRS_Voter/specification/AHRS_Voter.slx
#### Dependent Artifacts:
####      02_Models/AHRS_Voter/specification/data/DD_AHRS_Voter.sldd
####      02_Models/common/specification/data/csSingleInstance.sldd
####      02_Models/common/specification/data_types/bus_types.sldd
####      processmodel.m
#### Output Artifacts:
####      PA_Results/AHRS_Voter/metrics/myusername/AHRS_Voter_ModelMaintainability.pdf
...

    By default, the built-in task padv.builtin.task.GenerateModelComparison uses a Git™ branch named "main" for the model comparison. If there is no "main" branch, the task generates a warning and defaults to using the current branch. Suppose you just want the task to default to using the current branch. You can create a custom token that represents the current branch and use that token when specifying the task property MainBranch. To resolve the tokenized branch name, have the custom task override the run method to call resolvePath on the MainBranch property.

    Open the Process Advisor example project. The model AHRS_Voter opens with the Process Advisor pane to the left of the Simulink canvas.

    processAdvisorExampleStart

    In the project, create a function that finds and returns the name of the current Git branch.

    function branchName = getCurrentGitBranch()
    try
        branchName = gitrepo().CurrentBranch.Name;
    catch
        branchName = 'main';
    end
end

    In the processmodel.m file for the project, edit the file to add a custom token that acts as a placeholder for the current branch name. For this example, you can define a custom token $GIT:CURRENT_BRANCH$ that uses the function getCurrentGitBranch to get the current Git branch name. For more information on custom tokens, see addToken.

        addToken(pm,"$GIT:CURRENT_BRANCH$",@(~)getCurrentGitBranch);

    In your project, create a new class that inherits from padv.builtin.task.GenerateModelComparison. Specify the MainBranch property value using the token $GIT:CURRENT_BRANCH$ and resolve the tokenized branch name by using the resolvePath method inside the run method.

    classdef DiffCurrentBranch < padv.builtin.task.GenerateModelComparison
    methods
        function obj = DiffCurrentBranch(options)
            arguments
                options.Name = "DiffCurrentBranch";
                options.Title = "Diff Current Branch";
                options.MainBranch = "$GIT:CURRENT_BRANCH$"; % use token
            end
            obj@padv.builtin.task.GenerateModelComparison(Name = options.Name);
            obj.Title = options.Title;
            obj.MainBranch = options.MainBranch;
        end

        function taskResult = run(taskObj,input)

            % Extend the built-in GenerateModelComparison behavior
            % Resolve the tokenized MainBranch name
            tokenizedBranch = taskObj.MainBranch;
            resolvedBranch = resolvePath(taskObj,tokenizedBranch);
            taskObj.MainBranch = resolvedBranch;
            
            % Then use GenerateModelComparison to run the comparison
            taskResult = run@padv.builtin.task.GenerateModelComparison(taskObj,input);

        end

    end
end
    Optionally, to support this behavior during dry runs, you can override the dryRun method to resolve the tokenized branch name for dry runs too.

    Add the custom task to your process model.

        addTask(pm,processLibrary.task.DiffCurrentBranch);
    When you run the task in Process Advisor, the task automatically uses the current Git branch for the model comparison and does not generate a warning.

    Input Arguments

    collapse all

    Task, specified as a padv.Task object.

    Example: padv.Task("MyTask")

    Text that contains tokens, specified as a string.

    Example: "$PROJECTROOT$"

    Example: fullfile("$PROJECTROOT$","$ITERATIONARTIFACT$","reports")

    Data Types: string

    Output Arguments

    collapse all

    Resolved path with tokens replaced by their actual values, returned as a string.

    See Also

    | |