mirror of
https://gitlab.com/freepascal.org/lazarus/lazarus.git
synced 2025-05-01 11:04:15 +02:00
d75d2884f7
* Removes whitespace used to indent topic content. * Wraps text in content at 80 characters.
2366 lines
71 KiB
XML
2366 lines
71 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<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="ExtractFileNameWithoutExt">
|
|
<short>
|
|
Returns the file name without a file extension.
|
|
</short>
|
|
</element>
|
|
<element name="ExtractFileNameWithoutExt.Result">
|
|
<short>
|
|
Returns the original file name if it had no extension, otherwise returns the
|
|
file name with its extension removed.
|
|
</short>
|
|
</element>
|
|
<element name="ExtractFileNameWithoutExt.AFilename">
|
|
<short>
|
|
The name of the file for checking.
|
|
</short>
|
|
</element>
|
|
|
|
<element name="CreateAbsoluteSearchPath">
|
|
<short>
|
|
Forms an absolute search path for files from values in
|
|
<var>BaseDirectory</var> and <var>SearchPath</var>.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>CreateAbsoluteSearchPath</var> - concatenates <var>BaseDirectory</var>
|
|
and <var>SearchPath</var> to form an absolute path to search for files.
|
|
</p>
|
|
<p>
|
|
The routine adds the appropriate path delimiters to the BaseDirectory string,
|
|
and adds the search path. Each directory in the search path is examined to
|
|
ensure that each is also an absolute directory path. The return value
|
|
contains the fully-formed absolute search path.
|
|
</p>
|
|
<p>
|
|
If <var>BaseDirectory</var> is empty, the function exits with a return value
|
|
equal to <var>SearchPath</var>. if <var>SearchPath</var> is empty, the
|
|
function exits with empty string <b>('')</b> in the return value.
|
|
</p>
|
|
<p>
|
|
Deprecated. Use the CreateAbsoluteSearchPath function from the LazFileUtils
|
|
unit.
|
|
</p>
|
|
</descr>
|
|
<version>
|
|
Deprecated in LCL version 2.1.0.
|
|
</version>
|
|
</element>
|
|
<element name="CreateAbsoluteSearchPath.Result">
|
|
<short>
|
|
The absolute path formed by concatenating <var>BaseDirectory</var> and
|
|
<var>SearchPath</var>.
|
|
</short>
|
|
</element>
|
|
<element name="CreateAbsoluteSearchPath.SearchPath">
|
|
<short>
|
|
The search path (a relative path).
|
|
</short>
|
|
</element>
|
|
<element name="CreateAbsoluteSearchPath.BaseDirectory">
|
|
<short>
|
|
The base directory from which to form the absolute path.
|
|
</short>
|
|
</element>
|
|
|
|
<element name="CreateAbsolutePath">
|
|
<short>
|
|
Deprecated.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
Deprecated. Use the CreateAbsolutePath function from the
|
|
<file>LazFileUtils</file> unit.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="#lazutils.lazfileutils.CreateAbsolutePath">CreateAbsolutePath</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="CreateAbsolutePath.Filename">
|
|
<short/>
|
|
</element>
|
|
<element name="CreateAbsolutePath.BaseDirectory">
|
|
<short/>
|
|
</element>
|
|
<element name="CreateAbsolutePath.Result">
|
|
<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>
|
|
<var>ReadFileToString</var> - returns a string with the contents of the named
|
|
file.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>ReadFileToString</var> opens the file and reads its contents into a
|
|
Stream, then reads the stream to construct the <var>Result</var> string.
|
|
</p>
|
|
</descr>
|
|
<errors>
|
|
If there is an error while reading the file, an Exception is raised and an
|
|
empty string is returned.
|
|
</errors>
|
|
</element>
|
|
<element name="ReadFileToString.Result">
|
|
<short>
|
|
The contents of the file as a string, or an empty string if there is an error
|
|
or the file is empty.
|
|
</short>
|
|
</element>
|
|
<element name="ReadFileToString.Filename">
|
|
<short>
|
|
The name of the file for processing.
|
|
</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>
|
|
Search is a method used to search for files or directories matching a
|
|
specified mask found in the specified search paths. <var>ASearchPath</var>
|
|
contains the locations examined in the method, and can contain multiple path
|
|
names separated by the value in <var>PathSeparator</var>. Each delimited path
|
|
value in <var>ASearchPath</var> is resolved by calling the
|
|
<var>ResolveDots</var> function, and processed in the method.
|
|
</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 ASearchMask in the
|
|
search process when set to <b>True</b>.
|
|
</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>
|
|
Base path for searching files.
|
|
</short>
|
|
</element>
|
|
<element name="TFileSearcher.Search.ASearchMask">
|
|
<short>
|
|
Mask 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.
|
|
</p>
|
|
</descr>
|
|
<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 an overloaded routine used to populate a
|
|
<var>TStringList</var> class instance with a list of files match the
|
|
specified search criteria. The procedure variant uses an existing TStringList
|
|
class instance to store the matching file names. The function variant creates
|
|
the TStringList class instance used as the return value for the method.
|
|
</p>
|
|
<remark>
|
|
The function variant of <var>FindAllFiles</var> 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.
|
|
</remark>
|
|
</descr>
|
|
<seealso/>
|
|
<example file="examples/fileutil.findallfiles.pas"/>
|
|
</element>
|
|
<element name="FindAllFiles.Result">
|
|
<short>
|
|
List of file names matching the search criteria.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
The StringList is created in the FindAllFiles function; you should not
|
|
instantiate it before calling the function.
|
|
</p>
|
|
</descr>
|
|
</element>
|
|
<element name="FindAllFiles.AList">
|
|
<short>
|
|
TStringList used to store file names matching the search criteria.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</descr>
|
|
</element>
|
|
<element name="FindAllFiles.SearchPath">
|
|
<short>
|
|
Base path for searching files.
|
|
</short>
|
|
</element>
|
|
<element name="FindAllFiles.SearchMask">
|
|
<short>
|
|
A list of masks, separated by a semicolon (;) to which found files should
|
|
match.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
A list of masks, separated by a semicolon (;) to which found files should
|
|
match. The mask can contain wildcards like * and ? and it also supports sets
|
|
like [a-d,x]. See the Masks unit for more details.
|
|
</p>
|
|
</descr>
|
|
</element>
|
|
<element name="FindAllFiles.SearchSubDirs">
|
|
<short><b>True</b> to search sub-directories in the process.</short>
|
|
<descr>
|
|
<p>
|
|
Parameter DirAttr is int file attribute: if file-system item has this
|
|
attribute(s), it is considered as a directory. It can be
|
|
<var>faDirectory</var>, <var>faSymLink</var>, (<var>faDirectory</var>+
|
|
<var>faSymLink</var>) or maybe another bits can be used.
|
|
</p>
|
|
</descr>
|
|
</element>
|
|
<element name="FindAllFiles.PathSeparator">
|
|
<short>
|
|
If search recursively sub directories.
|
|
</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/>
|
|
</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 sub-directories in the search.
|
|
</short>
|
|
</element>
|
|
<element name="FindAllDirectories.PathSeparator">
|
|
<short>
|
|
Delimiter used to separate 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>
|