matlab.buildtool.io.Glob Class

Namespace: matlab.buildtool.io
Superclasses: matlab.buildtool.io.FileCollection

File collection that matches pattern

Since R2023b

Description

The matlab.buildtool.io.Glob class represents a collection of files and folders on disk that match a pattern that includes the * or ** wildcard. You can use this class to specify file-based inputs and outputs of a task. For more information about task inputs and outputs, see Improve Performance with Incremental Builds.

Creation

When you use a string that includes the * or ** wildcard to specify an argument or property that requires a file collection, MATLAB^® automatically converts the string to a Glob object. For example, plan("myTask").Inputs = ["*.m" "src/**/*.m"] results in a 1-by-2 Glob vector.

To explicitly create a Glob object, use the matlab.buildtool.io.FileCollection.fromPaths or files method.

Properties

Pattern — Pattern to match for files and folders

string scalar | character vector

Pattern to match for files and folders, specified as a string scalar or character vector, and stored as a string scalar. The pattern can include the * and ** wildcards:

• The * wildcard can appear in both filenames and pathnames. It matches any number of characters, including zero characters.

• The ** wildcard can appear in pathnames, but not in filenames. Characters next to a ** wildcard must be file separators. ** matches any number of characters, including zero characters. You can use this wildcard to represent subfolders of a specified folder recursively.

The pattern does not match any files or folders that start with a dot (.) unless the pattern itself starts with a dot. In addition, a pattern that ends with a file separator matches only folders.

Example: "src/*.m" matches all the .m files in the src folder.

Example: "src/**/*.m" matches all the .m files in the src folder and any of its subfolders.

Attributes:

GetAccess	public
SetAccess	immutable

Examples

Create File Collections

Create file collections and return their paths.

Import the FileCollection class.

import matlab.buildtool.io.FileCollection

Create the folder structure used in this example. See the code of the local function createFile, which is used to create the files, at the end of this example.

mkdir source
createFile(fullfile("source","file1.m"))
createFile(fullfile("source","file2.m"))
mkdir source private
createFile(fullfile("source","private","file3.m"))
createFile(fullfile("source","private","file4.m"))

Create a file collection from all the .m files in the source folder and any of its subfolders. In this example, fc1 is a matlab.buildtool.io.Glob object because it is defined by a pattern that includes the * and ** wildcards.

fc1 = FileCollection.fromPaths("source/**/*.m")

fc1 = Glob
     source/**/*.m 

Return the paths of the file collection. When you call paths on a Glob object, the method returns the paths to the files and folders on disk that match the Glob pattern.

fc1.paths'

ans = 4×1 string
    "source\file1.m"
    "source\file2.m"
    "source\private\file3.m"
    "source\private\file4.m"

Add a file to the source folder, and return the paths of the file collection again. Even though fc1 has not been modified, the file collection has an additional path because its pattern now matches the newly created file as well.

createFile(fullfile("source","newFile.m"))
fc1.paths'

ans = 5×1 string
    "source\file1.m"
    "source\file2.m"
    "source\newFile.m"
    "source\private\file3.m"
    "source\private\file4.m"

Now, create file collections from the .m files in the source folder and any of its subfolders, as well as from another folder named nonexistentFolder. The fromPaths static method returns fc2 as a 1-by-2 FileCollection vector. The first element of the vector is a Glob object. The second element is a matlab.buildtool.io.File object because it represents a single folder.

fc2 = FileCollection.fromPaths(["source/**/*.m" "nonexistentFolder"])

fc2 = 1×2 heterogeneous FileCollection (Glob, File) array with no properties.
     source/**/*.m      nonexistentFolder 

Return the paths of fc2. In this example, even though nonexistentFolder does not exist on disk, the paths method returns the path to it. The method searches for files and folders on disk only for patterns that include the * or ** wildcard. If you call paths on a File object, the method returns the path to the specified file or folder even if it does not exist on disk.

fc2.paths'

ans = 6×1 string
    "source\file1.m"
    "source\file2.m"
    "source\newFile.m"
    "source\private\file3.m"
    "source\private\file4.m"
    "nonexistentFolder"

Local Function

This code shows the local function used in this example.

function createFile(filename)
fclose(fopen(filename,"w"));
end

Tips

• If you call the paths method on a Glob object, the method returns the paths to the files and folders on disk that match the Glob pattern. Due to the dynamic nature of disks, calling paths at different times can result in different values even though the pattern remains the same.

Version History

Introduced in R2023b