Castle Game Engine: CastleFindFiles

# Unit CastleFindFiles
Description | Uses | Classes, Interfaces, Objects and Records | Functions and Procedures | Types | Constants | Variables
## Description Finding files matching some mask. ## Uses SysUtils CastleUtils Classes CastleGenericLists ## Overview ### Classes, Interfaces, Objects and Records
Name | Description
--- | ---
record `TFileInfo` |
### Functions and Procedures
`function FindFiles(const Path, Mask: string; const FindDirectories: boolean; FileMethod: TFoundFileMethod; Options: TFindFilesOptions): Cardinal; overload;`
`function FindFiles(const Path, Mask: string; const FindDirectories: boolean; FileProc: TFoundFileProc; FileProcData: Pointer; Options: TFindFilesOptions): Cardinal; overload;`
`function FindFiles(const PathAndMask: string; const FindDirectories: boolean; FileMethod: TFoundFileMethod; Options: TFindFilesOptions): Cardinal; overload;`
`function FindFiles(const PathAndMask: string; const FindDirectories: boolean; FileProc: TFoundFileProc; FileProcData: Pointer; Options: TFindFilesOptions): Cardinal; overload;`
`function SearchFileHard(Path: string; const Base: string; out NewBase: string): boolean;`
`function FindFirstFile(const Mask: string; out FileInfo: TFileInfo): boolean;`
### Types
`TFileInfoList = specialize TGenericStructList<TFileInfo>;`
`TFoundFileProc = procedure (const FileInfo: TFileInfo; Data: Pointer);`
`TFoundFileMethod = procedure (const FileInfo: TFileInfo) of object;`
`TFindFilesOption = (...);`
`TFindFilesOptions = set of TFindFilesOption;`
## Description ### Functions and Procedures
`function FindFiles(const Path, Mask: string; const FindDirectories: boolean; FileMethod: TFoundFileMethod; Options: TFindFilesOptions): Cardinal; overload;`
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. 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). 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.
`function FindFiles(const Path, Mask: string; const FindDirectories: boolean; FileProc: TFoundFileProc; FileProcData: Pointer; Options: TFindFilesOptions): Cardinal; overload;`
`function FindFiles(const PathAndMask: string; const FindDirectories: boolean; FileMethod: TFoundFileMethod; Options: TFindFilesOptions): Cardinal; overload;`
`function FindFiles(const PathAndMask: string; const FindDirectories: boolean; FileProc: TFoundFileProc; FileProcData: Pointer; Options: TFindFilesOptions): Cardinal; overload;`
`function SearchFileHard(Path: string; const Base: string; out NewBase: string): boolean;`
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).
`function FindFirstFile(const Mask: string; out FileInfo: TFileInfo): boolean;`
Find first file matching given Mask. The file can be anything (including a symlink or directory). It is not searched recursively, it is only searched for in the directory inside Mask. If found, returns `True` and sets FileInfo. Otherwise, returns `False` and leaves FileInfo undefined.
### Types
`TFileInfoList = specialize TGenericStructList<TFileInfo>;`
`TFoundFileProc = procedure (const FileInfo: TFileInfo; Data: Pointer);`
`TFoundFileMethod = procedure (const FileInfo: TFileInfo) of object;`
`TFindFilesOption = (...);`
###### 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. For Android asset searching: note that recursive searching if unfortunately not supported. Although Android NDK contains functions to iterate over a files inside a directory, it stupidly omits the subdirectories (only returns the non-directory files). 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.
`TFindFilesOptions = set of TFindFilesOption;`
Generated by PasDoc 0.13.0 on 2015-06-15 04:43:09