FindFilesArgs#

Fully qualified name: carb::filesystem::FindFilesArgs

struct FindFilesArgs#

Search parameters passed to findFiles().

Recommended usage:

FindFilesArgs args{}; // this zero initializes arguments

const char* const* paths = { "/myPath", "myRelativePath" };
const char* const* patterns = { "*.dll" };

args.searchPaths = paths;
args.searchPathsCount = CARB_COUNTOF(paths);

args.matchWildcards = patterns;
args.matchWildcardsCount = CARB_COUNTOF(patterns);

args.onMatched = [](const char* canonical, void*) { printf("found: %s\n", canonical); };

if (!findFiles(args)) { CARB_LOG_ERROR(" :( "); }

Public Members

cpp::span<const cpp::string_view> searchPaths#

A list of paths (directories) to search.

If kFindFilesFlagReplaceEnvironmentVariables is specified in flags, tokens in the form ${MY_ENV_VAR} will be replaced with the corresponding environment variable.

If kFindFilesFlagRecursive is specified in flags, each path is searched recursively.

Paths may be absolute or relative.

Warning

Relative paths are relative to IFileSystem::getAppDirectoryPath(), not the working directory.

cpp::span<const cpp::string_view> matchWildcards#

The wildcard pattern to match files in the given searchPaths.

Special characters are:

* matches all characters
? matches a single character.

For example, given the file "libMyPlugin.plugin.dll":

* -> Matches!
lib -> Not a match.
*.so -> Not a match.
lib* -> Matches!
*.plugin.* -> Matches!
libMyPlugin.plugin?dll -> Matches!

When matching, only the filename is considered. So, given the path /a/b/c/d.txt only d.txt is considered when matching.

The extension of the filename can be ignored by passing the kFindFilesFlagMatchStem to flags.

Matched files may be excluded (see excludeWildcards below).

cpp::span<const cpp::string_view> excludeWildcards#

The wildcard pattern to exclude files in the given search paths.

Pattern matching follow the same rules as matchWildcards.

These patterns are checked only when the filename matches matchWildcards. If the filename matches a pattern in both matchWildcards and excludeWildcards, the file is excluded.

cpp::span<const cpp::string_view> ignorePrefixes#

A list of prefixes to ignore during pattern matching.

If not pattern matches a filename, pattern matching will be attempted again with the prefixes in this list stripped. For example, given:

ignorePrexies = { "lib" };
matchWildcard = { "MyPlugin.plugin.*" };

We see the following output:

MyPlugin.plugin.dll -> Match!
libMyPlugin.plugin.dll -> Match! (“lib” prefix was ignored)

IFileSystem *fs#

IFileSystem to use to walk the given search paths.

If nullptr, tryAcquireInterface<IFileSystem> is called.

FindFilesOnFilterNonCanonicalFn *onFilterNonCanonical#

Callback for each encountered file invoked before canonicalization and pattern matching.

This callback is invoked on each file in the given search paths. The callback is invoked before many of the expensive parts of the search algorithm, such as file canonicalization and pattern matching. May be nullptr.

void *onFilterNonCanonicalContext#: Context passed to onFilterNonCanonical. May be nullptr.

FindFilesOnMatchedFn *onMatched#

Callback invoked when a file matches a pattern matchWildcards and does not match a pattern in excludeWildcards.

May be nullptr.

void *onMatchedContext#: Context passed to onMatched. May be nullptr.

FindFilesOnExcludedFn *onExcluded#

Callback invoked when a file matches a pattern matchWildcards and excludeWildcards.

May be nullptr.

void *onExcludedContext#: Context passed to onExcluded. May be nullptr.

FindFilesOnSkippedFn *onSkipped#

Callback invoked when a file matches does not match a pattern in matchWildcards.

May be nullptr.

void *onSkippedContext#: Context passed to onSkipped. May be nullptr.

FindFilesOnSearchPathFn *onSearchPath#

Callback invoked when starting a search in one of the given search paths.

May be nullptr.

void *onSearchPathContext#: Context passed to onSearchPath. May be nullptr.

FindFilesFlag flags#: Bitmask of flags to change search behavior. See FindFilesFlag.