padv.builtin.query.FindFilesWithLabel Class

Namespace: padv.builtin.query
Superclasses: padv.Query, padv.builtin.query.FindArtifacts

Query for finding files with project label

Description

This class requires CI/CD Automation for Simulink Check.

The padv.builtin.query.FindFilesWithLabel class provides a query that can return files that use the specified project label. You can automatically include or exclude certain files by using the optional name-value arguments. If you do not need to specify a project label, you can use a built-in query like padv.builtin.query.FindFileWithAddress or padv.builtin.query.FindArtifacts instead.

You can use this query in your process model to find files for your tasks to iterate over.

The padv.builtin.query.FindFilesWithLabel class is a handle class.

Creation

Description

query = padv.builtin.query.FindFilesWithLabel(categoryName,labelName) creates a query for finding files that use the project label labelName from the project label category categoryName. For more information about project labels, see Add Labels to Project Files.

example

query = padv.builtin.query.FindFilesWithLabel(___,Name=Value) sets certain properties using one or more name-value arguments. For example, padv.builtin.query.FindFilesWithLabel("Classification","Design",Name = "FindMyLabeledFiles") creates a query with the name "FindMyLabeledFiles".

The padv.builtin.query.FindFilesWithLabel class also has other properties, but you cannot set those properties during query creation.

Input Arguments

expand all

`categoryName` — Name of category for project label
string | character vector

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

The query uses categoryName to specify the first entry for the query property IncludeLabel. For more information about project labels, see Add Labels to Project Files.

Example: "Classification"

Data Types: char | string

`labelName` — Name of project label
string | character vector

Name of project label, specified as a string or a character vector.

The query uses labelName to specify the second entry for the query property IncludeLabel. For more information about project labels, see Add Labels to Project Files.

Example: "Design"

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: query = padv.builtin.query.FindFilesWithLabel("Classification","Design",Name = "FindMyLabeledFiles")

`ExcludeLabel` — Exclude files with specific project label
cell array

Exclude files with specific project label, specified as a cell array where the first entry is the project label category and the second entry is the project label name.

For more information about project labels, see Add Labels to Project Files.

Example: {"Classification","Design"}

Data Types: cell

`ExcludePath` — Exclude files where path contains specific text
string | character vector

Exclude files where the path contains specific text, specified as a string or a character vector. Consider using ExcludePathRegex instead.

Example: "Control"

Data Types: string

`ExcludePathRegex` — Exclude files where path matches regular expression pattern
string | character vector

Exclude files where the path matches a regular expression pattern, specified as a string or a character vector. ExcludePathRegex expects UNIX^®-style path separators.

If you want to use a literal path, use ExcludePath instead. You can specify either ExcludePath or ExcludePathRegex but not both.

Data Types: char | string

`IncludeLabel` — Find files with specific project label
cell array

Find files with specific project label, specified as a cell array where the first entry is the project label category and the second entry is the project label name.

Alternatively, you can specify the first and second entries using the arguments categoryName and labelName. The query uses those arguments to specify the entries for IncludeLabel. For more information about project labels, see Add Labels to Project Files.

Example: {"Classification","Design"}

Data Types: cell

`IncludePath` — Find files where path contains specific text
string | character vector

Find files where the path contains specific text, specified as a string. Consider using IncludePathRegex instead.

Example: "Control"

Data Types: char | string

`IncludePathRegex` — Find files where path matches regular expression pattern
string | character vector

Find files where the path matches a regular expression pattern, specified as a character vector or string. IncludePathRegex expects UNIX-style path separators.

If you want to use a literal path, use IncludePath instead. You can specify either IncludePath or IncludePathRegex but not both.

Data Types: char | string

`Name` — Unique identifier for query
string | character vector

Unique identifier for query, specified as a string or a character vector.

Example: "FindMyLabeledFiles"

Data Types: char | string

Properties

expand all

`ArtifactType` — Type of artifact
`"m_file"` | `"other_file"` | ...

Type of artifact, specified as one or more of the values in this table. To specify multiple values, use an array.

Category	Artifact Type	Description
MATLAB^®	`"m_class"`	MATLAB class
	`"m_file"`	MATLAB file
	`"m_func"`	MATLAB function
	`"m_method"`	MATLAB class method
	`"m_property"`	MATLAB class property
Model Advisor	`"ma_config_file"`	Model Advisor configuration file
Model Advisor	`"ma_justification_file"`	Model Advisor justification file
Process Advisor	`"padv_dep_artifacts"`	Related artifacts that current artifact depends on
Process Advisor	`"padv_output_file"`	Process Advisor output file
Project	`"project"`	Current project file
Requirements	`"mwreq_item"`	Requirement (since R2024b)
	`"sl_req"`	Requirement (for R2024a and earlier)
	`"sl_req_file"`	Requirement file
	`"sl_req_table"`	Requirements Table
Stateflow^®	`"sf_chart"`	Stateflow chart
	`"sf_graphical_fcn"`	Stateflow graphical function
	`"sf_group"`	Stateflow group
	`"sf_state"`	Stateflow state
	`"sf_state_transition_chart"`	Stateflow state transition chart
	`"sf_truth_table"`	Stateflow truth table
Simulink^®	`"sl_block_diagram"`	Block diagram
	`"sl_data_dictionary_file"`	Data dictionary file
	`"sl_embedded_matlab_fcn"`	MATLAB function
	`"sl_block_diagram"`	Block diagram
	`"sl_library_file"`	Library file
	`"sl_model_file"`	Simulink model file
	`"sl_protected_model_file"`	Protected Simulink model file
	`"sl_subsystem"`	Subsystem
	`"sl_subsystem_file"`	Subsystem file
System Composer™	`"zc_block_diagram"`	System Composer architecture
	`"zc_component"`	System Composer architecture component
	`"zc_file"`	System Composer architecture file
Tests	`"harness_info_file"`	Harness info file
	`"sl_harness_block_diagram"`	Harness block diagram
	`"sl_harness_file"`	Test harness file
	`"sl_test_case"`	Simulink Test™ case
	`"sl_test_case_result"`	Simulink Test case result
	`"sl_test_file"`	Simulink Test file
	`"sl_test_iteration"`	Simulink Test iteration
	`"sl_test_iteration_result"`	Simulink Test iteration result
	`"sl_test_report_file"`	Simulink Test result report
	`"sl_test_result_file"`	Simulink Test result file
	`"sl_test_resultset"`	Simulink Test result set
	`"sl_test_seq"`	Test Sequence
	`"sl_test_suite"`	Simulink Test suite
	`"sl_test_suite_result"`	Simulink Test suite result

Example: "m_file"

Example: ["m_file" "other_file"]

`IncludeLabel` — Find files with specific project label
cell array

Find files with specific project label, specified as a cell array where the first entry is the project label category and the second entry is the project label name.

Example: {"Classification","Design"}

Data Types: cell

`ExcludeLabel` — Exclude files with specific project label
cell array

Exclude files with specific project label, specified as a cell array where the first entry is the project label category and the second entry is the project label name.

For more information about project labels, see Add Labels to Project Files.

Example: {"Classification","Design"}

Data Types: cell

`IncludePathRegex` — Find files where path matches regular expression pattern
string | character vector

Find files where the path matches a regular expression pattern, specified as a string or character vector. IncludePathRegex expects UNIX-style path separators.

If you want to use a literal path, use IncludePath instead. You can specify either IncludePath or IncludePathRegex but not both.

Data Types: char | string

`ExcludePathRegex` — Exclude files where path matches regular expression pattern
string | character vector

Exclude files where the path matches a regular expression pattern, specified as a string or a character vector. ExcludePathRegex expects UNIX-style path separators.

If you want to use a literal path, use ExcludePath instead. You can specify either ExcludePath or ExcludePathRegex but not both.

Data Types: char | string

`FilterSubFileArtifacts` — Filter out sub-file artifacts from query results
`1` (`true`) (default) | `0` (`false`)

Filter out sub-file artifacts from query results, specified as a numeric or logical 1 (true) or 0 (false).

A sub-file is a part of a larger file. For example, a subsystem is a sub-file of a model file.

Example: false

Data Types: logical

`InProject` — Include only files added to project
`0` (`false`) (default) | `1` (`true`)

Include only files that have been added to the project, specified as a numeric or logical 1 (true) or 0 (false).

For more information about how to add or remove files from a project, see Manage Project Files.

Example: true

Attributes:

Dependent true

Data Types: logical

`Title` — Query title
`"All files with label ''"` (default) | string | character vector

Query title, specified as a string or a character vector.

When you specify a project label name, the query automatically updates the Title to include that project label name. For example, "All files with label 'Design'".

Example: "Find my labeled files"

Data Types: string

`DefaultArtifactType` — Default artifact type returned by query
`"padv_output_file"` (default) | `"m_file"` | `"other_file"` | ...

Default artifact type returned by the query, specified as one or more of the values in this table. To specify multiple values, use an array.

Category	Artifact Type	Description
MATLAB	`"m_class"`	MATLAB class
	`"m_file"`	MATLAB file
	`"m_func"`	MATLAB function
	`"m_method"`	MATLAB class method
	`"m_property"`	MATLAB class property
Model Advisor	`"ma_config_file"`	Model Advisor configuration file
Model Advisor	`"ma_justification_file"`	Model Advisor justification file
Process Advisor	`"padv_dep_artifacts"`	Related artifacts that current artifact depends on
Process Advisor	`"padv_output_file"`	Process Advisor output file
Project	`"project"`	Current project file
Requirements	`"mwreq_item"`	Requirement (since R2024b)
	`"sl_req"`	Requirement (for R2024a and earlier)
	`"sl_req_file"`	Requirement file
	`"sl_req_table"`	Requirements Table
Stateflow	`"sf_chart"`	Stateflow chart
	`"sf_graphical_fcn"`	Stateflow graphical function
	`"sf_group"`	Stateflow group
	`"sf_state"`	Stateflow state
	`"sf_state_transition_chart"`	Stateflow state transition chart
	`"sf_truth_table"`	Stateflow truth table
Simulink	`"sl_block_diagram"`	Block diagram
	`"sl_data_dictionary_file"`	Data dictionary file
	`"sl_embedded_matlab_fcn"`	MATLAB function
	`"sl_block_diagram"`	Block diagram
	`"sl_library_file"`	Library file
	`"sl_model_file"`	Simulink model file
	`"sl_protected_model_file"`	Protected Simulink model file
	`"sl_subsystem"`	Subsystem
	`"sl_subsystem_file"`	Subsystem file
System Composer	`"zc_block_diagram"`	System Composer architecture
	`"zc_component"`	System Composer architecture component
	`"zc_file"`	System Composer architecture file
Tests	`"harness_info_file"`	Harness info file
	`"sl_harness_block_diagram"`	Harness block diagram
	`"sl_harness_file"`	Test harness file
	`"sl_test_case"`	Simulink Test case
	`"sl_test_case_result"`	Simulink Test case result
	`"sl_test_file"`	Simulink Test file
	`"sl_test_iteration"`	Simulink Test iteration
	`"sl_test_iteration_result"`	Simulink Test iteration result
	`"sl_test_report_file"`	Simulink Test result report
	`"sl_test_result_file"`	Simulink Test result file
	`"sl_test_resultset"`	Simulink Test result set
	`"sl_test_seq"`	Test Sequence
	`"sl_test_suite"`	Simulink Test suite
	`"sl_test_suite_result"`	Simulink Test suite result

Example: "m_file"

Example: ["m_file" "other_file"]

`Parent` — Initial query that runs before iteration query
`padv.Query` | `Name` of `padv.Query` object

Initial query that runs before iteration query, specified as either a padv.Query object or the Name of a padv.Query object. When you specify an iteration query for a task, the parent query is the initial query that the build system runs before running the specified iteration query.

For information on how to improve Process Advisor load times by sharing query instances across your process model, see Best Practices for Process Model Authoring.

Example: sharedQuery

Example: "FindMyInitialArtifacts"

`ShowFileExtension` — Show file extensions for returned files
`0` (`false`) | `1` (`true`)

Show file extensions in the Alias property of returned files, specified as a numeric or logical 1 (true) or 0 (false). The Alias property controls the display name for the artifact in the Tasks column in Process Advisor.

By default, queries strip file extensions from the Alias property of each task iteration artifact. To show file extensions for all artifacts in the Tasks column, select the project setting Show file extensions. To keep file extensions in the results for a specific query, specify the query property ShowFileExtension as true.

Example: true

Data Types: logical

`SortArtifacts` — Setting for automatically sorting artifacts by address
`true` or `1` (default) | `false` or `0`

Setting for automatically sorting artifacts by address, specified as a numeric or logical 1 (true) or 0 (false). When a query returns artifacts, the artifacts should be in a consistent order. By default, the build system sorts artifacts by the artifact address.

Alternatively, you can sort artifacts in a different order by overriding the internal sortArtifacts method in a subclass that defines a custom sort behavior. For an example, see Sort Artifacts in Specific Order.

The build system automatically calls the sortArtifacts method when using the process model. The sortArtifacts method expects two input arguments: a padv.Query object and a list of padv.Artifact objects returned by the run method. The sortArtifacts method should return a list of sorted padv.Artifact objects.

Example: SortArtifacts = false

Data Types: logical

`FunctionHandle` — Handle to function that function-based query runs
`function_handle`

Handle to the function that a function-based query runs, specified as a function_handle.

If you define your query functionality inside a function and you or the build system call run on the query, the query runs the function specified by the function_handle.

The built-in queries are defined inside classes and do not use the FunctionHandle.

Example: FunctionHandle = @FunctionForQuery

Data Types: function_handle

Methods

expand all

Specialized Public Methods

This class overrides the following inherited methods.

run

Run query to find the artifacts that meet the criteria specified by the query.

The query returns a padv.Artifact object or an array of padv.Artifact objects that represent those artifacts.

Note

You do not need to manually invoke this method inside your process model. The build system automatically invokes the run method to find artifacts.

The run method inside this built-in query runs on a query object obj and returns artifacts artifacts. If you inherit from this built-in query, make sure to use the same method signature inside your custom query:

function artifacts = run(obj,~)
    ...
end

Examples

collapse all

Find Files with Specific Project Label

Suppose that you have a project that contains several MATLAB scripts and you want a custom task to only run for MATLAB script files with a specific project label.

In your process model, you can use the FindFilesWithLabel query in your task definition to find files that your tasks can iterate over (IterationQuery). For example, if the scripts that you want to run the task on use the project label ProjectTooling from the project label category Tools:

    taskObj = addTask(pm, "MyCustomTask",...
        IterationQuery = padv.builtin.query.FindFilesWithLabel(...
        "Tools","ProjectTooling"),...
        InputQueries = padv.builtin.query.GetIterationArtifact);

When you specify InputQueries as padv.builtin.query.GetIterationArtifact, that allows the task to use the artifacts returned by IterationQuery as inputs to the task.

In Process Advisor, view the updated Tasks by clicking Refresh Tasks and switching to the Project view. For the task MyCustomTask, there is one task iteration for each file with the ProjectTooling project label.

Test `FindFilesWithLabel` Query Outside Process Model

Although you typically use a query inside your process model, you can run an instance of the FindFilesWithLabel query outside of your process model to confirm which artifacts the query returns.

Open a project. For this example, you can open the Process Advisor example project.

processAdvisorExampleStart

Create an instance of the query. You can use the arguments of the query to filter the query results. For example, to find files that use the Design project label from the Classification project label category:

q = padv.builtin.query.FindFilesWithLabel("Classification","Design");

Run the query and inspect the array of artifacts that the query returns.

run(q)

ans = 

  1×24 Artifact array with properties:

    Type
    Parent
    ArtifactAddress
    Alias

The ArtifactAddress property contains the address of the file. If you only need to find a specific file at a specific address, you can use the built-in query padv.builtin.query.FindFileWithAddress instead.

Capabilities and Limitations

This table identifies functionality that is supported by the query.

Functionality	Supported?
Input query for task	No.
Iteration query for task	Yes.

padv.builtin.query.FindFilesWithLabel Class

Description

Creation

Description

Input Arguments

categoryName — Name of category for project label string | character vector

labelName — Name of project label string | character vector

ExcludeLabel — Exclude files with specific project label cell array

ExcludePath — Exclude files where path contains specific text string | character vector

ExcludePathRegex — Exclude files where path matches regular expression pattern string | character vector

IncludeLabel — Find files with specific project label cell array

IncludePath — Find files where path contains specific text string | character vector

IncludePathRegex — Find files where path matches regular expression pattern string | character vector

Name — Unique identifier for query string | character vector

Properties

ArtifactType — Type of artifact "m_file" | "other_file" | ...

IncludeLabel — Find files with specific project label cell array

ExcludeLabel — Exclude files with specific project label cell array

IncludePathRegex — Find files where path matches regular expression pattern string | character vector

ExcludePathRegex — Exclude files where path matches regular expression pattern string | character vector

FilterSubFileArtifacts — Filter out sub-file artifacts from query results 1 (true) (default) | 0 (false)

InProject — Include only files added to project 0 (false) (default) | 1 (true)

Attributes:

Title — Query title "All files with label ''" (default) | string | character vector

DefaultArtifactType — Default artifact type returned by query "padv_output_file" (default) | "m_file" | "other_file" | ...

Parent — Initial query that runs before iteration query padv.Query | Name of padv.Query object

ShowFileExtension — Show file extensions for returned files 0 (false) | 1 (true)

SortArtifacts — Setting for automatically sorting artifacts by address true or 1 (default) | false or 0

FunctionHandle — Handle to function that function-based query runs function_handle

Methods

Specialized Public Methods

Examples

Find Files with Specific Project Label

Test FindFilesWithLabel Query Outside Process Model

Capabilities and Limitations

See Also

`categoryName` — Name of category for project label
string | character vector

`labelName` — Name of project label
string | character vector

`ExcludeLabel` — Exclude files with specific project label
cell array

`ExcludePath` — Exclude files where path contains specific text
string | character vector

`ExcludePathRegex` — Exclude files where path matches regular expression pattern
string | character vector

`IncludeLabel` — Find files with specific project label
cell array

`IncludePath` — Find files where path contains specific text
string | character vector

`IncludePathRegex` — Find files where path matches regular expression pattern
string | character vector

`Name` — Unique identifier for query
string | character vector

`ArtifactType` — Type of artifact
`"m_file"` | `"other_file"` | ...

`IncludeLabel` — Find files with specific project label
cell array

`ExcludeLabel` — Exclude files with specific project label
cell array

`IncludePathRegex` — Find files where path matches regular expression pattern
string | character vector

`ExcludePathRegex` — Exclude files where path matches regular expression pattern
string | character vector

`FilterSubFileArtifacts` — Filter out sub-file artifacts from query results
`1` (`true`) (default) | `0` (`false`)

`InProject` — Include only files added to project
`0` (`false`) (default) | `1` (`true`)

`Title` — Query title
`"All files with label ''"` (default) | string | character vector

`DefaultArtifactType` — Default artifact type returned by query
`"padv_output_file"` (default) | `"m_file"` | `"other_file"` | ...

`Parent` — Initial query that runs before iteration query
`padv.Query` | `Name` of `padv.Query` object

`ShowFileExtension` — Show file extensions for returned files
`0` (`false`) | `1` (`true`)

`SortArtifacts` — Setting for automatically sorting artifacts by address
`true` or `1` (default) | `false` or `0`

`FunctionHandle` — Handle to function that function-based query runs
`function_handle`

Test `FindFilesWithLabel` Query Outside Process Model