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".

This is an URL, so it expected to be percent-encoded, and it may also have a protocol. Like "castle-data:/foo/bar/" or "file:///home/user/dir/".

Mask

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

This is not a URL, so it is not percent-encoded.

PathAndMask

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

This is an URL, so it is expected to be percent-encoded, and it may also have a protocol. Like "castle-data:/foo/bar/" or "file:///home/user/dir/".

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.

Source: files/castlefindfiles.pas (line 170).

This item has no description.

Source: files/castlefindfiles.pas (line 172).

This item has no description.

Source: files/castlefindfiles.pas (line 176).

This item has no description.

Source: files/castlefindfiles.pas (line 178).

Like FindFiles, but return found files as a list. Caller is responsible for freeing the returned list.

Source: files/castlefindfiles.pas (line 185).

This item has no description.

Source: files/castlefindfiles.pas (line 187).

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).

Source: files/castlefindfiles.pas (line 203).

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

Source: files/castlefindfiles.pas (line 208).

Find first file matching given Mask inside Path, always ignores case (regardless of OS conventions). If found, returns True and sets FileInfo. Otherwise, returns False and leaves FileInfo undefined.

Source: files/castlefindfiles.pas (line 216).

Assuming that PathAndMask is a string containing URL prefix and a filename with wildcard characters * and ?, split into Path and Mask.

It is guaranteed that Path+Mask equal exactly PathAndMask. ( This also implies we do no percent-decoding here. )

Note that this doesn't really treat PathAndMask as a full URL: in a real URL, we would treat ? as part of the "query". And ExtractUriName would even strip it. Here we assume ? is part of mask.

Source: files/castlefindfiles.pas (line 230).

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

This item has no description.

This item has no description.

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.

Source: files/castlefindfiles.pas (line 71).

This item has no description.

Source: files/castlefindfiles.pas (line 115).