carb::filesystem::FindFilesArgs

Defined in carb/filesystem/FindFiles.h

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

const char *const *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. If relative, the value of IFileSystem::getAppDirectoryPath() is prepended to the path.

Warning

Must not be nullptr.

uint32_t searchPathsCount

Number of paths in searchPaths. Must be greater than 0.

const char *const *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).

Warning

Must not be nullptr.

uint32_t matchWildcardsCount

Number of patterns in matchWildcards. Must be greater than 0.

const char *const *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.

May be nullptr.

uint32_t excludeWildcardsCount

Number of patterns in excludeWildcards. May be 0.

const char *const *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)

May be nullptr

uint32_t ignorePrefixesCount

Number of prefixes in ignorePrefixes. May be 0.

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.