Unit CastleFindFiles

Find all files matching the given mask, and call FileProc for them.

Parameters

Path

Path URL to search inside. May be absolute or relative. Like everywhere in our engine, it can also be a local filesystem path, although we advice using URLs for everything. May, but doesn't have to, end with slash or PathDelim. Empty Path means "the current directory".

Mask

Mask of the files to search, may contain wildcards * and ?.

PathAndMask

Overloaded versions without separate Path and Mask parameters just assume that PathAndMask contain concatenated Path + Mask, separated by any valid path delimiter.

FindDirectories

Should directories also be found (reported by FileProc). Note that this is completely independent from whether we work recursively (ffRecursive in Options).

FileProc

Called on each file found. May be Nil (useful if you are only interested in the number of files found, returned by this function).

FileProcData

Pointer passed to every call of FileProc. This routine just passes FileProcData value as "Data" parameter to each FileProc call. It is a pointer that may have absolutely any meaning you want, and may point to any data structure you want, it is useful to communicate information between the caller and the FileProc implementation.

If you don't need this, then just ignore the "Data" in your FileProc implementation, and pass anything (like Nil) as FileProcData value.

Note that the overloaded version with FileMethod parameter doesn't have any FileProcData, as in this case the instance that implements FileMethod may carry any additional information necessary.

Options

A set of options. See TFindFilesOption for meaning of each option.

Returns

How many times FileProc was called, that is: how many files/directories were matching. Useful to report to user how many files were processed, in particular to warn if nothing was processed.

Search for a file, ignoring the case. Path must be absolute URL and contain the final slash. Returns URL relative to Path.

We prefer to return just Base, if it exists, or when no alternative exists. When Base doesn't exist but some likely alternative exists (e.g. with different case), we return it.

Looks for normal files/symlinks, that can be opened as usual files. Not directories.

Returns if some file was found. Note that even when we return False, we still set NewBase (to original Base).

Find first file matching given Mask inside Path. If found, returns True and sets FileInfo. Otherwise, returns False and leaves FileInfo undefined.

Called for each file found. StopSearch is always initially False, you can change it to True to stop the enclosing FindFiles call.

Values

• ffRecursive: If ffRecursive is in Options then FindFiles (and friends) descend into subdirectories.

  Note that we always descend into every subdirectory (not only into those matching Mask, that would be pretty useless (and is a problem with Unix shell expansion)).

  Note that including ffRecursive in Options is something completely different than the FindDirectories parameter: FindDirectories says whether to report directories to FileProc; ffRecursive says whether to descend into directories and enumerate their files too.

  Recursive does not descend into symlinks to directories on Unix right now. The reason is that this would risk an infinite loop (unless some time-consuming precautions would be taken, or a level limit). In other words, it's just not implemented. But it may be implemented someday, as this would be definitely something useful.

• ffDirContentsLast: Determines the order of reporting directory contents. Meaningfull only if ffRecursive is also included in Options.

  If not included, then directory contents (files and directories matching mask) are reported to the callback first. And only then we enter the subdirectories.

  If ffDirContentsLast is included, then we first enter subdirectories. Only then we list directory contents to the callback.

• ffReadAllFirst: If ffReadAllFirst is included in the Options then before calling FileProc, we will first read all file information to an internal array. And only then we will call FileProc for each item of this array.

  Why this may be useful? This way changes to the directory (like renaming / deleting / creating files) will not have any effect on the list of files we will get. This is important if our FileProc may modify the directory contents. Without ffReadAllFirst, it's undefined (OS-dependent and sometimes just random) if the new file names will appear in the directory list.