Unit CastleEnumerateFiles

DescriptionUsesClasses, Interfaces, Objects and RecordsFunctions and ProceduresTypesConstantsVariables

Description

Enumerating filenames matching some mask. Intention is to wrap standard FindFirst/FindNext procedures in a much safer and cleaner interface.

Uses

Overview

Classes, Interfaces, Objects and Records

Name Description
record TEnumeratedFileInfo  

Functions and Procedures

function EnumFiles(const Mask: string; Attr: integer; FileProc: TEnumFileProc; FileProcData: Pointer; Options: TEnumFilesOptions): Cardinal; overload;
function EnumFilesObj(const Mask: string; Attr: integer; FileMethod: TEnumFileMethod; Options: TEnumFilesOptions): Cardinal; overload;
function SearchFileHard(const Path, Base: string; out NewBase: string): boolean;

Types

PEnumeratedFileInfo = ˆTEnumeratedFileInfo;
TEnumeratedFileInfoList = specialize TGenericStructList<TEnumeratedFileInfo>;
TEnumFileProc = procedure (const FileInfo: TEnumeratedFileInfo; Data: Pointer);
TEnumFileMethod = procedure (const FileInfo: TEnumeratedFileInfo) of object;
TEnumFilesOption = (...);
TEnumFilesOptions = set of TEnumFilesOption;

Description

Functions and Procedures

function EnumFiles(const Mask: string; Attr: integer; FileProc: TEnumFileProc; FileProcData: Pointer; Options: TEnumFilesOptions): Cardinal; overload;

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

Some limitations of FindFirst/FindNext underneath are reflected in our functionality. Under Windows, mask is treated somewhat hacky:

  1. Every filename conceptually has an extention under Windows, so *.* matches any file. On more sane OSes, *.* matches only files with a dot inside a filename.

  2. Extensions may be shortened to the first 3 letters. For example searching for *.txt actually searches for *.txt*, that is it finds all the files with extensions starting from txt.

Parameters
Mask
Path and filename mask. May have a path, absolute or relative. The final part (filename) may contain wildcards * and ?.
Attr
Bit-wise or of faXxx flags specifying which files to find. Normal, regular files are always found.
FileProc
Called on each file found.
Options
A set of options. See TEnumFilesOption for meaning of each option. Often [eoSymlinks] is the right choice.
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 EnumFilesObj(const Mask: string; Attr: integer; FileMethod: TEnumFileMethod; Options: TEnumFilesOptions): Cardinal; overload;
 
function SearchFileHard(const Path, Base: string; out NewBase: string): boolean;

Search for a file, ignoring the case. Path must be absolute and contain the final PathDelim. Returns filename 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).

Types

PEnumeratedFileInfo = ˆTEnumeratedFileInfo;
 
TEnumeratedFileInfoList = specialize TGenericStructList<TEnumeratedFileInfo>;
 
TEnumFileProc = procedure (const FileInfo: TEnumeratedFileInfo; Data: Pointer);
 
TEnumFileMethod = procedure (const FileInfo: TEnumeratedFileInfo) of object;
 
TEnumFilesOption = (...);
 
Values
  • eoSymlinks: Means that symlinks should also be enumerated. Excluding this from Options means that symlinks will not be reported to FileProc.

    Note that you do not control whether symlinks are enumerated using Attr parameter, you control it only by including or excluding eoSymlinks from Options.

  • eoRecursive: If eoRecursive is in Options then EnumFiles (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 eoRecursive in Options is something completely different than the flag faDirectory in Attr: faDirectory in Attr says whether to report directories to FileProc; eoRecursive says whether to descend into directories and enumerate their files too.

    Recursive does not descend into symlinks to directories. Why? Well, this would produce risk of falling into infinite loop (unless some time-consuming precautions would be taken). In other words, it's just not implemented. But it may be implemented someday, as this would be definitely something useful.

  • eoDirContentsLast: Determines the order of reporting directory contents. Meaningfull only if eoRecursive 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 eoDirContentsLast is included, then we first enter subdirectories. Only then we list directory contents to the callback.

  • eoAllowStdIn: If Mask will equal exactly '-', it will be intrepreted specially: we will then return exactly one file record, with SearchRec.Name and FullFileName equal to '-'.
  • eoReadAllFirst: If eoReadAllFirst 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 eoReadAllFirst, it's undefined (OS-dependent and sometimes just random) if the new file names will appear in the directory list.

TEnumFilesOptions = set of TEnumFilesOption;
 

Generated by PasDoc 0.12.1 on 2013-02-04 20:26:50