lazarus/docs/xml/lazutils/fileutil.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
file://../../cc-by-sa-4-0.txt

Copyright (c) 1997-2024, by the Lazarus Development Team.

-->
<fpdoc-descriptions>
<package name="lazutils">
<!--
=======================================================================
FileUtil
=======================================================================
-->
<module name="FileUtil">
<short>
Miscellaneous routines, types, and classes for manipulating files, file 
names, and paths.
</short>
<descr>
<p>
<file>fileutils.pas</file> contains routines, types, and classes used to 
maintain compatibility with the FileUtil unit in Delphi. File routines that 
deal with UTF-8 file names are located in the <file>LazFileUtils</file> unit.
</p>
<p>
File name handling in the unit is platform- or OS-specific. For the Windows, 
Darwin (macOS), and Amiga platforms, file names are <b>NOT</b> case 
sensitive. In addition, under Darwin, the <b>NotLiteralFilenames</b> define 
is enabled. This indicates that file names cannot be compared using the 
<b>=</b> string operator.
</p>
<p>
This unit contains basic functions similar to those in the RTL, but use UTF-8 
instead of the default system encoding. Please note that AnsiToUTF8 and 
UTF8ToAnsi need a widestring manager under Linux, BSD, and macOS. Normally 
these operating systems use UTF-8 as the system encoding so the 
WideStringManager is not needed.
</p>
<p>
<file>fileutil.pas</file> is part of the <file>LazUtils</file> package.
</p>
</descr>

<!-- unresolved type reference Visibility: default -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="StrUtils"/>
<element name="Masks"/>
<element name="LazUTF8"/>
<element name="LazFileUtils"/>

<element name="UTF8FileHeader">
<short>
Byte Order Mark (BOM) used at the beginning of UTF-8-encoded files.
</short>
<descr/>
<seealso/>
</element>

<element name="FilenamesCaseSensitive">
<short>
When <b>True</b>, uppercase and lowercase file names are equivalent.
</short>
<descr>
<p>
FilenamesCaseSensitive is present when the <b>CaseInsensitiveFilenames</b> 
compiler define exists.
</p>
</descr>
<seealso/>
</element>

<element name="FilenamesLiteral">
<short>
When <b>True</b>, file names can be compared using the <b>=</b> string 
operator.
</short>
<descr>
<p>
FilenamesLiteral is present when the <b>NotLiteralFilenames</b> compiler 
define exists.
</p>
</descr>
<seealso/>
</element>

<element name="ComparePhysicalFilenames">
<short>
Compares file names after resolving symbolic links.
</short>
<descr>
<p>
<var>ComparePhysicalFilenames</var>, like <var>CompareFileNames</var>, is 
used to compare file name using the case-sensitivity enforced for file names 
on the platform.
</p>
<p>
Calls <var>GetPhysicalFilename</var> to ensure that values in 
<var>Filename1</var> and <var>Filename2</var> are resolved to the actual file 
names on the local file system. This is significant for UNIX-like platforms 
where the file name arguments may be symbolic links on the file system.
</p>
<p>
Calls CompareFileNames in <file>LazFileUtils</file> to perform the comparison 
and get the return value for the routine.
</p>
</descr>
<seealso>
<link id="#lazutils.LazFileUtils.CompareFileNames">CompareFileNames</link>
<link id="#lazutils.LazFileUtils.GetPhysicalFilename">GetPhysicalFilename</link>
</seealso>
</element>
<element name="ComparePhysicalFilenames.Result">
<short>
Relative sort order for the compared values.
</short>
</element>
<element name="ComparePhysicalFilenames.Filename1">
<short>
First file name resolved and used in the comparison.
</short>
</element>
<element name="ComparePhysicalFilenames.Filename2">
<short>
Second file name resolved and used in the comparison.
</short>
</element>

<element name="CompareFilenames">
<short>
Compares two file names to see whether they are equal.
</short>
<descr>
<p>
<var>CompareFileNames</var> is an <var>Integer</var> function used to compare 
the specified file names (and lengths).
</p>
<p>
The <var>Filename1</var> and <var>Filename2</var> arguments are 
<var>PChar</var> types with pointers to the first character in each of the 
compared file names.The <var>Len1</var> and <var>Len2</var> arguments contain 
the length (or number of characters) for the pointers. If a length value is 
omitted, it implies the corresponding file name argument is empty.
</p>
<p>
<var>ResolveLinks</var> indicates whether file system or symbolic links are 
resolved before comparing the file name arguments. When set to <b>True</b>, 
the ComparePhysicalFilenames routine is called to resolve the file system 
links to actual path and file names for the comparison. For platforms where 
<b>NotLiteralFilenames</b> is defined, the file names are copied to a 
temporary string before resolving the file names.
</p>
<p>
Otherwise, the CompareFileNames routine (in <file>LazFileUtils</file>) is 
used to compare the file names and to get the return value.
</p>
<p>
The return value is <b>0</b> (zero) when the file names contain (or resolve 
to) the same files on the local file system. It is set to the difference 
between the lengths in Len1 and Len2 when one of the arguments has been 
omitted. For platforms where NotLiteralFilenames is not defined, it contains 
the initial difference between the ordinal values in the file names. 
Otherwise, it is set to the value from CompareFilenames (in 
<file>LazFileUtils</file>) or ComparePhysicalFilenames.
</p>
</descr>
<seealso>
<link id="ComparePhysicalFilenames"/>
<link id="#lazutils.lazfileutils.CompareFilenames">CompareFilenames</link>
</seealso>
</element>
<element name="CompareFilenames.Result">
<short>
Returns zero (<b>0</b>) if files are equal, or when character values or file 
name lengths are not equal.
</short>
</element>
<element name="CompareFilenames.Filename1">
<short>
First filename.
</short>
</element>
<element name="CompareFilenames.Len1">
<short>
Length of first filename.
</short>
</element>
<element name="CompareFilenames.Filename2">
<short>
Second filename.
</short>
</element>
<element name="CompareFilenames.Len2">
<short>
Length of second filename.
</short>
</element>
<element name="CompareFilenames.ResolveLinks">
<short>
When <b>True</b>, file system links are searched to find the actual file(s) 
for the comparison.
</short>
</element>

<element name="ExtractShortPathNameUTF8">
<short>
Gets a short path name using the 8.3 notation from the UTF-8-encoded value.
</short>
<descr>
<p>
<var>ExtractShortPathNameUTF8</var> is a <var>String</var> function used to 
get a short path name from the UTF-8-encoded value in FileName. Short path 
names use the familiar 8.3 notation, where the file name contains a maximum 
of 8 characters, and the optional file extension has a maximum of 3 
characters.
</p>
<p>
ExtractShortPathNameUTF8 is similar to the <var>ExtractShortPathName</var> 
routine in the RTL <file>sysutils</file> unit, but accepts a String value in 
<var>FileName</var> and returns a String value in the result which uses UTF-8 
encoding.The RTL routine uses UnicodeString for both.
</p>
<p>
The WinCE platform does not support the concept of short file names; the 
return value is set to the value in FileName.
</p>
<p>
For Windows platforms after version 5, the <var>GetShortPathNameW</var> 
routine is called to get the shortened path name.The UTF-16 value is 
converted to UTF-8 for use in the return value.
</p>
<p>
For all other platforms, FileName is converted to the system encoding and the 
ExtractShortPathName routine in the RTL is used to shorten the path name. The 
value is converted to UTF-8 for use in the return value.
</p>
</descr>
<seealso>
<link id="#rtl.sysutils.ExtractShortPathName">ExtractShortPathName</link>
</seealso>
</element>
<element name="ExtractShortPathNameUTF8.FileName">
<short>
Path name examined in the routine.
</short>
</element>
<element name="ExtractShortPathNameUTF8.Result">
<short>
Path name using the familiar 8.3 notation.
</short>
</element>

<element name="DeleteDirectory">
<short>
Deletes the specified directory (or only its contents when 
<var>OnlyChildren</var> is <b>True</b>).
</short>
<descr>
<p>
Returns <b>True</b> when the specified entries are deleted on the local file 
system. Returns <b>False</b> when:
</p>
<ul>
<li>
DirectoryName is one of the relative path indicators like '.' or '..'
</li>
<li>DirectoryName is an empty string ('')</li>
<li>DirectoryName does not exist on the local file system</li>
<li>
The process does not have permissions needed to delete the directory or its 
content
</li>
</ul>
</descr>
</element>
<element name="DeleteDirectory.Result">
<short>
Returns <b>True</b> if the directory or its contents were correctly removed.
</short>
</element>
<element name="DeleteDirectory.DirectoryName">
<short>
The name of the directory for processing.
</short>
</element>
<element name="DeleteDirectory.OnlyChildren">
<short>
If <b>True</b>, only the contents ('children') of the directory are removed.
</short>
</element>

<element name="ProgramDirectory">
<short>
Gets the directory where the current program is located.
</short>
<descr>
<p>
<var>ProgramDirectory</var> is a <var>String</var> function which gets the 
path to the directory where the current program is located.
</p>
<p>
ProgramDirectory calls <var>ParamStrUTF8</var> to get the command line and 
arguments used to start the current process. If the initial argument (the 
executable name) does not include a path to the file, the <b>PATH</b> 
environment variable was used to locate and start the process. 
<var>SearchFileInPath</var> is called to search each of the directory paths 
included in the PATH environment variable.
</p>
<p>
ProgramDirectory calls <var>GetPhysicalFilename</var> to resolve a symbolic 
link in the path to the executable. <var>ExpandFileNameUTF8</var> is called 
to expand drive letters or relative path references in the return value.
</p>
<p>
The return value is an empty string if the executable was not located on 
local file system.
</p>
</descr>
<seealso>
<link id="SearchFileInPath"/>
<link id="#lazutils.lazutf8.ParamStrUTF8">ParamStrUTF8</link>
<link id="#lazutils.lazutf8.GetEnvironmentVariableUTF8">GetEnvironmentVariableUTF8</link>
<link id="#lazutils.lazfileutils.GetPhysicalFilename">GetPhysicalFilename</link>
<link id="#lazutils.lazfileutils.ExpandFileNameUTF8">ExpandFileNameUTF8</link>
</seealso>
</element>
<element name="ProgramDirectory.Result">
<short>
Path to the directory where the current program is located.
</short>
</element>

<element name="ProgramDirectoryWithBundle">
<short>
Gets the directory for the current executable without the macOS bundle 
post-fix.
</short>
<descr>
<p>
<var>ProgramDirectoryWithBundle</var> is a <var>String</var> function used to 
get the path to current executable on the macOS operating system. It calls 
ProgramDirectory to get the return value, and removes the bundle post-fix 
('.app/Contents/MacOS') from the return value. The return value is not 
changed if it does not contain the bundle post-fix.
</p>
</descr>
<seealso>
<link id="ProgramDirectory"/>
</seealso>
</element>
<element name="ProgramDirectoryWithBundle.Result">
<short>
Path to the executable without the macOS bundle post-fix.
</short>
</element>

<element name="ExpandUNCFileNameUTF8">
<short>
Expands the specified UTF-8-encoded UNC file name to an absolute UNC file 
name.
</short>
<descr>
<p>
<var>ExpandUNCFileNameUTF8</var> is a <var>String</var> function used to 
expand the UNC file name in the <var>FileName</var> argument to an absolute 
UNC file name. It is the UTF-8-enabled equivalent of the ExpandUNCFileName 
routine from the FPC RTL.
</p>
<p>
ExpandUNCFileNameUTF8 calls the ExpandUNCFileName routine in RTL to get the 
return value for the method. Drive letters which are mapped to shared disks 
are replaced with the UNC device name for the mapped drive. The return value 
is an empty string ('') if an error occurs in ExpandUNCFileName.
</p>
</descr>
<seealso>
<link id="#rtl.sysutils.ExpandUNCFileName">ExpandUNCFileName</link>
<link id="#rtl.sysutils.ExpandFileName">ExpandFileName</link>
</seealso>
</element>
<element name="ExpandUNCFileNameUTF8.FileName">
<short>
File name expanded in the routine.
</short>
</element>
<element name="ExpandUNCFileNameUTF8.Result">
<short>
The expanded file name.
</short>
</element>

<element name="FileSize">
<short>
Gets the size for the specified file name.
</short>
<descr>
<p>
<var>FileSize</var> is an overloaded <var>Int64</var> function used to get 
the size for the file specified in the <var>FileName</var> parameter. 
FileSize is similar to the FileSize routine in the FPC RTL, but accepts a 
file name instead of a FileRec argument.
</p>
<p>
FileSize calls <var>FileSizeUtf8</var> to get the return value for the 
function.
</p>
</descr>
<seealso>
<link id="#lazutils.lazfileutils.FileSizeUtf8">FileSizeUtf8</link>
<link id="#rtl.system.FileSize">FileSize</link>
</seealso>
</element>
<element name="FileSize.Result">
<short>
Returns the size of the file, or -1 if the file does not exist.
</short>
</element>
<element name="FileSize.Filename">
<short>
The name of the file examined in the routine.
</short>
</element>

<element name="FilenameHasPascalExt">
<short>
Indicates whether the specified file name uses a recognized Pascal file 
extension.
</short>
<descr>
<p>
<var>FilenameHasPascalExt</var> is a <var>Boolean</var> function used to 
determine if the file name in the <var>Filename</var> argument uses a file 
extension recognized as a Pascal source code file. The <var>CompareText</var> 
routine is called to perform a case-insensitive comparison between the value 
in Filename and the recognized file extensions.
</p>
<p>
The return value is <b>True</b> when Filename has one of the following file 
extensions:
</p>
<ul>
<li>.pas</li>
<li>.pp</li>
<li>.p</li>
</ul>
<p>
The return value is <b>False</b> if Filename does not have a file extension, 
or the extension does not match the preceding values.
</p>
</descr>
<seealso/>
</element>
<element name="FilenameHasPascalExt.Result">
<short>
<b>True</b> when the file name uses a recognized Pascal file extension.
</short>
</element>
<element name="FilenameHasPascalExt.Filename">
<short>
File name examined in the routine.
</short>
</element>

<element name="FileIsInPath">
<short>
Checks whether the specified file name shares the path specified in Path.
</short>
<descr>
<p>
<var>FileIsInPath</var> is a Boolean function used to determine whether the 
file in <var>FileName</var> is located in the specified <var>Path</var>. 
FileIsInPath calls the CleanAndExpandFilename and CleanAndExpandDirectory 
routines to resolve drive letters or relative path information included in 
the arguments.
</p>
<p>
The return value is <b>True</b> when the resolved paths for the arguments 
contain the same values. FileIsInPath does <b>not</b> verify whether Path or 
FileName actually exist on the local file system. It compares the specified 
string values only.
</p>
<p>
Use DirectoryExists or DirectoryExistsUTF8 to determine whether a path exists 
on the local file system.
</p>
<p>
Use FileExists or FileExistsUTF8 to determine whether a file exists on the 
local file system.
</p>
<p>
<b>Example:</b>
</p>
<code>
// uses FileUtil;
// ...
// var
//   sDir, sFile: String;
//   bResult: Boolean;
// ...
// neither the file nor the directory exist on the file system
sDir := 'q:\bogus\path\';
sFile := 'q:\bogus\path\..\path\filename.ext';
bResult := FileIsInPath(sFile, sDir);

ShowMessage('File: ' + sFile + LineEnding +
  'is in Path: ' + sDir + '?' + LineEnding +
  'FileIsInPath() result is: ' + bResult.ToString(TUseBoolStrs.True) + '.');
</code>
</descr>
<seealso>
<link id="FileIsInDirectory"/>
<link id="#lazutils.lazfileutils.CleanAndExpandFilename">CleanAndExpandFilename</link>
<link id="#lazutils.lazfileutils.CleanAndExpandDirectory">CleanAndExpandDirectory</link>
<link id="#lazutils.lazfileutils.CompareFileNames">CompareFileNames</link>
</seealso>
</element>
<element name="FileIsInPath.Result">
<short>
Returns <b>True</b> the arguments share the same path information.
</short>
</element>
<element name="FileIsInPath.Filename">
<short>
The name of the file examined in the routine.
</short>
</element>
<element name="FileIsInPath.Path">
<short>
The path name examined in the routine.
</short>
</element>

<element name="FileIsInDirectory">
<short>
Checks whether the specified file name shares the path specified in Directory.
</short>
<descr>
<p>
<var>FileIsInDirectory</var> is a Boolean function used to determine whether 
the file in <var>FileName</var> is located in <var>Directory</var>. 
FileIsInDirectory calls the CleanAndExpandFilename and 
CleanAndExpandDirectory routines to resolve drive letters or relative path 
information included in the arguments.
</p>
<p>
The return value is <b>True</b> when the resolved paths for the arguments 
contain the same values. FileIsInDirectory does <b>not</b> verify whether 
Directory or FileName actually exist on the local file system. It compares 
the specified string values only.
</p>
<p>
Use DirectoryExists or DirectoryExistsUTF8 to determine whether a path exists 
on the local file system.
</p>
<p>
Use FileExists or FileExistsUTF8 to determine whether a file exists on the 
local file system.
</p>
<p>
<b>Example:</b>
</p>
<code>
// uses FileUtil;
// ...
// var
//   sDir, sFile: String;
//   bResult: Boolean;
// ...
// neither the file nor the directory exist on the file system
sDir := 'q:\bogus\path\';
sFile := 'q:\bogus\path\..\path\filename.ext';
bResult := FileIsInDirectory(sFile, sDir);

ShowMessage('File: ' + sFile + LineEnding +
  'is in Directory: ' + sDir + '?' + LineEnding +
  'FileIsInDirectory() result is: ' + bResult.ToString(TUseBoolStrs.True) + '.');
</code>
</descr>
<seealso>
<link id="FileIsInPath"/>
<link id="#lazutils.lazfileutils.CleanAndExpandFilename">CleanAndExpandFilename</link>
<link id="#lazutils.lazfileutils.CleanAndExpandDirectory">CleanAndExpandDirectory</link>
<link id="#lazutils.lazfileutils.CompareFileNames">CompareFileNames</link>
</seealso>
</element>
<element name="FileIsInDirectory.Result">
<short>
Returns <b>True</b> if the file and directory share the same paths.
</short>
</element>
<element name="FileIsInDirectory.Filename">
<short>
The name of the file to be checked.
</short>
</element>
<element name="FileIsInDirectory.Directory">
<short>
The name of the directory compared to the file name.
</short>
</element>

<element name="GetAllFilesMask">
<short>
Gets the file mask representing all files in a file filter.
</short>
<descr>
<p>
GetAllFilesMask returns a File Mask suitable for showing in a filter for a 
Open File Dialog. For Windows, '*.*' is returned; on other operating systems 
'*' is used.
</p>
</descr>
<seealso/>
</element>
<element name="GetAllFilesMask.Result">
<short>
The All Files mask for the platform.
</short>
</element>

<element name="GetExeExt">
<short>
Returns the file extension (including the starting .) for an executable file 
on the platform.
</short>
</element>
<element name="GetExeExt.Result">
<short>
Returns '.exe' on Windows, or an empty string for other platforms.
</short>
</element>

<element name="ReadFileToString">
<short>
Returns a string with the contents of the named text file.
</short>
<descr>
<p>
<var>ReadFileToString</var> opens the file specified in the <var>FileName</var> 
argument, then reads its contents into the <var>Result</var> string.
</p>
<p>
<var>FileName</var> can include a path to the file, but cannot include a value 
which needs to be resolved (like '~' for the home directory on UNIX-like file 
systems). Relative path notation can be used in FileName.
</p>
<p>
ReadFileToString does not check whether FileName contains an expanded value or 
whether it exists on the local file system. It does not complain if the file 
does not exist or cannot be accessed; the return value is an empty string ('') 
for these conditions. ExpandFileName() or ExpandFileNameUTF8() can be used to 
resolve a path with '~' notation. FileExists() or FileExistsUTF8() can be used 
to verify whether the file path/name exists before ReadFileToString is called.
</p>
<p>
FileSize is used to determine the storage size needed for the return value. 
UNIX-like file systems usually return 0 as the file size if FileName is located 
on a virtual file system (like /proc). In this case, the return value is an 
empty string. Another mechanism (like TStringList.LoadfromFile) should be used 
for virtual files.
</p>
<p>
FileOpenUTF8 is called to get a shared handle used to read from (but not write 
to) the specified file name. If an invalid handle is returned, the routine 
quietly exits with an empty return value.
</p>
<p>
FileRead is called for the handle to read the number of bytes in the file size 
into the return value.
</p>
<p>
FileClose is called to close the handle for the file when the operation has 
been completed.
</p>
</descr>
<errors>
If an error occurs while reading from or closing the file handle, the Exception 
is handled in the routine and an empty string is returned.
</errors>
<seealso>
<link id="FileSize"/>
<link id="#lazutils.lazfileutils.FileOpenUTF8">FileOpenUTF8</link>
<link id="#lazutils.lazfileutils.FileExistsUTF8">FileExistsUTF8</link>
<link id="#lazutils.lazfileutils.ExpandFileNameUTF8">ExpandFileNameUTF8</link>
<link id="#rtl.sysutils.FileRead">FileRead</link>
<link id="#rtl.sysutils.FileClose">FileClose</link>
<link id="#rtl.sysutils.FileExists">FileExists</link>
<link id="#rtl.sysutils.feInvalidHandle">feInvalidHandle</link>
</seealso>
</element>
<element name="ReadFileToString.Result">
<short>
The contents of the file as a string. Returns an empty string if there is an 
error, the file does not exist, or the file is empty.
</short>
</element>
<element name="ReadFileToString.Filename">
<short>
The qualified name for the file read in the routine.
</short>
</element>

<element name="TSearchFileInPathFlag">
<short>
Flags used to control options used when searching for file(s) in a given path.
</short>
<descr>
<p>
<var>TSearchFileInPathFlag</var> is an enumerated type with values that 
enable search options when locating files in a given path. Values in 
TSearchFileInPathFlag are stored in the <var>TSearchFileInPathFlags</var> set 
type and passed as an argument to the <var>SearchFileInPath</var> and 
<var>SearchAllFilesInPath</var> routines.
</p>
</descr>
<seealso>
<link id="TSearchFileInPathFlags"/>
<link id="SearchFileInPath"/>
<link id="SearchAllFilesInPath"/>
</seealso>
</element>
<element name="TSearchFileInPathFlag.sffDontSearchInBasePath">
<short>
Do not search in BasePath, search only in SearchPath.
</short>
</element>
<element name="TSearchFileInPathFlag.sffSearchLoUpCase">
<short>
Performs a case-insensitive search for file or directory names.
</short>
</element>
<element name="TSearchFileInPathFlag.sffFile">
<short>
Must be a file, and not a directory.
</short>
</element>
<element name="TSearchFileInPathFlag.sffExecutable">
<short>
File must be an executable file for the platform.
</short>
</element>
<element name="TSearchFileInPathFlag.sffDequoteSearchPath">
<short>
Removes ANSI Quotation Marks in a search path or file name.
</short>
</element>

<element name="TSearchFileInPathFlags">
<short>
Set type used to store values from the TSearchFileInPathFlag enumeration.
</short>
<descr>
<p>
<var>TSearchFileInPathFlags</var> is a <b>Set</b> type used to store zero (0) 
or more values from the <var>TSearchFileInPathFlag</var> enumeration. It is 
the type passed as an argument to the <var>SearchFileInPath</var> and 
<var>SearchAllFilesInPath</var> routines.
</p>
</descr>
<seealso>
<link id="TSearchFileInPathFlag"/>
<link id="SearchFileInPath"/>
<link id="SearchAllFilesInPath"/>
</seealso>
</element>

<element name="sffFindProgramInPath">
<short>
Search flags used to find a program file in a path on the current platform.
</short>
<descr>
<p>
<var>sffFindProgramInPath</var> is a constant which contains the default 
<var>TSearchFileInPathFlag</var> enumeration values used to locate a program 
file on the current platform.
</p>
<p>
For the Windows platform, sffFindProgramInPath contains the following values:
</p>
<code>[ sffDequoteSearchPath, sffFile, sffExecutable ]</code>
<p>
For UNIX-like platforms, sffFindProgramInPath contains the following values:
</p>
<code>[ sffDontSearchInBasePath, sffFile, sffExecutable ]</code>
<p>
For all other platforms, sffFindProgramInPath contains the following values:
</p>
<code>[ sffFile, sffExecutable ]</code>
<p>
sffFindProgramInPath is used in the implementation of the 
<var>FindDefaultExecutablePath</var> routine.
</p>
</descr>
<seealso>
<link id="FindDefaultExecutablePath"/>
</seealso>
</element>

<element name="SearchFileInPath">
<short>
Searches for a file name in a given path using the specified base path and 
options.
</short>
<descr>
<p>
<var>SearchFileInPath</var> is a <var>String</var> function used to get the 
fully-qualified name for the specified <var>FileName</var> in the specified 
search paths. When FileName contains an absolute path, and the file exists in 
the file system, no other directories are checked in the routine.
</p>
<p>
<var>SearchPath</var> contains the delimited list of search paths examined in 
the routine. Search paths are separated using the value in 
<var>Delimiter</var>.
</p>
<p>
<var>BasePath</var> contains the path used to resolve relative path 
references in SearchPath. By default, BasePath is also searched unless 
<var>sffDontSearchInBasePath</var> is included in the <var>Flags</var> 
parameter.
</p>
<p>
<var>Flags</var> contains values from the <var>TSearchFileInPathFlag</var> 
enumeration used to control the file matching logic used in the routine. For 
example:
</p>
<dl>
<dt>sffDontSearchInBasePath</dt>
<dd>Prevents searching in the directory represented by BasePath.</dd>
<dt>sffFile</dt>
<dd>Excludes a directory entry that matches the file name.</dd>
<dt>sffExecutable</dt>
<dd>Exclude any file or directory name that is not an executable.</dd>
</dl>
<p>
By default, the current directory is searched first. Each of the paths in 
SearchPaths are also searched until a file with the specified FileName is 
found.
</p>
<p>
The return value contains the fully-qualified path to the file including the 
file name and extension (when used). The first file that matches the supplied 
criteria is used in the return value. It may contain an empty string when a 
file with the given file name was not located.
</p>
</descr>
</element>
<element name="SearchFileInPath.Result">
<short>
Fully qualified file name for the file, or an empty string if the file was 
not found.
</short>
</element>
<element name="SearchFileInPath.Filename">
<short>
The name of the file to locate in the routine.
</short>
</element>
<element name="SearchFileInPath.BasePath">
<short>
Path used to resolve relative path references in a search path.
</short>
</element>
<element name="SearchFileInPath.SearchPath">
<short>
List of search paths examined in the routine.
</short>
</element>
<element name="SearchFileInPath.Delimiter">
<short>
Delimiter used to separate search paths.
</short>
</element>
<element name="SearchFileInPath.Flags">
<short>
Controls the file matching logic and behavior used in the routine.
</short>
</element>

<element name="SearchAllFilesInPath">
<short>
<var>SearchAllFilesInPath</var> - searches for all files named 
<var>Filename</var> in the given <var>SearchPath</var> using the supplied 
<var>BasePath</var> with the specified <var>Delimiter</var> and the options 
listed in <var>Flags</var>.
</short>
<descr>
<p>
<var>SearchAllFilesInPath</var> is a TStrings function used to get a list 
with all file names matching the value in <var>FileName</var>.
</p>
<p>
SearchAllFilesInPath creates the TStringList instance in the return value 
when needed. The return value can be <b>Nil</b> if no files or directories 
were found that match the FileName parameter.
</p>
<p>
Files or directories stored in the return value are fully-qualified path 
names, with relative path references resolved to the path in 
<var>BasePath</var>. If FileName contains an absolute path name, the return 
value has a single entry with the normalized value for FileName.
</p>
<p>
<var>SearchPath</var> contains one or more search paths examined in the 
routine. Each search path is separated by the value in <var>Delimiter</var>.
</p>
<p>
<var>Flags</var> is a set type which contains zero or more options enabled 
for the search. It can include values from the 
<var>TSearchFileInPathFlag</var> enumeration, including:
</p>
<dl>
<dt>sffDontSearchInBasePath</dt>
<dd>
Omits the directory in BasePath from the search process. Uses only the 
directories in SearchPath. When not used, matching files in BasePath are 
included in the search results.
</dd>
<dt>sffFile</dt>
<dd>
Matching entries must be a file and not a directory. Directory names which 
match FileName are ignored.
</dd>
<dt>sffExecutable</dt>
<dd>
Matching entries must be an executable file for the platform. Non-executable 
files are ignored.
</dd>
<dt>sffDequoteSearchPath</dt>
<dd>
Removes ANSI Quotation Marks found in the sanitized name for a matching file.
</dd>
</dl>
</descr>
<seealso>
<link id="TSearchFileInPathFlag"/>
<link id="TSearchFileInPathFlags"/>
<link id="#lazutils.lazfileutils.FilenameIsAbsolute">FilenameIsAbsolute</link>
<link id="#lazutils.lazfileutils.CleanAndExpandFilename">CleanAndExpandFilename</link>
<link id="#lazutils.lazfileutils.CleanAndExpandDirectory">CleanAndExpandDirectory</link>
<link id="#lazutils.lazfileutils.FileExistsUTF8">FileExistsUTF8</link>
<link id="#lazutils.lazfileutils.DirectoryExistsUTF8">DirectoryExistsUTF8</link>
</seealso>
</element>
<element name="SearchAllFilesInPath.Result">
<short>
Returns a fully qualified file name for all files that match the supplied 
criteria, or an empty string if the file is not found.
</short>
</element>
<element name="SearchAllFilesInPath.Filename">
<short>
The name of the file for searching.
</short>
</element>
<element name="SearchAllFilesInPath.BasePath">
<short>
The <var>BasePath</var> to be used for the search.
</short>
</element>
<element name="SearchAllFilesInPath.SearchPath">
<short>
The path for searching.
</short>
</element>
<element name="SearchAllFilesInPath.Delimiter">
<short>
The delimiter used between search paths.
</short>
</element>
<element name="SearchAllFilesInPath.Flags">
<short>
<var>Flags</var> specifying how to search: e.g. don't search in base path, 
case independent search.
</short>
</element>

<element name="FindDiskFilename">
<short>
Finds the file name that most closely matches the specified file name.
</short>
<descr>
<p>
<var>FindDiskFilename</var> is a String function used to get the file name 
which most closely matches the value in the <var>FileName</var> argument. It 
does not use case-sensitivity when comparing file names - regardless of the 
platform. In addition, the file must exist on the local file system.
</p>
<p>
FileName can include a fully-qualified path including a drive letter on 
Windows platforms. A drive letter in the value is always converted to 
uppercase. The path to the file is extracted and sanitized to resolve 
relative path references.
</p>
<p>
The file path is used to locate and compare all files in the directory by 
calling FindFirstUTF8 and FindNextUTF8. Each file entry is examined using 
CompareFilenamesIgnoreCase for a case-insensitive match for the specified 
file name. When a single match is found, its fully qualified path and file 
name are assigned as the return value. If more than one file is a match, the 
result is ambiguous and the resolved value for the original FileName argument 
is returned.
</p>
<remark>
The "All Files" mask for the platform is used to find the files in the path. 
This can be time consuming when a folder has a large number of files.
</remark>
<p>
<b>Example:</b>
</p>
<code>
// uses FileUtil;
// var AFileName, AResult: String;
// ...

// Windows
AFileName := 'c:\WINDOWS\WIN.INI';
AResult := FindDiskFileName(AFileName);
// AResult contains: 'C:\Windows\win.ini';

// UNIX-like platforms
AFileName := '/ETC/FONTS/FONTS.CONF';
AResult := FindDiskFileName(AFileName);
// AResult contains: '/etc/fonts/fonts.conf';
</code>
</descr>
<seealso>
<link id="FindFirstUTF8"/>
<link id="FindNextUTF8"/>
<link id="GetAllFilesMask"/>
<link id="#lazutils.lazfileutils.ResolveDots">ResolveDots</link>
<link id="#lazutils.lazfileutils.CompareFilenamesIgnoreCase">CompareFilenamesIgnoreCase</link>
</seealso>
</element>
<element name="FindDiskFilename.Result">
<short>
Resolved path and file name which is the case-insensitive match for the 
specified value.
</short>
</element>
<element name="FindDiskFilename.Filename">
<short>
The qualified path (optional) and file name to locate in the routine.
</short>
</element>

<element name="FindDiskFileCaseInsensitive">
<short>
<var>FindDiskFileCaseInsensitive</var> - searches for the given 
<var>FileName</var> in a case insensitive manner.
</short>
</element>
<element name="FindDiskFileCaseInsensitive.Result">
<short>
If it exists, returns the file name with path information otherwise returns 
an empty string.
</short>
</element>
<element name="FindDiskFileCaseInsensitive.Filename">
<short>
The name of the file for processing.
</short>
</element>

<element name="FindDefaultExecutablePath">
<short>
Finds the default path to the named Executable file.
</short>
<descr>
<p>
<var>FindDefaultExecutablePath</var> finds the default path to the named 
Executable file. On Windows systems, it looks for files both with and without 
the '.EXE' extension.
</p>
<p>
If Executable is not an absolute filename the executable is searched using 
the environment variable PATH. Relative directories in PATH are expanded 
using BaseDir.
</p>
<p>
On non-Unix systems (e.g. Windows), it searches in BaseDir as well. While on 
Unix systems (e.g. Linux, OS X) it only searches in BaseDir, if PATH contains 
the '.' directory.
</p>
</descr>
</element>
<element name="FindDefaultExecutablePath.Result">
<short>
Returns the filename of the Executable file with path information attached.
</short>
</element>
<element name="FindDefaultExecutablePath.Executable">
<short>
The name of the <var>Executable</var> file.
</short>
</element>

<element name="TFileIterator">
<short>
Implements an iterator for file and directory names on the local file system.
</short>
<descr>
<p>
<var>TFileIterator</var> is a class used to implement an iterator for file 
and directory names on the local file system. TFileIterator provides 
properties and methods used to represent the path and file name for values 
found when searching the local file system. It is not very useful on its own, 
but serves as the base class for the <var>TFileSearcher</var> ancestor.
</p>
<p>
TFileIterator is the type passed as an argument to 
<var>TFileFoundEvent</var>, <var>TDirectoryFoundEvent</var>, and 
<var>TDirectoryEnterEvent</var> event handlers.
</p>
</descr>
<seealso>
<link id="TFileSearcher"/>
<link id="TFileFoundEvent"/>
<link id="TDirectoryFoundEvent"/>
<link id="TDirectoryEnterEvent"/>
</seealso>
</element>

<element name="TFileIterator.FPath"/>
<element name="TFileIterator.FLevel"/>
<element name="TFileIterator.FFileInfo"/>
<element name="TFileIterator.FSearching"/>

<element name="TFileIterator.GetFileName">
<short>
Gets the value for the FileName property.
</short>
<descr/>
<seealso>
<link id="TFileIterator.FileName"/>
</seealso>
</element>
<element name="TFileIterator.GetFileName.Result">
<short>
Value for the property.
</short>
</element>

<element name="TFileIterator.Stop">
<short>
Stops the search process.
</short>
<descr>
<p>
Changes the value in <var>Searching</var> to <b>False</b>.
</p>
</descr>
<seealso>
<link id="TFileIterator.Searching"/>
<link id="TFileSearcher.Search"/>
</seealso>
</element>

<element name="TFileIterator.IsDirectory">
<short><b>True</b> when the current file system entry is a directory.</short>
<descr>
<p>
<var>IsDirectory</var> is a <var>Boolean</var> function which indicates if 
the current file entry is a directory on the local file system. Checks the 
file attributes in <var>FileInfo</var> to determine if the 
<var>faDirectory</var> attribute is included for the file. Returns 
<b>True</b> when the attribute in included in the <var>TSearchRec</var> value.
</p>
</descr>
<seealso>
<link id="TFileIterator.FileInfo"/>
<link id="#rtl.sysutils.TSearchRec">TSearchRec</link>
<link id="#rtl.sysutils.faDirectory">faDirectory</link>
</seealso>
</element>
<element name="TFileIterator.IsDirectory.Result">
<short>
<b>True</b> if the current file entry is a directory.
</short>
</element>

<element name="TFileIterator.FileName">
<short>
The qualified file name for the current file entry.
</short>
<descr>
<p>
<var>FileName</var> is a read-only <var>String</var> property which contains 
the qualified file name for the current file entry. FileName includes the 
value in <var>Path</var> as a prefix and the file name indicated in 
<var>FileInfo</var>.
</p>
</descr>
<seealso>
<link id="TFileIterator.Path"/>
<link id="TFileIterator.FileInfo"/>
</seealso>
</element>

<element name="TFileIterator.FileInfo">
<short>
Contains file information for the current entry in the iterator.
</short>
<descr>
<p>
<var>FileInfo</var> is a read-only <var>TSearchRec</var> property with the 
file information for the current entry in the iterator. FileInfo is used in 
the IsDirectory method to determine the faDirectory file attribute exists in 
the file information. Values in the <var>Path</var>, <var>FileName</var>, and 
FileInfo properties are updated in descendent classes which perform the 
search operation.
</p>
</descr>
<seealso>
<link id="TFileIterator.IsDirectory"/>
<link id="TFileIterator.FileName"/>
<link id="TFileIterator.Path"/>
<link id="TFileSearcher.Search"/>
</seealso>
</element>

<element name="TFileIterator.Level">
<short>
Gets the current directory level relative to the base search path.
</short>
<descr>
<p>
<var>Level</var> is a read-only <var>Integer</var> property which contains 
the directory level for the current entry in the <var>FileInfo</var> 
property. The level indicates the number of sub-directories relative to the 
the base search path. The value in Level is maintained in descendent classes 
that perform a search operation using the iterator.
</p>
</descr>
<seealso>
<link id="TFileIterator.FileInfo"/>
<link id="TFileIterator.IsDirectory"/>
<link id="TFileSearcher.Search"/>
</seealso>
</element>

<element name="TFileIterator.Path">
<short>
Contains the path to the current file or directory in the iterator.
</short>
<descr>
<p>
<var>Path</var> is a read-only <var>String</var> property which contains the 
fully-qualified path to the current file or directory in the 
<var>FileInfo</var> property. Values in the Path, <var>FileName</var>, and 
FileInfo properties are updated in descendent classes which perform the 
search operation.
</p>
</descr>
<seealso>
<link id="TFileIterator.FileInfo"/>
<link id="TFileIterator.FileName"/>
<link id="TFileSearcher.Search"/>
</seealso>
</element>

<element name="TFileIterator.Searching">
<short>
Indicates if a search process is active.
</short>
<descr>
<p>
<var>Searching</var> is a read-only <var>Boolean</var> property which 
indicates if a search process is active for the iterator. The property value 
is updated in descendent classes which perform the search operation.
</p>
<p>
Searching is set to <b>False</b> when the <var>Stop</var> method is called.
</p>
</descr>
<seealso>
<link id="TFileIterator.Stop"/>
<link id="TFileSearcher.Search"/>
</seealso>
</element>

<element name="TFileFoundEvent">
<short>
Specifies an event handler signalled when a file name is found for the 
specified iterator.
</short>
<descr>
<p>
<var>TFileFoundEvent</var> is an object procedure type which specifies an 
event handler signalled when a file name is found using the specified 
iterator. <var>FileIterator</var> contains the <var>TFileIterator</var> 
instance for the event notification.
</p>
<p>
TFileFoundEvent is the type used to implement the 
<var>TFileSearcher.OnFileFound</var> event handler. Applications can 
implement a procedure using the event signature to perform actions needed to 
process the file in a FileIterator.
</p>
</descr>
<seealso>
<link id="TFileSearcher.Search"/>
<link id="TFileSearcher.OnFileFound"/>
</seealso>
</element>
<element name="TFileFoundEvent.FileIterator">
<short>
File iterator with the file information for the event.
</short>
</element>

<element name="TDirectoryFoundEvent">
<short>
Specifies an event handler signalled when a directory is found for the 
specified iterator.
</short>
<descr>
<p>
<var>TDirectoryFoundEvent</var> is an object procedure type which specifies 
an event handler signalled when a directory is located for the iterator in 
<var>FileIterator</var>.
</p>
<p>
TDirectoryFoundEvent is the type used to implement the 
<var>TFileSearcher.OnDirectoryFound</var> event handler. Applications can 
implement a procedure using the event signature to perform actions needed to 
process the directory in a FileIterator.
</p>
</descr>
<seealso/>
</element>
<element name="TDirectoryFoundEvent.FileIterator">
<short>
File iterator with the directory information for the event.
</short>
</element>

<element name="TDirectoryEnterEvent">
<short>
Specifies an event handler signalled when a new directory is processed with 
the specified iterator.
</short>
<descr>
<p>
<var>TDirectoryEnterEvent</var> is an object procedure type which specifies 
an event handler signalled when a new directory is processed for the iterator 
in <var>FileIterator</var>.
</p>
<p>
TDirectoryEnterEvent is the type used to implement the 
<var>TFileSearcher.OnDirectoryEnter</var> event handler. Applications can 
implement a procedure using the event signature to perform actions needed to 
process the directory in a FileIterator.
</p>
</descr>
<seealso/>
</element>
<element name="TDirectoryEnterEvent.FileIterator">
<short>
File iterator with the directory information for the event.
</short>
</element>

<element name="TFileSearcher">
<short>
Implements an iterator used to search for files or directories.
</short>
<descr>
<p>
<var>TFileSearcher</var> is a <var>TFileIterator</var> descendant used to 
search for files or directories that match a search mask in a given directory 
path. TFileSearcher extends the ancestor class with additional properties, 
methods, and events needed to search and process files or directories on the 
local file system.
</p>
<p>
It implements the <var>Search</var> method to perform a search using the 
specified path(s) and file mask(s).
</p>
<p>
Use <var>MaskSeparator</var> to specify the delimiter used to separate a list 
of mask values passed to the method. Use <var>PathSeparator</var> to specify 
the delimiter used to separate a list of file paths passed to the method.
</p>
<p>
Use <var>FileAttribute</var> and <var>DirectoryAttribute</var> to specify the 
file system attributes needed for files or directories considered a match in 
the Search method. Use <var>FollowSymLink</var> to indicate whether symbolic 
links on the file system are followed in the Search method.
</p>
<p>
Use the <var>OnFileFound</var>, <var>OnDirectoryFound</var>, and 
<var>OnDirectoryEnter</var> event handlers to perform the actions needed for 
files or directories found using the Search method.
</p>
<p>
TFileSearcher is the ancestor class for more specialized descendants like 
<var>TListFileSearcher</var> and <var>TListDirectoriesSearcher</var>.
</p>
</descr>
<seealso>
<link id="TFileIterator"/>
<link id="TListFileSearcher"/>
<link id="TListDirectoriesSearcher"/>
</seealso>
</element>

<element name="TFileSearcher.FMaskSeparator"/>
<element name="TFileSearcher.FPathSeparator"/>
<element name="TFileSearcher.FFollowSymLink"/>
<element name="TFileSearcher.FOnFileFound"/>
<element name="TFileSearcher.FOnDirectoryFound"/>
<element name="TFileSearcher.FOnDirectoryEnter"/>
<element name="TFileSearcher.FFileAttribute"/>
<element name="TFileSearcher.FDirectoryAttribute"/>

<element name="TFileSearcher.RaiseSearchingError">
<short>
Raises an Exception if Search is called when Searching is already set to 
<b>True</b>.
</short>
</element>

<element name="TFileSearcher.DoDirectoryEnter">
<short>
Signals the OnDirectoryEnter event handler (when assigned).
</short>
</element>

<element name="TFileSearcher.DoDirectoryFound">
<short>
Signals the OnDirectoryFound event handler (when assigned).
</short>
</element>

<element name="TFileSearcher.DoFileFound">
<short>
Signals the OnFileFound event handler (when assigned).
</short>
</element>

<element name="TFileSearcher.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
<var>Create</var> is the overridden constructor for the class instance, and 
calls the inherited constructor on entry. Create sets the default values used 
in the following properties:
</p>
<dl>
<dt>MaskSeparator</dt>
<dd>Set to ';'.</dd>
<dt>PathSeparator</dt>
<dd>Set to ';'.</dd>
<dt>FollowSymLink</dt>
<dd>Set to <b>True</b>.</dd>
<dt>FileAttribute</dt>
<dd>Set to faAnyFile.</dd>
<dt>DirectoryAttribute</dt>
<dd>Set to faDirectory.</dd>
<dt>Searching</dt>
<dd>Set to <b>False</b>.</dd>
</dl>
</descr>
<seealso/>
</element>

<element name="TFileSearcher.Search">
<short>
Searches for files or directories in the specified path(s) using the 
specified options.
</short>
<descr>
<p>
<var>Search</var> is a method used to search for files or directories matching 
the specified file masks found in the specified search paths.
</p>
<p>
<var>ASearchPath</var> contains one or more paths examined in the method, and 
can contain multiple path names separated by the value in 
<var>PathSeparator</var>. Each delimited path value in ASearchPath is resolved 
by calling the <var>ResolveDots</var> function, and processed in the method. 
For example:
</p>
<code>
'c:\path\to\dir;c:\path\to\another\dir'
'/home/user/path/to/dir;/home/user/path/to/another/dir'
</code>
<p>
Please note that leading or trailing white space in a search path is treated as 
part of the path specification. It is not trimmed, and will most likely prevent 
a match for the path value.
</p>
<p>
<var>ASearchMask</var> contains one or more file masks which determine the 
matching files in the method. It may contain multiple file masks separated by 
the value in the <var>MaskSeparator</var> property. For example:
</p>
<code>
'*.pas;*.pp;*.lpr'
</code>
<p>
Please note that leading or trailing white space in a file mask is treated as 
part of the file specification. It is not trimmed, and will most likely prevent 
a match for the mask value.
</p>
<p>
The value in the <var>CaseSensitive</var> argument is used to add or remove 
mask options for the search mask in ASearchMask. Set CaseSensitive to 
<b>True</b> before calling Search to perform file name comparisons with case 
sensitivity.
</p>
<p>
<var>ASearchSubDirs</var> includes subdirectories found in ASearchPath in the 
search process when set to <b>True</b>. When set to <b>False</b> only the 
specified paths are searched and their subdirectories are ignored.
</p>
<p>
Set the value in <var>FileAttribute</var> to control the file attributes 
included in the search process. The default value (<var>faAnyFile</var>) 
allows all files to be considered.
</p>
<p>
Set the value in <var>DirectoryAttribute</var> to control whether directory 
names are included in the search process. The default value 
(<var>faDirectory</var>) includes directory names.
</p>
<p>
Set the value in <var>FollowSymLink</var> to indicate whether symbolic links 
in the file system are followed in the method.
</p>
<p>
When a matching file is found, the OnFileFound event is signalled. For 
directories, the OnDirectoryFound event is signalled. When a new directory is 
processed in the method, the OnDirectoryEnter events is signalled. 
Applications must assign a handler for the events to respond to the 
notifications. You can abort the search process by calling the Stop method in 
the handlers for these events.
</p>
</descr>
<errors>
<p>
Calls RaiseSearchingError to raise an exception if the Search method has 
already been called and has not completed.
</p>
</errors>
<seealso>
<link id="TFileSearcher.OnFileFound"/>
<link id="TFileSearcher.OnDirectoryFound"/>
<link id="TFileSearcher.OnDirectoryEnter"/>
<link id="TFileSearcher.FileAttribute"/>
<link id="TFileSearcher.DirectoryAttribute"/>
<link id="TFileSearcher.FollowSymLink"/>
<link id="TFileSearcher.PathSeparator"/>
<link id="TFileSearcher.MaskSeparator"/>
<link id="TFileIterator.Stop"/>
</seealso>
</element>
<element name="TFileSearcher.Search.ASearchPath">
<short>
One or more paths used to search for files.
</short>
</element>
<element name="TFileSearcher.Search.ASearchMask">
<short>
One or more masks used to determine file names that match in the search.
</short>
</element>
<element name="TFileSearcher.Search.ASearchSubDirs">
<short>
Indicates if subdirectories are searched recursively.
</short>
</element>
<element name="TFileSearcher.Search.CaseSensitive">
<short>
Indicates if file names are compared using case sensitivity.
</short>
</element>

<element name="TFileSearcher.MaskSeparator">
<short>
Character used as a delimiter between file masks.
</short>
<descr>
<p>
<var>MaskSeparator</var> is a <var>Char</var> property which contains the 
character used as a delimiter between file masks in the search criteria. The 
default value for the property is '<b>;</b>' as assigned in the 
<var>Create</var> method.
</p>
<p>
MaskSeparator is used in<var>Search</var> to fill an internal 
<var>TMaskList</var> instance used in the method.
</p>
</descr>
<seealso>
<link id="TFileSearcher.PathSeparator"/>
<link id="TFileSearcher.Search"/>
<link id="TFileSearcher.Create"/>
<link id="#lazutils.masks.TMaskList">TMaskList</link>
</seealso>
</element>

<element name="TFileSearcher.PathSeparator">
<short>
Character used as a delimiter between directory paths.
</short>
<descr>
<p>
<var>PathSeparator</var> is a <var>Char</var> property which contains the 
character used as a delimiter between directory paths in the search criteria. 
The default value for the property is '<b>;</b>' as assigned in the 
<var>Create</var> method.
</p>
<p>
PathSeparator is used in the <var>Search</var> method to fill an internal 
<var>TStringList</var> instance with the directory paths specified in the 
search criteria.
</p>
</descr>
<seealso>
<link id="TFileSearcher.MaskSeparator"/>
<link id="TFileSearcher.Search"/>
<link id="TFileSearcher.Create"/>
</seealso>
</element>

<element name="TFileSearcher.FollowSymLink">
<short>
Indicates if a search process directory paths that are symbolic links.
</short>
<descr>
<p>
<var>FollowSymLink</var> is a <var>Boolean</var> property which indicates if 
the <var>Search</var> method should process directory paths that are symbolic 
links on the local file system. The default value for the property is 
<b>True</b> as assigned in the <var>Create</var> method.
</p>
<p>
FollowSymLink is used in the Search method when a directory entry is detected 
in <var>FileInfo</var> that <var>FileIsSymLink</var> identifies as a symbolic 
link. When set to <b>False</b>, the directory is <b>not</b> processed; the 
<var>OnDirectoryEnter</var> event handler is <b>not</b> signalled and the 
method ignores the directory path. The <var>OnDirectoryFound</var> event 
handler is signalled for the iterator value.
</p>
</descr>
<seealso>
<link id="TFileSearcher.Create"/>
<link id="TFileSearcher.OnDirectoryFound"/>
<link id="TFileIterator.FileInfo"/>
<link id="TFileIterator.IsDirectory"/>
<link id="#lazutils.lazfileutils.FileIsSymLink">FileIsSymLink</link>
</seealso>
</element>

<element name="TFileSearcher.FileAttribute">
<short>
File attribute needed for any file considered a match in the Search method.
</short>
<descr>
<p>
<var>FileAttribute</var> is a <var>Word</var> property. The default value for 
the property is <var>faAnyfile</var>, and means that any of the file 
attribute constants are allowed for files.
</p>
<p>
FileAttribute is used in the <var>Search</var> method to determine whether a 
file in a given search path can be considered a match based on its file 
attributes. The value is passed as an argument to <var>FindFirstUTF8</var> 
and <var>FindNextUTF8</var>. The value is compared to the file attributes 
returned in a <var>TSearchRec</var> instance from those routines.
</p>
<p>
Use <var>DirectoryAttribute</var> to specify the file attributes needed for 
directories processed in the Search method.
</p>
</descr>
<seealso>
<link id="TFileSearcher.Search"/>
<link id="TFileSearcher.DirectoryAttribute"/>
<link id="TFileIterator.FileInfo"/>
<link id="#lazutils.lazfileutils.FindFirstUTF8">FindFirstUTF8</link>
<link id="#lazutils.lazfileutils.FindNextUTF8">FindNextUTF8</link>
<link id="#rtl.sysutils.TSearchRec">TSearchRec</link>
</seealso>
</element>

<element name="TFileSearcher.DirectoryAttribute">
<short>
File attribute needed for directories considered a match in the Search method.
</short>
<descr>
<p>
<var>DirectoryAttribute</var> is a <var>Word</var> property with the file 
attribute needed for directories considered a match in the Search method. The 
default value for the property is <var>faDirectory</var>.
</p>
<p>
DirectoryAttribute is used in the <var>Search</var> method to determine 
whether a file system entry in a given search path can be considered a match 
based on its file attributes. The value is passed as an argument to 
<var>FindFirstUTF8</var> and <var>FindNextUTF8</var>. The value is compared 
to the file attributes returned in a <var>TSearchRec</var> instance from 
those routines.
</p>
<p>
Use <var>FollowSymLink</var> to include or exclude directories which are 
symbolic links on the local file system.
</p>
<p>
Use <var>FileAttribute</var> to set the file attributes needed for files 
considered a match in the Search method.
</p>
</descr>
<seealso>
<link id="TFileSearcher.Search"/>
<link id="TFileSearcher.FileAttribute"/>
<link id="TFileIterator.FileInfo"/>
<link id="#lazutils.lazfileutils.FindFirstUTF8">FindFirstUTF8</link>
<link id="#lazutils.lazfileutils.FindNextUTF8">FindNextUTF8</link>
<link id="#rtl.sysutils.TSearchRec">TSearchRec</link>
</seealso>
</element>

<element name="TFileSearcher.OnDirectoryFound">
<short>
Event handler signalled when a new directory is found in the Search method.
</short>
<descr>
<p>
<var>OnDirectoryFound</var> is a <var>TDirectoryFoundEvent</var> property 
with the event handler signalled when a new directory is found in the Search 
method. It is signalled after values in the <var>Path</var>, 
<var>FileInfo</var>, and <var>Level</var> properties have been updated in the 
file iterator.
</p>
<p>
An application must implement and assign an object procedure to the handler 
to respond to the event notification. The <var>FileIterator</var> argument is 
the <var>TFileIterator</var> instance for the event notification, and allows 
access to its properties and methods. Call the <var>Stop</var> method in 
FileIterator to stop the search process.
</p>
<p>
Use <var>OnDirectoryEnter</var> to perform actions needed when a new 
directory is processed in the search method.
</p>
</descr>
<seealso>
<link id="TFileSearcher.Search"/>
<link id="TFileSearcher.DirectoryAttribute"/>
<link id="TFileSearcher.OnDirectoryEnter"/>
<link id="TFileIterator"/>
<link id="TFileIterator.Path"/>
<link id="TFileIterator.FileInfo"/>
<link id="TFileIterator.Level"/>
<link id="TDirectoryFoundEvent"/>
</seealso>
</element>

<element name="TFileSearcher.OnFileFound">
<short>
Event handler signalled when a file matching the file mask is found in the 
Search method.
</short>
<descr>
<p>
<var>OnFileFound</var> is a <var>TFileFoundEvent</var> property with the 
event handler signalled when a file matching the search criteria is found in 
the Search method. It is signalled for each file that matches the search path 
and file mask arguments passed to the method. The event occurs after values 
in the <var>Path</var>, <var>FileInfo</var>, and <var>Level</var> properties 
have been updated in the file iterator.
</p>
<p>
An application must implement and assign an object procedure to the handler 
to respond to the event notification. The <var>FileIterator</var> argument is 
the <var>TFileIterator</var> instance for the event notification, and allows 
access to its properties and methods. Call the <var>Stop</var> method in 
FileIterator to stop the search process.
</p>
<p>
Use <var>OnDirectoryFound</var> to respond to directory names found in the 
Search method.
</p>
<p>
Use <var>OnDirectoryEnter</var> to respond to a new directory processed in 
the Search method.
</p>
</descr>
<seealso>
<link id="TFileSearcher.Search"/>
<link id="TFileSearcher.DirectoryAttribute"/>
<link id="TFileSearcher.OnDirectoryFound"/>
<link id="TFileSearcher.OnDirectoryEnter"/>
<link id="TFileIterator"/>
<link id="TFileIterator.Path"/>
<link id="TFileIterator.FileInfo"/>
<link id="TFileIterator.Level"/>
<link id="TFileFoundEvent"/>
</seealso>
</element>

<element name="TFileSearcher.OnDirectoryEnter">
<short>
Event handler signalled when a new directory is processed in the Search 
method.
</short>
<descr>
<p>
<var>OnDirectoryEnter</var> is a <var>TDirectoryEnterEvent</var> property 
with the event handler signalled when a new directory is processed in the 
<var>Search</var> method. It is signalled after the new directory name has 
been stored in Path, FileInfo, and Level in the file iterator. It occurs 
immediately before the search in the directory path is performed.
</p>
<p>
An application must implement and assign an object procedure to the handler 
to respond to the event notification. The <var>FileIterator</var> argument is 
the <var>TFileIterator</var> instance for the event notification, and allows 
access to its properties and methods. Call the <var>Stop</var> method in 
FileIterator to stop the search process.
</p>
<p>
Use <var>OnDirectoryFound</var> to respond to directory names found in the 
Search method.
</p>
<p>
Use <var>OnFileFound</var> to respond to a new file name processed as a match 
in the Search method.
</p>
</descr>
<seealso>
<link id="TFileSearcher.Search"/>
<link id="TFileSearcher.DirectoryAttribute"/>
<link id="TFileSearcher.OnDirectoryFound"/>
<link id="TFileSearcher.OnFileFound"/>
<link id="TFileIterator"/>
<link id="TFileIterator.Path"/>
<link id="TFileIterator.FileInfo"/>
<link id="TFileIterator.Level"/>
<link id="TDirectoryEnterEvent"/>
</seealso>
</element>

<element name="TListFileSearcher">
<short>
Stores file names matching a search criteria in a TStrings class instance.
</short>
<descr>
<p>
<var>TListFileSearcher</var> is a <var>TFileSearcher</var> descendant used to 
used store file names matching a specified search criteria in a 
<var>TStrings</var> class instance. It provides an overridden methods used to 
add file names to the string list when a matching file name is found. An 
alternate constructor is provided to specify the TStrings instance used to 
store the file names found in the <var>Search</var> method.
</p>
<remark>
Resources allocated to the TStrings instance must be freed by the caller. 
TListFileSearcher does not own or manage the resources for the TStrings 
instance.
</remark>
</descr>
<seealso>
<link id="TFileSearcher"/>
</seealso>
</element>

<element name="TListFileSearcher.FList">
<short>
Internal list used to store matching file names in the file searcher.
</short>
</element>

<element name="TListFileSearcher.DoFileFound">
<short>
Performs actions required to add a file name to the list of matches for the 
file searcher.
</short>
<descr>
<p>
<var>DoFileFound</var> is an overridden method in 
<var>TListFileSearcher</var>. It adds the current value from the FileName 
property to the internal TStrings member maintained in the class instance. 
The inherited method is called prior to exit to signal the OnFileFound event 
handler (when assigned).
</p>
<p>
DoFileFound is called from the Search method when a file on the local file 
system is located that matches a given mask.
</p>
</descr>
<seealso>
<link id="TFileIterator.FileName"/>
<link id="TFileSearcher.OnFileFound"/>
<link id="TFileSearcher.Search"/>
</seealso>
</element>

<element name="TListFileSearcher.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
<var>Create</var> is an alternate constructor for the class instance. Create 
calls the inherited constructor, and stores the <var>TStrings</var> instance 
in <var>AList</var> to the the internal member used in the class instance.
</p>
<remark>
Resources allocated to the TStrings instance must be freed by the caller. 
TListFileSearcher does not own or manage the resources for the TStrings 
instance.
</remark>
</descr>
<seealso/>
</element>
<element name="TListFileSearcher.Create.AList">
<short>
TStrings class instance used to store matching file names.
</short>
</element>

<element name="TListDirectoriesSearcher">
<short>
Stores directory names matching a given search criteria in a TStrings class 
instance.
</short>
<descr>
<p>
<var>TListDirectoriesSearcher</var> is a <var>TFileSearcher</var> descendant 
used to store directory names matching the specified search criteria in a 
TStrings class instance. It extends the ancestor class by implementing an 
internal member used to store the TStrings class instance.
</p>
<p>
Use the <var>PathSeparator</var> property to specify the separator used between 
path names passed as an argument to the <var>Search</var> method.
</p>
<p>
TListDirectoriesSearcher is used to implement the FindAllDirectories routine.
</p>
</descr>
<seealso>
<link id="TFileSearcher"/>
<link id="TFileSearcher.PathSeparator"/>
<link id="TFileSearcher.Search"/>
<link id="TListFileSearcher"/>
<link id="FindAllDirectories"/>
</seealso>
</element>

<element name="TListDirectoriesSearcher.FDirectoriesList">
<short>
Stores directory paths matching the specified search criteria.
</short>
</element>

<element name="TListDirectoriesSearcher.DoDirectoryFound">
<short>
Performs actions needed to add a directory path to the list of matches for 
the searcher.
</short>
<descr>
<p>
DoDirectoryFound is an overridden method in TListDirectoriesSearcher. It adds 
the current value from the FileName property to the internal TStrings member 
used in the class instance. The inherited method is called prior to exit to 
signal the OnDirectoryFound event handler (when assigned).
</p>
<p>
DoDirectoryFound is called from the Search method when a directory on the 
local file system is located that matches a given mask.
</p>
</descr>
<seealso>
<link id="TFileIterator.FileName"/>
<link id="TFileSearcher.OnDirectoryFound"/>
<link id="TFileSearcher.Search"/>
</seealso>
</element>

<element name="TListDirectoriesSearcher.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
<var>Create</var> is the constructor for the class instance. Create calls the 
inherited constructor, and stores the value in <var>AList</var> to the 
internal member used to capture matching directory names in the class 
instance.
</p>
<remark>
Resources allocated to the TStrings instance must be freed by the caller. 
TListFileSearcher does not own or manage the resources for the TStrings 
instance.
</remark>
</descr>
<seealso/>
</element>
<element name="TListDirectoriesSearcher.Create.AList">
<short>
TStrings class instance used to store directory names matching the specified 
search criteria.
</short>
<descr/>
<seealso/>
</element>

<element name="FindAllFiles">
<short>
Returns the list of files in the specified path matching the search criteria.
</short>
<descr>
<p>
<var>FindAllFiles</var> is a routine used to gather a list of file names found 
in the specified search paths which match the specified file masks. Overloaded 
variants are provided which allow the list of matching file names to be 
returned in different manners. 
</p>
<p>
The procedure variant uses an existing TStringList class instance to store the 
matching file names. The function variant creates a new TStringList instance 
which is used as the return value. It creates the string list internally. This 
may seem very convenient at first, but it is very easy to create memory leaks 
if string list instances are not freed properly.
</p>
<p>
FindAllFiles uses the <link id="TListFileSearcher">TListFileSearcher</link> 
class to perform the file search using the specified parameter values.
</p>
</descr>
<seealso>
<link id="TListFileSearcher"/>
</seealso>
<example file="examples/fileutil.findallfiles.pas"/>
</element>
<element name="FindAllFiles.Result">
<short>
TStringList instance with the file names matching the search criteria.
The StringList is created in the FindAllFiles function; you should not 
instantiate it before calling the function, and it must be freed in the calling 
routine.
</short>
</element>
<element name="FindAllFiles.AList">
<short>
TStringList used to store file names matching the search criteria. AList must 
be instantiated before it is passed as an argument to the method. The 
TStringList instance must also be freed by the routine where it was created.
</short>
</element>
<element name="FindAllFiles.SearchPath">
<short>
Base path for searching files.
</short>
</element>
<element name="FindAllFiles.SearchMask">
<short>
A list of file masks, separated by a semicolon (;), used to determine which 
files are a match in the routine. The mask can contain wildcards like * and ? 
and it also supports sets like [a-d,x]. See the Masks unit for more details. 
The default value is an empty string ('') and causes the all files mask for the 
platform to be used.
</short>
</element>
<element name="FindAllFiles.SearchSubDirs">
<short>
<b>True</b> to search for matching files in subdirectories. 
</short>
</element>
<element name="FindAllFiles.DirAttr">
<short>
Specifies the file attribute which indicates whether a file system entry is 
treated as a directory. It can contain <var>faDirectory</var>, 
<var>faSymLink</var>, (<var>faDirectory</var>+ <var>faSymLink</var>), or other 
bits can be used. The default value is faDirectory.
</short>
</element>
<element name="FindAllFiles.MaskSeparator">
<short>
Separator used between file masks in the SearchMask argument. Default value is 
';'.
</short>
</element>
<element name="FindAllFiles.PathSeparator">
<short>
Separator used between path names in the SearchPath argument. Default value is 
';'.
</short>
</element>

<element name="FindAllDirectories">
<short>
Stores directory names matching the search criteria in a TStringList class 
instance.
</short>
<descr>
<p>
<var>FindAllDirectories</var> is an overloaded routine used to store 
directory path names that match the specified search criteria in a 
<var>TStringList</var> class instance. The procedure variant uses an existing 
TStringList class instance to store the matching directory names. The 
function variant allocates a TStringList class instance used to capture the 
matching directory names.
</p>
</descr>
<seealso>
<link id="TListDirectoriesSearcher"/>
</seealso>
</element>
<element name="FindAllDirectories.Result">
<short>
Stores directory names matching the search criteria.
</short>
</element>
<element name="FindAllDirectories.AList">
<short>
Stores directory names matching the search criteria.
</short>
</element>
<element name="FindAllDirectories.SearchPath">
<short>
Path(s) to the directories examined in the routine.
</short>
</element>
<element name="FindAllDirectories.SearchSubDirs">
<short>
<b>True</b> to recurse into subdirectories in the search.
</short>
</element>
<element name="FindAllDirectories.PathSeparator">
<short>
Delimiter used between path names in the SearchPath parameter.
</short>
</element>

<element name="TCopyFileFlag">
<short>
Contains flags used to control actions performed in CopyFile or CopyDirTree.
</short>
<descr/>
<seealso>
<link id="TCopyFileFlags"/>
<link id="CopyFile"/>
<link id="CopyDirTree"/>
</seealso>
</element>
<element name="TCopyFileFlag.cffOverwriteFile">
<short>
Overwrites the destination file if it already exists.
</short>
</element>
<element name="TCopyFileFlag.cffCreateDestDirectory">
<short>
Create the directory for the destination fie if it does not already exist.
</short>
</element>
<element name="TCopyFileFlag.cffPreserveTime">
<short>
Preserves the timestamp for the source file in the destination file.
</short>
</element>

<element name="TCopyFileFlags">
<short>
Set type used to store TCopyFileFlag enumeration values.
</short>
<descr>
<p>
<var>TCopyFileFlags</var> is a set type used to store 0 or more values from 
the <var>TCopyFileFlag</var> enumeration. TCopyFileFlags is passed as an 
argument to the CopyFile and CopyDirTree routines.
</p>
</descr>
<seealso>
<link id="TCopyFileFlag"/>
<link id="CopyFile"/>
<link id="CopyDirTree"/>
</seealso>
</element>

<element name="CopyFile">
<short>
Copies the source file to the destination file using the specified options.
</short>
<descr>
<p>
<var>CopyFile</var> is an overloaded <var>Boolean</var> function used to copy 
the file in <var>SrcFilename</var> to the destination in 
<var>DestFilename</var>. Both parameters contain a fully-qualified path with 
file name and extension (if needed) for the respective files.
</p>
<p>
<var>Flags</var> contains <var>TCopyFileFlag</var> value(s) that are enforced 
in the copy operation. The default value for the parameter is 
<var>[cffOverwriteFile]</var> and indicates that the destination file is 
overwritten if it already exists on the local file system.
</p>
<p>
<var>PreserveTime</var> indicates if the timestamp for the source file is 
preserved in the destination file when the copy operation has been completed. 
It is an alternative to using the Flags arguments in the overloaded variant.
</p>
<p>
The return value is set to <b>True</b> when the copy operation has been 
completed successfully. Otherwise, the return value is <b>False</b>.
</p>
</descr>
<errors>
An Exception is raised if the copy process does not complete successfully or 
correctly.
</errors>
</element>
<element name="CopyFile.Result">
<short>
Returns <b>True</b> if successful, <b>False</b> if there was an error.
</short>
</element>
<element name="CopyFile.SrcFilename">
<short>
The source file name for the copy operation.
</short>
</element>
<element name="CopyFile.DestFilename">
<short>
The destination file name for the copy operation.
</short>
</element>
<element name="CopyFile.Flags">
<short>
Set with flags enabled for the copy operation.
</short>
</element>
<element name="CopyFile.PreserveTime">
<short>
If <b>True</b>, the timestamp of the original file is preserved in the copied 
file.
</short>
</element>
<element name="CopyFile.ExceptionOnError">
<short>
If <b>True</b>, and exception is raised if the copy operation cannot be 
performed.
</short>
</element>

<element name="CopyDirTree">
<short>
Copies all file system entries in a source directory to the destination 
directory using the specified options.
</short>
<descr>
<p>
<var>CopyDirTree</var> is a <var>Boolean</var> function used to copy file 
system entries from the directory in <var>SourceDir</var> to the directory in 
<var>TargetDir</var>.
</p>
<p>
Values in SourceDir and TargetDir are fully-qualified path names for the 
directories. If a trailing path delimiter is omitted in SourceDir or 
TargetDir, it is appended (when needed) to the values. TargetDir cannot be a 
sub-directory located in SourceDir. No actions are performed in the routine 
when TargetDir is located within the specified SourceDir.
</p>
<p>
Flags contains values representing the options enabled in the copy operation. 
The default value for the parameters is an empty set (<b>[]</b>) and 
indicates that none of the <var>TCopyFileFlag</var> options are enabled. The 
value <var>cffCreateDestDirectory</var> is always added to the values in 
Flags internally; CopyDirTree requires the destination directory to be 
created if it does not already exist.
</p>
<p>
See <link id="TCopyFileFlag">TCopyFileFlag</link> for more information about 
the option values and their meanings.
</p>
<p>
The return value is <b>True</b> when all file system entries in SourceDir are 
successfully copied in the routine. Please note that a portion of the copy 
operation may have been performed successfully even when the return value is 
<b>False</b>.
</p>
<p>
Use <var>CopyFile</var> to copy a single file with a given name to a new file 
name.
</p>
</descr>
<seealso>
<link id="CopyFile"/>
<link id="TCopyFileFlags"/>
</seealso>
</element>
<element name="CopyDirTree.Result">
<short>
<b>True</b> when all files are successfully copied in the routine.
</short>
</element>
<element name="CopyDirTree.SourceDir">
<short>
Directory with the files copied in the routine.
</short>
</element>
<element name="CopyDirTree.TargetDir">
<short>
Directory where the copied files are stored.
</short>
</element>
<element name="CopyDirTree.Flags">
<short>
Options enabled for the copy operation; default value is an empty set ([])
</short>
</element>

<element name="PascalFileExt">
<short>
File extensions used for Pascal source code files.
</short>
<descr>
<p>
<var>PascalFileExt</var> is an <b>array constant</b> which contains the file 
extensions (including the initial '.') used for Pascal source code files 
(units).
</p>
</descr>
<seealso>
<link id="PascalSourceExt"/>
</seealso>
</element>

<element name="PascalSourceExt">
<short>
File extensions considered to be a Pascal source, project or package file.
</short>
<descr>
<p>
<var>PascalSourceExt</var> is an <b>array constant</b> which contains the 
file extensions (including the initial '.') used for Pascal source code 
files. Similar to <var>PascalFileExt</var>, but includes extensions used for 
project and package files.
</p>
</descr>
<seealso>
<link id="PascalFileExt"/>
</seealso>
</element>

<element name="AllDirectoryEntriesMask">
<short>
File mask used to match all directories entries on the local file system.
</short>
<descr>
<p>
Used in the implementation of the <var>TFileSearcher.Search</var> method.
</p>
</descr>
<seealso>
<link id="TFileSearcher.Search"/>
</seealso>
</element>

</module>
<!-- FileUtil -->
</package>
</fpdoc-descriptions>