From d75d2884f72d74b8ee2a9e4f1190932ed45c8666 Mon Sep 17 00:00:00 2001 From: dsiders Date: Sun, 7 Aug 2022 19:18:45 +0100 Subject: [PATCH] Docs: LazUtils/fileutil. Updates tagging for True, False values. * Removes whitespace used to indent topic content. * Wraps text in content at 80 characters. --- docs/xml/lazutils/fileutil.xml | 3820 +++++++++++++++++++------------- 1 file changed, 2239 insertions(+), 1581 deletions(-) diff --git a/docs/xml/lazutils/fileutil.xml b/docs/xml/lazutils/fileutil.xml index c4d7633c8a..b0b3271745 100644 --- a/docs/xml/lazutils/fileutil.xml +++ b/docs/xml/lazutils/fileutil.xml @@ -1,346 +1,490 @@ - - - - - Miscellaneous routines, types, and classes for manipulating files, file names, and paths. - - -

- fileutils.pas 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 LazFileUtils unit. -

-

- File name handling in the unit is platform- or OS-specific. For the Windows, Darwin (macOS), and Amiga platforms, file names are NOT case sensitive. In addition, under Darwin, the NotLiteralFilenames define is enabled. This indicates that file names cannot be compared using the = string operator. -

-

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

-

- fileutil.pas is part of the LazUtils package. -

- + + + + +Miscellaneous routines, types, and classes for manipulating files, file +names, and paths. + + +

+fileutils.pas 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 LazFileUtils unit. +

+

+File name handling in the unit is platform- or OS-specific. For the Windows, +Darwin (macOS), and Amiga platforms, file names are NOT case +sensitive. In addition, under Darwin, the NotLiteralFilenames define +is enabled. This indicates that file names cannot be compared using the += string operator. +

+

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

+

+fileutil.pas is part of the LazUtils package. +

+ - - - - - - - + + + + + + + - - Byte Order Mark (BOM) used at the beginning of UTF-8-encoded files. - - - + + +Byte Order Mark (BOM) used at the beginning of UTF-8-encoded files. + + + + - - - When True, uppercase and lowercase file names are equivalent. - - -

- FilenamesCaseSensitive is present when the CaseInsensitiveFilenames compiler define exists. -

- - - + + +When True, uppercase and lowercase file names are equivalent. + + +

+FilenamesCaseSensitive is present when the CaseInsensitiveFilenames +compiler define exists. +

+ + + - - - When True, file names can be compared using the = string operator. - - -

- FilenamesLiteral is present when the NotLiteralFilenames compiler define exists. -

- - - + + +When True, file names can be compared using the = string +operator. + + +

+FilenamesLiteral is present when the NotLiteralFilenames compiler +define exists. +

+ + + - - Compares file names after resolving symbolic links. - -

- ComparePhysicalFilenames, like CompareFileNames, is used to compare file name using the case-sensitivity enforced for file names on the platform. -

-

- Calls GetPhysicalFilename to ensure that values in Filename1 and Filename2 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. -

-

- Calls CompareFileNames in LazFileUtils to perform the comparison and get the return value for the routine. -

- - - CompareFileNames - GetPhysicalFilename - - - - Relative sort order for the compared values. - - - First file name resolved and used in the comparison. - - - Second file name resolved and used in the comparison. - + + +Compares file names after resolving symbolic links. + + +

+ComparePhysicalFilenames, like CompareFileNames, is +used to compare file name using the case-sensitivity enforced for file names +on the platform. +

+

+Calls GetPhysicalFilename to ensure that values in +Filename1 and Filename2 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. +

+

+Calls CompareFileNames in LazFileUtils to perform the comparison +and get the return value for the routine. +

+ + +CompareFileNames +GetPhysicalFilename + + + + +Relative sort order for the compared values. + + + + +First file name resolved and used in the comparison. + + + + +Second file name resolved and used in the comparison. + + - - - Compares two file names to see whether they are equal. - - -

- CompareFileNames is an Integer function used to compare the specified file names (and lengths). -

-

- The Filename1 and Filename2 arguments are PChar types with pointers to the first character in each of the compared file names.The Len1 and Len2 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. -

-

- ResolveLinks indicates whether file system or symbolic links are resolved before comparing the file name arguments. When set to True, the ComparePhysicalFilenames routine is called to resolve the file system links to actual path and file names for the comparison. For platforms where NotLiteralFilenames is defined, the file names are copied to a temporary string before resolving the file names. -

-

- Otherwise, the CompareFileNames routine (in LazFileUtils) is used to compare the file names and to get the return value. -

-

- The return value is 0 (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 LazFIleUtils) or ComparePhysicalFilenames. -

- - - - CompareFilenames - - - - - Returns zero (0) if files are equal, or when character values or file name lengths are not equal. - - - - First filename. - - - Length of first filename. - - - Second filename. - - - Length of second filename. - - - - When True, file system links are searched to find the actual file(s) for the comparison. - - + + +Compares two file names to see whether they are equal. + + +

+CompareFileNames is an Integer function used to compare +the specified file names (and lengths). +

+

+The Filename1 and Filename2 arguments are +PChar types with pointers to the first character in each of the +compared file names.The Len1 and Len2 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. +

+

+ResolveLinks indicates whether file system or symbolic links are +resolved before comparing the file name arguments. When set to True, +the ComparePhysicalFilenames routine is called to resolve the file system +links to actual path and file names for the comparison. For platforms where +NotLiteralFilenames is defined, the file names are copied to a +temporary string before resolving the file names. +

+

+Otherwise, the CompareFileNames routine (in LazFileUtils) is +used to compare the file names and to get the return value. +

+

+The return value is 0 (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 +LazFileUtils) or ComparePhysicalFilenames. +

+ + + +CompareFilenames + + + + +Returns zero (0) if files are equal, or when character values or file +name lengths are not equal. + + + + +First filename. + + + + +Length of first filename. + + + + +Second filename. + + + + +Length of second filename. + + + + +When True, file system links are searched to find the actual file(s) +for the comparison. + + - - Gets a short path name using the 8.3 notation from the UTF-8-encoded value. - -

- ExtractShortPathNameUTF8 is a String 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. -

-

- ExtractShortPathNameUTF8 is similar to the ExtractShortPathName routine in the RTL sysutils unit, but accepts a String value in FileName and returns a String value in the result which uses UTF-8 encoding.The RTL routine uses UnicodeString for both. -

-

- The WinCE platform does not support the concept of short file names; the return value is set to the value in FileName. -

-

- For Windows platforms after version 5, the GetShortPathNameW routine is called to get the shortened path name.The UTF-16 value is converted to UTF-8 for use in the return value. -

-

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

- - - ExtractShortPathName - - - - Path name examined in the routine. - - - Path name using the familiar 8.3 notation. - + + +Gets a short path name using the 8.3 notation from the UTF-8-encoded value. + + +

+ExtractShortPathNameUTF8 is a String 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. +

+

+ExtractShortPathNameUTF8 is similar to the ExtractShortPathName +routine in the RTL sysutils unit, but accepts a String value in +FileName and returns a String value in the result which uses UTF-8 +encoding.The RTL routine uses UnicodeString for both. +

+

+The WinCE platform does not support the concept of short file names; the +return value is set to the value in FileName. +

+

+For Windows platforms after version 5, the GetShortPathNameW +routine is called to get the shortened path name.The UTF-16 value is +converted to UTF-8 for use in the return value. +

+

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

+ + +ExtractShortPathName + + + + +Path name examined in the routine. + + + + +Path name using the familiar 8.3 notation. + + - - - Deletes the specified directory (or only its contents when OnlyChildren is True). - - -

- Returns True when the specified entries are deleted on the local file system. Returns False when: -

-
    -
  • - DirectoryName is one of the relative path indicators like '.' or '..' -
    • -
  • DirectoryName is an empty string ('')
    • -
  • DirectoryName does not exist on the local file system
    • -
  • - The process does not have permissions needed to delete the directory or its content -
    • -
- - - - - - Returns True if the directory or its contents were correctly removed. - - - The name of the directory for processing. - - - If True, only the contents ('children') of the directory are removed. - + + +Deletes the specified directory (or only its contents when +OnlyChildren is True). + + +

+Returns True when the specified entries are deleted on the local file +system. Returns False when: +

+
    +
  • +DirectoryName is one of the relative path indicators like '.' or '..' +
    • +
  • DirectoryName is an empty string ('')
    • +
  • DirectoryName does not exist on the local file system
    • +
  • +The process does not have permissions needed to delete the directory or its +content +
    • +
+ + + + +Returns True if the directory or its contents were correctly removed. + + + + +The name of the directory for processing. + + + + +If True, only the contents ('children') of the directory are removed. + + - - Gets the directory where the current program is located. - -

- ProgramDirectory is a String function which gets the path to the directory where the current program is located. -

-

- ProgramDirectory calls ParamStrUTF8 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 PATH environment variable was used to locate and start the process. SearchFileInPath is called to search each of the directory paths included in the PATH environment variable. -

-

- ProgramDirectory calls GetPhysicalFilename to resolve a symbolic link in the path to the executable. ExpandFileNameUTF8 is called to expand drive letters or relative path references in the return value. -

-

- The return value is an empty string if the executable was not located on local file system. -

- - - - ParamStrUTF8 - GetEnvironmentVariableUTF8 - GetPhysicalFilename - ExpandFileNameUTF8 - - - - Path to the directory where the current program is located. - + + +Gets the directory where the current program is located. + + +

+ProgramDirectory is a String function which gets the +path to the directory where the current program is located. +

+

+ProgramDirectory calls ParamStrUTF8 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 PATH +environment variable was used to locate and start the process. +SearchFileInPath is called to search each of the directory paths +included in the PATH environment variable. +

+

+ProgramDirectory calls GetPhysicalFilename to resolve a symbolic +link in the path to the executable. ExpandFileNameUTF8 is called +to expand drive letters or relative path references in the return value. +

+

+The return value is an empty string if the executable was not located on +local file system. +

+ + + +ParamStrUTF8 +GetEnvironmentVariableUTF8 +GetPhysicalFilename +ExpandFileNameUTF8 + + + + +Path to the directory where the current program is located. + + - - - Gets the directory for the current executable without the macOS bundle post-fix. - - -

- ProgramDirectoryWithBundle is a String 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. -

- - - - - - - Path to the executable without the macOS bundle post-fix. - + + +Gets the directory for the current executable without the macOS bundle +post-fix. + + +

+ProgramDirectoryWithBundle is a String 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. +

+ + + + + + + +Path to the executable without the macOS bundle post-fix. + + - - Expands the specified UTF-8-encoded UNC file name to an absolute UNC file name. - -

- ExpandUNCFileNameUTF8 is a String function used to expand the UNC file name in the FileName argument to an absolute UNC file name. It is the UTF-8-enabled equivalent of the ExpandUNCFileName routine from the FPC RTL. -

-

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

- - - ExpandUNCFileName - ExpandFileName - - - - File name expanded in the routine. - - - The expanded file name. - + + +Expands the specified UTF-8-encoded UNC file name to an absolute UNC file +name. + + +

+ExpandUNCFileNameUTF8 is a String function used to +expand the UNC file name in the FileName argument to an absolute +UNC file name. It is the UTF-8-enabled equivalent of the ExpandUNCFileName +routine from the FPC RTL. +

+

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

+ + +ExpandUNCFileName +ExpandFileName + + + + +File name expanded in the routine. + + + + +The expanded file name. + + - - Gets the size for the specified file name. - -

- FileSize is an overloaded Int64 function used to get the size for the file specified in the FileName parameter. FileSize is similar to the FileSize routine in the FPC RTL, but accepts a file name instead of a FileRec argument. -

-

- FileSize calls FileSizeUtf8 to get the return value for the function. -

- - - FileSizeUtf8 - FileSize - - - - Returns the size of the file, or -1 if the file does not exist. - - - The name of the file examined in the routine. - + + +Gets the size for the specified file name. + + +

+FileSize is an overloaded Int64 function used to get +the size for the file specified in the FileName parameter. +FileSize is similar to the FileSize routine in the FPC RTL, but accepts a +file name instead of a FileRec argument. +

+

+FileSize calls FileSizeUtf8 to get the return value for the +function. +

+ + +FileSizeUtf8 +FileSize + + + + +Returns the size of the file, or -1 if the file does not exist. + + + + +The name of the file examined in the routine. + + - - - Indicates whether the specified file name uses a recognized Pascal file extension. - - -

- FilenameHasPascalExt is a Boolean function used to determine if the file name in the Filename argument uses a file extension recognized as a Pascal source code file. The CompareText routine is called to perform a case-insensitive comparison between the value in Filename and the recognized file extensions. -

-

- The return value is True when Filename has one of the following file extensions: -

-
    -
  • .pas
    • -
  • .pp
    • -
  • .p
    • -
-

- The return value is False if Filename does not have a file extension, or the extension does not match the preceding values. -

- - - - - True when the file name uses a recognized Pascal file extension. - - - File name examined in the routine. - + + +Indicates whether the specified file name uses a recognized Pascal file +extension. + + +

+FilenameHasPascalExt is a Boolean function used to +determine if the file name in the Filename argument uses a file +extension recognized as a Pascal source code file. The CompareText +routine is called to perform a case-insensitive comparison between the value +in Filename and the recognized file extensions. +

+

+The return value is True when Filename has one of the following file +extensions: +

+
    +
  • .pas
    • +
  • .pp
    • +
  • .p
    • +
+

+The return value is False if Filename does not have a file extension, +or the extension does not match the preceding values. +

+ + + + + +True when the file name uses a recognized Pascal file extension. + + + + +File name examined in the routine. + + - - - Checks whether the specified file name shares the path specified in Path. - - - -

- FileIsInPath is a Boolean function used to determine whether the file in FileName is located in the specified Path. FileIsInPath calls the CleanAndExpandFilename and CleanAndExpandDirectory routines to resolve drive letters or relative path information included in the arguments. -

-

- The return value is True when the resolved paths for the arguments contain the same values. FileIsInPath does not verify whether Path or FileName actually exist on the local file system. It compares the specified string values only. -

-

- Use DirectoryExists or DirectoryExistsUTF8 to determine whether a path exists on the local file system. -

-

- Use FileExists or FileExistsUTF8 to determine whether a file exists on the local file system. -

-

- Example: -

+ + +Checks whether the specified file name shares the path specified in Path. + + +

+FileIsInPath is a Boolean function used to determine whether the +file in FileName is located in the specified Path. +FileIsInPath calls the CleanAndExpandFilename and CleanAndExpandDirectory +routines to resolve drive letters or relative path information included in +the arguments. +

+

+The return value is True when the resolved paths for the arguments +contain the same values. FileIsInPath does not verify whether Path or +FileName actually exist on the local file system. It compares the specified +string values only. +

+

+Use DirectoryExists or DirectoryExistsUTF8 to determine whether a path exists +on the local file system. +

+

+Use FileExists or FileExistsUTF8 to determine whether a file exists on the +local file system. +

+

+Example: +

// uses FileUtil; // ... @@ -357,46 +501,59 @@ ShowMessage('File: ' + sFile + LineEnding + 'is in Path: ' + sDir + '?' + LineEnding + 'FileIsInPath() result is: ' + bResult.ToString(TUseBoolStrs.True) + '.'); - - - - CleanAndExpandFilename - CleanAndExpandDirectory - CompareFileNames - - - - - Returns True the arguments share the same path information. - - - - The name of the file examined in the routine. - - - The path name examined in the routine. - + + + +CleanAndExpandFilename +CleanAndExpandDirectory +CompareFileNames + + + + +Returns True the arguments share the same path information. + + + + +The name of the file examined in the routine. + + + + +The path name examined in the routine. + + - - - Checks whether the specified file name shares the path specified in Directory. - - -

- FileIsInDirectory is a Boolean function used to determine whether the file in FileName is located in Directory. FileIsInDirectory calls the CleanAndExpandFilename and CleanAndExpandDirectory routines to resolve drive letters or relative path information included in the arguments. -

-

- The return value is True when the resolved paths for the arguments contain the same values. FileIsInDirectory does not verify whether Directory or FileName actually exist on the local file system. It compares the specified string values only. -

-

- Use DirectoryExists or DirectoryExistsUTF8 to determine whether a path exists on the local file system. -

-

- Use FileExists or FileExistsUTF8 to determine whether a file exists on the local file system. -

-

- Example: -

+ + +Checks whether the specified file name shares the path specified in Directory. + + +

+FileIsInDirectory is a Boolean function used to determine whether +the file in FileName is located in Directory. +FileIsInDirectory calls the CleanAndExpandFilename and +CleanAndExpandDirectory routines to resolve drive letters or relative path +information included in the arguments. +

+

+The return value is True when the resolved paths for the arguments +contain the same values. FileIsInDirectory does not verify whether +Directory or FileName actually exist on the local file system. It compares +the specified string values only. +

+

+Use DirectoryExists or DirectoryExistsUTF8 to determine whether a path exists +on the local file system. +

+

+Use FileExists or FileExistsUTF8 to determine whether a file exists on the +local file system. +

+

+Example: +

// uses FileUtil; // ... @@ -413,359 +570,485 @@ ShowMessage('File: ' + sFile + LineEnding + 'is in Directory: ' + sDir + '?' + LineEnding + 'FileIsInDirectory() result is: ' + bResult.ToString(TUseBoolStrs.True) + '.'); - - - - CleanAndExpandFilename - CleanAndExpandDirectory - CompareFileNames - - - - Returns True if the file and directory share the same paths. - - - The name of the file to be checked. - - - The name of the directory compared to the file name. - + + + +CleanAndExpandFilename +CleanAndExpandDirectory +CompareFileNames + + + + +Returns True if the file and directory share the same paths. + + + + +The name of the file to be checked. + + + + +The name of the directory compared to the file name. + + - - - Returns the file name without a file extension. - - - - - Returns the original file name if it had no extension, otherwise returns the file name with its extension removed. - - - - The name of the file for checking. - + + +Returns the file name without a file extension. + + + + +Returns the original file name if it had no extension, otherwise returns the +file name with its extension removed. + + + + +The name of the file for checking. + + - - - Forms an absolute search path for files from values in BaseDirectory and SearchPath. - - -

- CreateAbsoluteSearchPath - concatenates BaseDirectory and SearchPath to form an absolute path to search for files. -

-

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

-

- If BaseDirectory is empty, the function exits with a return value equal to SearchPath. if SearchPath is empty, the function exits with empty string ('') in the return value. -

-

- Deprecated. Use the CreateAbsoluteSearchPath function from the LazFileUtils unit. -

- - - Deprecated in LCL version 2.1.0. - - - - - The absolute path formed by concatenating BaseDirectory and SearchPath. - - - - The search path (a relative path). - - - The base directory from which to form the absolute path. - + + +Forms an absolute search path for files from values in +BaseDirectory and SearchPath. + + +

+CreateAbsoluteSearchPath - concatenates BaseDirectory +and SearchPath to form an absolute path to search for files. +

+

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

+

+If BaseDirectory is empty, the function exits with a return value +equal to SearchPath. if SearchPath is empty, the +function exits with empty string ('') in the return value. +

+

+Deprecated. Use the CreateAbsoluteSearchPath function from the LazFileUtils +unit. +

+ + +Deprecated in LCL version 2.1.0. + + + + +The absolute path formed by concatenating BaseDirectory and +SearchPath. + + + + +The search path (a relative path). + + + + +The base directory from which to form the absolute path. + + - - Deprecated. - -

- Deprecated. Use the CreateAbsolutePath function from the LazFileUtils unit. -

- - - CreateAbsolutePath - - - - - - - - - - - + + +Deprecated. + + +

+Deprecated. Use the CreateAbsolutePath function from the +LazFileUtils unit. +

+ + +CreateAbsolutePath + + + + + + + + + + + - - - Gets the file mask representing all files in a file filter. - - -

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

- - - - - The All Files mask for the platform. - + + +Gets the file mask representing all files in a file filter. + + +

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

+ + + + + +The All Files mask for the platform. + + - - - Returns the file extension (including the starting .) for an executable file on the platform. - - - - Returns '.exe' on Windows, or an empty string for other platforms. - + + +Returns the file extension (including the starting .) for an executable file +on the platform. + + + + +Returns '.exe' on Windows, or an empty string for other platforms. + + - - - ReadFileToString - returns a string with the contents of the named file. - - -

- ReadFileToString opens the file and reads its contents into a Stream, then reads the stream to construct the Result string. -

- - - If there is an error while reading the file, an Exception is raised and an empty string is returned. - - - - - The contents of the file as a string, or an empty string if there is an error or the file is empty. - - - - The name of the file for processing. - + + +ReadFileToString - returns a string with the contents of the named +file. + + +

+ReadFileToString opens the file and reads its contents into a +Stream, then reads the stream to construct the Result string. +

+ + +If there is an error while reading the file, an Exception is raised and an +empty string is returned. + + + + +The contents of the file as a string, or an empty string if there is an error +or the file is empty. + + + + +The name of the file for processing. + + - - Flags used to control options used when searching for file(s) in a given path. - -

- TSearchFileInPathFlag is an enumerated type with values that enable search options when locating files in a given path. Values in TSearchFileInPathFlag are stored in the TSearchFileInPathFlags set type and passed as an argument to the SearchFileInPath and SearchAllFilesInPath routines. -

- - - - - - - - - Do not search in BasePath, search only in SearchPath. - - - Performs a case-insensitive search for file or directory names. - - - Must be a file, and not a directory. - - - File must be an executable file for the platform. - - - Removes ANSI Quotation Marks in a search path or file name. - + + +Flags used to control options used when searching for file(s) in a given path. + + +

+TSearchFileInPathFlag is an enumerated type with values that +enable search options when locating files in a given path. Values in +TSearchFileInPathFlag are stored in the TSearchFileInPathFlags set +type and passed as an argument to the SearchFileInPath and +SearchAllFilesInPath routines. +

+ + + + + + + + + +Do not search in BasePath, search only in SearchPath. + + + + +Performs a case-insensitive search for file or directory names. + + + + +Must be a file, and not a directory. + + + + +File must be an executable file for the platform. + + + + +Removes ANSI Quotation Marks in a search path or file name. + + - - Set type used to store values from the TSearchFileInPathFlag enumeration. - -

- TSearchFileInPathFlags is a Set type used to store zero (0) or more values from the TSearchFileInPathFlag enumeration. It is the type passed as an argument to the SearchFileInPath and SearchAllFilesInPath routines. -

- - - - - - - + + +Set type used to store values from the TSearchFileInPathFlag enumeration. + + +

+TSearchFileInPathFlags is a Set type used to store zero (0) +or more values from the TSearchFileInPathFlag enumeration. It is +the type passed as an argument to the SearchFileInPath and +SearchAllFilesInPath routines. +

+ + + + + + + - - - Search flags used to find a program file in a path on the current platform. - - -

- sffFindProgramInPath is a constant which contains the default TSearchFileInPathFlag enumeration values used to locate a program file on the current platform. -

-

- For the Windows platform, sffFindProgramInPath contains the following values: -

- [ sffDequoteSearchPath, sffFile, sffExecutable ] -

- For UNIX-like platforms, sffFindProgramInPath contains the following values: -

- [ sffDontSearchInBasePath, sffFile, sffExecutable ] -

- For all other platforms, sffFindProgramInPath contains the following values: -

- [ sffFile, sffExecutable ] -

- sffFindProgramInPath is used in the implementation of the FindDefaultExecutablePath routine. -

- - - - - + + +Search flags used to find a program file in a path on the current platform. + + +

+sffFindProgramInPath is a constant which contains the default +TSearchFileInPathFlag enumeration values used to locate a program +file on the current platform. +

+

+For the Windows platform, sffFindProgramInPath contains the following values: +

+[ sffDequoteSearchPath, sffFile, sffExecutable ] +

+For UNIX-like platforms, sffFindProgramInPath contains the following values: +

+[ sffDontSearchInBasePath, sffFile, sffExecutable ] +

+For all other platforms, sffFindProgramInPath contains the following values: +

+[ sffFile, sffExecutable ] +

+sffFindProgramInPath is used in the implementation of the +FindDefaultExecutablePath routine. +

+ + + + + - - - Searches for a file name in a given path using the specified base path and options. - - -

- SearchFileInPath is a String function used to get the fully-qualified name for the specified FileName 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. -

-

- SearchPath contains the delimited list of search paths examined in the routine. Search paths are separated using the value in Delimiter. -

-

- BasePath contains the path used to resolve relative path references in SearchPath. By default, BasePath is also searched unless sffDontSearchInBasePath is included in the Flags parameter. -

-

- Flags contains values from the TSearchFileInPathFlag enumeration used to control the file matching logic used in the routine. For example: -

-
-
sffDontSearchInBasePath
-
Prevents searching in the directory represented by BasePath.
-
sffFile
-
Excludes a directory entry that matches the file name.
-
sffExecutable
-
Exclude any file or directory name that is not an executable.
-
-

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

-

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

- - - - - Fully qualified file name for the file, or an empty string if the file was not found. - - - - The name of the file to locate in the routine. - - - Path used to resolve relative path references in a search path. - - - List of search paths examined in the routine. - - - Delimiter used to separate search paths. - - - Controls the file matching logic and behavior used in the routine. - + + +Searches for a file name in a given path using the specified base path and +options. + + +

+SearchFileInPath is a String function used to get the +fully-qualified name for the specified FileName 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. +

+

+SearchPath contains the delimited list of search paths examined in +the routine. Search paths are separated using the value in +Delimiter. +

+

+BasePath contains the path used to resolve relative path +references in SearchPath. By default, BasePath is also searched unless +sffDontSearchInBasePath is included in the Flags +parameter. +

+

+Flags contains values from the TSearchFileInPathFlag +enumeration used to control the file matching logic used in the routine. For +example: +

+
+
sffDontSearchInBasePath
+
Prevents searching in the directory represented by BasePath.
+
sffFile
+
Excludes a directory entry that matches the file name.
+
sffExecutable
+
Exclude any file or directory name that is not an executable.
+
+

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

+

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

+ + + + +Fully qualified file name for the file, or an empty string if the file was +not found. + + + + +The name of the file to locate in the routine. + + + + +Path used to resolve relative path references in a search path. + + + + +List of search paths examined in the routine. + + + + +Delimiter used to separate search paths. + + + + +Controls the file matching logic and behavior used in the routine. + + - - - SearchAllFilesInPath - searches for all files named Filename in the given SearchPath using the supplied BasePath with the specified Delimiter and the options listed in Flags. - - -

- SearchAllFilesInPath is a TStrings function used to get a list with all file names matching the value in FileName. -

-

- SearchAllFilesInPath creates the TStringList instance in the return value when needed. The return value can be Nil if no files or directories were found that match the FileName parameter. -

-

- Files or directories stored in the return value are fully-qualified path names, with relative path references resolved to the path in BasePath. If FileName contains an absolute path name, the return value has a single entry with the normalized value for FileName. -

-

- SearchPath contains one or more search paths examined in the routine. Each search path is separated by the value in Delimiter. -

-

- Flags is a set type which contains zero or more options enabled for the search. It can include values from the TSearchFileInPathFlag enumeration, including: -

-
-
sffDontSearchInBasePath
-
- 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. -
-
sffFile
-
- Matching entries must be a file and not a directory. Directory names which match FileName are ignored. -
-
sffExecutable
-
- Matching entries must be an executable file for the platform. Non-executable files are ignored. -
-
sffDequoteSearchPath
-
- Removes ANSI Quotation Marks found in the sanitized name for a matching file. -
-
- - - - - FilenameIsAbsolute - CleanAndExpandFilename - CleanAndExpandDirectory - FileExistsUTF8 - DirectoryExistsUTF8 - - - - - Returns a fully qualified file name for all files that match the supplied criteria, or an empty string if the file is not found. - - - - The name of the file for searching. - - - - The BasePath to be used for the search. - - - - The path for searching. - - - The delimiter used between search paths. - - - - Flags specifying how to search: e.g. don't search in base path, case independent search. - - + + +SearchAllFilesInPath - searches for all files named +Filename in the given SearchPath using the supplied +BasePath with the specified Delimiter and the options +listed in Flags. + + +

+SearchAllFilesInPath is a TStrings function used to get a list +with all file names matching the value in FileName. +

+

+SearchAllFilesInPath creates the TStringList instance in the return value +when needed. The return value can be Nil if no files or directories +were found that match the FileName parameter. +

+

+Files or directories stored in the return value are fully-qualified path +names, with relative path references resolved to the path in +BasePath. If FileName contains an absolute path name, the return +value has a single entry with the normalized value for FileName. +

+

+SearchPath contains one or more search paths examined in the +routine. Each search path is separated by the value in Delimiter. +

+

+Flags is a set type which contains zero or more options enabled +for the search. It can include values from the +TSearchFileInPathFlag enumeration, including: +

+
+
sffDontSearchInBasePath
+
+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. +
+
sffFile
+
+Matching entries must be a file and not a directory. Directory names which +match FileName are ignored. +
+
sffExecutable
+
+Matching entries must be an executable file for the platform. Non-executable +files are ignored. +
+
sffDequoteSearchPath
+
+Removes ANSI Quotation Marks found in the sanitized name for a matching file. +
+
+ + + + +FilenameIsAbsolute +CleanAndExpandFilename +CleanAndExpandDirectory +FileExistsUTF8 +DirectoryExistsUTF8 + + + + +Returns a fully qualified file name for all files that match the supplied +criteria, or an empty string if the file is not found. + + + + +The name of the file for searching. + + + + +The BasePath to be used for the search. + + + + +The path for searching. + + + + +The delimiter used between search paths. + + + + +Flags specifying how to search: e.g. don't search in base path, +case independent search. + + - - - Finds the file name that most closely matches the specified file name. - - -

- FindDiskFilename is a String function used to get the file name which most closely matches the value in the FileName 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. -

-

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

-

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

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

- Example: -

+ + +Finds the file name that most closely matches the specified file name. + + +

+FindDiskFilename is a String function used to get the file name +which most closely matches the value in the FileName 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. +

+

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

+

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

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

+Example: +

// uses FileUtil; // var AFileName, AResult: String; @@ -781,927 +1064,1302 @@ AFileName := '/ETC/FONTS/FONTS.CONF'; AResult := FindDiskFileName(AFileName); // AResult contains: '/etc/fonts/fonts.conf'; - - - - - - ResolveDots - CompareFilenamesIgnoreCase - - - - - Resolved path and file name which is the case-insensitive match for the specified value. - - - - The qualified path (optional) and file name to locate in the routine. - + + + + + +ResolveDots +CompareFilenamesIgnoreCase + + + + +Resolved path and file name which is the case-insensitive match for the +specified value. + + + + +The qualified path (optional) and file name to locate in the routine. + + - - - FindDiskFileCaseInsensitive - searches for the given FileName in a case insensitive manner. - - - - - If it exists, returns the file name with path information otherwise returns an empty string. - - - - The name of the file for processing. - + + +FindDiskFileCaseInsensitive - searches for the given +FileName in a case insensitive manner. + + + + +If it exists, returns the file name with path information otherwise returns +an empty string. + + + + +The name of the file for processing. + + - - Finds the default path to the named Executable file. - -

- FindDefaultExecutablePath finds the default path to the named Executable file. On Windows systems, it looks for files both with and without the '.EXE' extension. -

-

- If Executable is not an absolute filename the executable is searched using the environment variable PATH. Relative directories in PATH are expanded using BaseDir. -

-

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

- - - - - Returns the filename of the Executable file with path information attached. - - - - - The name of the Executable file. - - + + +Finds the default path to the named Executable file. + + +

+FindDefaultExecutablePath finds the default path to the named +Executable file. On Windows systems, it looks for files both with and without +the '.EXE' extension. +

+

+If Executable is not an absolute filename the executable is searched using +the environment variable PATH. Relative directories in PATH are expanded +using BaseDir. +

+

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

+ + + + +Returns the filename of the Executable file with path information attached. + + + + +The name of the Executable file. + + - - Implements an iterator for file and directory names on the local file system. - -

- TFileIterator 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 TFileSearcher ancestor. -

-

- TFileIterator is the type passed as an argument to TFileFoundEvent, TDirectoryFoundEvent, and TDirectoryEnterEvent event handlers. -

- - - - - - - - + + +Implements an iterator for file and directory names on the local file system. + + +

+TFileIterator 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 TFileSearcher ancestor. +

+

+TFileIterator is the type passed as an argument to +TFileFoundEvent, TDirectoryFoundEvent, and +TDirectoryEnterEvent event handlers. +

+ + + + + + + + - - - - + + + + - - Gets the value for the FileName property. - - - - - - - Value for the property. - + + +Gets the value for the FileName property. + + + + + + + + +Value for the property. + + - - Stops the search process. - -

- Changes the value in Searching to False. -

- - - - - - + + +Stops the search process. + + +

+Changes the value in Searching to False. +

+ + + + + + - - True when the current file system entry is a directory. - -

- IsDirectory is a Boolean function which indicates if the current file entry is a directory on the local file system. Checks the file attributes in FileInfo to determine if the faDirectory attribute is included for the file. Returns True when the attribute in included in the TSearchRec value. -

- - - - TSearchRec - faDirectory - - - - True if the current file entry is a directory. - + +True when the current file system entry is a directory. + +

+IsDirectory is a Boolean function which indicates if +the current file entry is a directory on the local file system. Checks the +file attributes in FileInfo to determine if the +faDirectory attribute is included for the file. Returns +True when the attribute in included in the TSearchRec value. +

+ + + +TSearchRec +faDirectory + + + + +True if the current file entry is a directory. + + - - The qualified file name for the current file entry. - -

- FileName is a read-only String property which contains the qualified file name for the current file entry. FileName includes the value in Path as a prefix and the file name indicated in FileInfo. -

- - - - - - + + +The qualified file name for the current file entry. + + +

+FileName is a read-only String property which contains +the qualified file name for the current file entry. FileName includes the +value in Path as a prefix and the file name indicated in +FileInfo. +

+ + + + + + - - Contains file information for the current entry in the iterator. - -

- FileInfo is a read-only TSearchRec 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 Path, FileName, and FileInfo properties are updated in descendent classes which perform the search operation. -

- - - - - - - - + + +Contains file information for the current entry in the iterator. + + +

+FileInfo is a read-only TSearchRec 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 Path, FileName, and +FileInfo properties are updated in descendent classes which perform the +search operation. +

+ + + + + + + + - - Gets the current directory level relative to the base search path. - -

- Level is a read-only Integer property which contains the directory level for the current entry in the FileInfo 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. -

- - - - - - - + + +Gets the current directory level relative to the base search path. + + +

+Level is a read-only Integer property which contains +the directory level for the current entry in the FileInfo +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. +

+ + + + + + + - - Contains the path to the current file or directory in the iterator. - -

- Path is a read-only String property which contains the fully-qualified path to the current file or directory in the FileInfo property. Values in the Path, FileName, and FileInfo properties are updated in descendent classes which perform the search operation. -

- - - - - - - + + +Contains the path to the current file or directory in the iterator. + + +

+Path is a read-only String property which contains the +fully-qualified path to the current file or directory in the +FileInfo property. Values in the Path, FileName, and +FileInfo properties are updated in descendent classes which perform the +search operation. +

+ + + + + + + - - Indicates if a search process is active. - -

- Searching is a read-only Boolean 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. -

-

- Searching is set to False when the Stop method is called. -

- - - - - - + + +Indicates if a search process is active. + + +

+Searching is a read-only Boolean 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. +

+

+Searching is set to False when the Stop method is called. +

+ + + + + + - - - Specifies an event handler signalled when a file name is found for the specified iterator. - - -

- TFileFoundEvent is an object procedure type which specifies an event handler signalled when a file name is found using the specified iterator. FileIterator contains the TFileIterator instance for the event notification. -

-

- TFileFoundEvent is the type used to implement the TFileSearcher.OnFileFound event handler. Applications can implement a procedure using the event signature to perform actions needed to process the file in a FileIterator. -

- - - - - - - - File iterator with the file information for the event. - + + +Specifies an event handler signalled when a file name is found for the +specified iterator. + + +

+TFileFoundEvent is an object procedure type which specifies an +event handler signalled when a file name is found using the specified +iterator. FileIterator contains the TFileIterator +instance for the event notification. +

+

+TFileFoundEvent is the type used to implement the +TFileSearcher.OnFileFound event handler. Applications can +implement a procedure using the event signature to perform actions needed to +process the file in a FileIterator. +

+ + + + + + + + +File iterator with the file information for the event. + + - - - Specifies an event handler signalled when a directory is found for the specified iterator. - - -

- TDirectoryFoundEvent is an object procedure type which specifies an event handler signalled when a directory is located for the iterator in FileIterator. -

-

- TDirectoryFoundEvent is the type used to implement the TFileSearcher.OnDirectoryFound event handler. Applications can implement a procedure using the event signature to perform actions needed to process the directory in a FileIterator. -

- - - - - File iterator with the directory information for the event. - + + +Specifies an event handler signalled when a directory is found for the +specified iterator. + + +

+TDirectoryFoundEvent is an object procedure type which specifies +an event handler signalled when a directory is located for the iterator in +FileIterator. +

+

+TDirectoryFoundEvent is the type used to implement the +TFileSearcher.OnDirectoryFound event handler. Applications can +implement a procedure using the event signature to perform actions needed to +process the directory in a FileIterator. +

+ + + + + +File iterator with the directory information for the event. + + - - - Specifies an event handler signalled when a new directory is processed with the specified iterator. - - -

- TDirectoryEnterEvent is an object procedure type which specifies an event handler signalled when a new directory is processed for the iterator in FileIterator. -

-

- TDirectoryEnterEvent is the type used to implement the TFileSearcher.OnDirectoryEnter event handler. Applications can implement a procedure using the event signature to perform actions needed to process the directory in a FileIterator. -

- - - - - File iterator with the directory information for the event. - + + +Specifies an event handler signalled when a new directory is processed with +the specified iterator. + + +

+TDirectoryEnterEvent is an object procedure type which specifies +an event handler signalled when a new directory is processed for the iterator +in FileIterator. +

+

+TDirectoryEnterEvent is the type used to implement the +TFileSearcher.OnDirectoryEnter event handler. Applications can +implement a procedure using the event signature to perform actions needed to +process the directory in a FileIterator. +

+ + + + + +File iterator with the directory information for the event. + + - - Implements an iterator used to search for files or directories. - -

- TFileSearcher is a TFileIterator 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. -

-

- It implements the Search method to perform a search using the specified path(s) and file mask(s). -

-

- Use MaskSeparator to specify the delimiter used to separate a list of mask values passed to the method. Use PathSeparator to specify the delimiter used to separate a list of file paths passed to the method. -

-

- Use FileAttribute and DirectoryAttribute to specify the file system attributes needed for files or directories considered a match in the Search method. Use FollowSymLink to indicate whether symbolic links on the file system are followed in the Search method. -

-

- Use the OnFileFound, OnDirectoryFound, and OnDirectoryEnter event handlers to perform the actions needed for files or directories found using the Search method. -

-

- TFileSearcher is the ancestor class for more specialized descendants like TListFileSearcher and TListDirectoriesSearcher. -

- - - - - - - + + +Implements an iterator used to search for files or directories. + + +

+TFileSearcher is a TFileIterator 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. +

+

+It implements the Search method to perform a search using the +specified path(s) and file mask(s). +

+

+Use MaskSeparator to specify the delimiter used to separate a list +of mask values passed to the method. Use PathSeparator to specify +the delimiter used to separate a list of file paths passed to the method. +

+

+Use FileAttribute and DirectoryAttribute to specify the +file system attributes needed for files or directories considered a match in +the Search method. Use FollowSymLink to indicate whether symbolic +links on the file system are followed in the Search method. +

+

+Use the OnFileFound, OnDirectoryFound, and +OnDirectoryEnter event handlers to perform the actions needed for +files or directories found using the Search method. +

+

+TFileSearcher is the ancestor class for more specialized descendants like +TListFileSearcher and TListDirectoriesSearcher. +

+ + + + + + + - - - - - - - - + + + + + + + + - - Raises an Exception if Search is called when Searching is already set to True. - + + +Raises an Exception if Search is called when Searching is already set to +True. + + - - Signals the OnDirectoryEnter event handler (when assigned). - + + +Signals the OnDirectoryEnter event handler (when assigned). + + - - Signals the OnDirectoryFound event handler (when assigned). - + + +Signals the OnDirectoryFound event handler (when assigned). + + - - Signals the OnFileFound event handler (when assigned). - + + +Signals the OnFileFound event handler (when assigned). + + - - Constructor for the class instance. - -

- Create 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: -

-
-
MaskSeparator
-
Set to ';'.
-
PathSeparator
-
Set to ';'.
-
FollowSymLink
-
Set to True.
-
FileAttribute
-
Set to faAnyFile.
-
DirectoryAttribute
-
Set to faDirectory.
-
Searching
-
Set to False.
-
- - - + + +Constructor for the class instance. + + +

+Create 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: +

+
+
MaskSeparator
+
Set to ';'.
+
PathSeparator
+
Set to ';'.
+
FollowSymLink
+
Set to True.
+
FileAttribute
+
Set to faAnyFile.
+
DirectoryAttribute
+
Set to faDirectory.
+
Searching
+
Set to False.
+
+ + + - - - Searches for files or directories in the specified path(s) using the specified options. - - -

- Search is a method used to search for files or directories matching a specified mask found in the specified search paths. ASearchPath contains the locations examined in the method, and can contain multiple path names separated by the value in PathSeparator. Each delimited path value in ASearchPath is resolved by calling the ResolveDots function, and processed in the method. -

-

- The value in the CaseSensitive argument is used to add or remove mask options for the search mask in ASearchMask. Set CaseSensitive to True before calling Search to perform file name comparisons with case sensitivity. -

-

- ASearchSubDirs includes subdirectories found in ASearchMask in the search process when set to True. -

-

- Set the value in FileAttribute to control the file attributes included in the search process. The default value (faAnyFile) allows all files to be considered. -

-

- Set the value in DirectoryAttribute to control whether directory names are included in the search process. The default value (faDirectory) includes directory names. -

-

- Set the value in FollowSymLink to indicate whether symbolic links in the file system are followed in the method. -

-

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

- - -

- Calls RaiseSearchingError to raise an exception if the Search method has already been called and has not completed. -

- - - - - - - - - - - - - - - Base path for searching files. - - - Mask used to determine file names that match in the search. - - - Indicates if subdirectories are searched recursively. - - - Indicates if file names are compared using case sensitivity. - + + +Searches for files or directories in the specified path(s) using the +specified options. + + +

+Search is a method used to search for files or directories matching a +specified mask found in the specified search paths. ASearchPath +contains the locations examined in the method, and can contain multiple path +names separated by the value in PathSeparator. Each delimited path +value in ASearchPath is resolved by calling the +ResolveDots function, and processed in the method. +

+

+The value in the CaseSensitive argument is used to add or remove +mask options for the search mask in ASearchMask. Set CaseSensitive to +True before calling Search to perform file name comparisons with case +sensitivity. +

+

+ASearchSubDirs includes subdirectories found in ASearchMask in the +search process when set to True. +

+

+Set the value in FileAttribute to control the file attributes +included in the search process. The default value (faAnyFile) +allows all files to be considered. +

+

+Set the value in DirectoryAttribute to control whether directory +names are included in the search process. The default value +(faDirectory) includes directory names. +

+

+Set the value in FollowSymLink to indicate whether symbolic links +in the file system are followed in the method. +

+

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

+ + +

+Calls RaiseSearchingError to raise an exception if the Search method has +already been called and has not completed. +

+ + + + + + + + + + + + + + + +Base path for searching files. + + + + +Mask used to determine file names that match in the search. + + + + +Indicates if subdirectories are searched recursively. + + + + +Indicates if file names are compared using case sensitivity. + + - - Character used as a delimiter between file masks. - -

- MaskSeparator is a Char property which contains the character used as a delimiter between file masks in the search criteria. The default value for the property is ';' as assigned in the Create method. -

-

- MaskSeparator is used inSearch to fill an internal TMaskList instance used in the method. -

- - - - - - TMaskList - - + + +Character used as a delimiter between file masks. + + +

+MaskSeparator is a Char property which contains the +character used as a delimiter between file masks in the search criteria. The +default value for the property is ';' as assigned in the +Create method. +

+

+MaskSeparator is used inSearch to fill an internal +TMaskList instance used in the method. +

+ + + + + +TMaskList + + - - Character used as a delimiter between directory paths. - -

- PathSeparator is a Char property which contains the character used as a delimiter between directory paths in the search criteria. The default value for the property is ';' as assigned in the Create method. -

-

- PathSeparator is used in the Search method to fill an internal TStringList instance with the directory paths specified in the search criteria. -

- - - - - - - + + +Character used as a delimiter between directory paths. + + +

+PathSeparator is a Char property which contains the +character used as a delimiter between directory paths in the search criteria. +The default value for the property is ';' as assigned in the +Create method. +

+

+PathSeparator is used in the Search method to fill an internal +TStringList instance with the directory paths specified in the +search criteria. +

+ + + + + + + - - Indicates if a search process directory paths that are symbolic links. - -

- FollowSymLink is a Boolean property which indicates if the Search method should process directory paths that are symbolic links on the local file system. The default value for the property is True as assigned in the Create method. -

-

- FollowSymLink is used in the Search method when a directory entry is detected in FileInfo that FileIsSymLink identifies as a symbolic link. When set to False, the directory is not processed; the OnDirectoryEnter event handler is not signalled and the method ignores the directory path. The OnDirectoryFound event handler is signalled for the iterator value. -

- - - - - - - FileIsSymLink - - + + +Indicates if a search process directory paths that are symbolic links. + + +

+FollowSymLink is a Boolean property which indicates if +the Search method should process directory paths that are symbolic +links on the local file system. The default value for the property is +True as assigned in the Create method. +

+

+FollowSymLink is used in the Search method when a directory entry is detected +in FileInfo that FileIsSymLink identifies as a symbolic +link. When set to False, the directory is not processed; the +OnDirectoryEnter event handler is not signalled and the +method ignores the directory path. The OnDirectoryFound event +handler is signalled for the iterator value. +

+ + + + + + +FileIsSymLink + + - - File attribute needed for any file considered a match in the Search method. - -

- FileAttribute is a Word property. The default value for the property is faAnyfile, and means that any of the file attribute constants are allowed for files. -

-

- FileAttribute is used in the Search 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 FindFirstUTF8 and FindNextUTF8. The value is compared to the file attributes returned in a TSearchRec instance from those routines. -

-

- Use DirectoryAttribute to specify the file attributes needed for directories processed in the Search method. -

- - - - - - FindFirstUTF8 - FindNextUTF8 - TSearchRec - - + + +File attribute needed for any file considered a match in the Search method. + + +

+FileAttribute is a Word property. The default value for +the property is faAnyfile, and means that any of the file +attribute constants are allowed for files. +

+

+FileAttribute is used in the Search 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 FindFirstUTF8 +and FindNextUTF8. The value is compared to the file attributes +returned in a TSearchRec instance from those routines. +

+

+Use DirectoryAttribute to specify the file attributes needed for +directories processed in the Search method. +

+ + + + + +FindFirstUTF8 +FindNextUTF8 +TSearchRec + + - - File attribute needed for directories considered a match in the Search method. - -

- DirectoryAttribute is a Word property with the file attribute needed for directories considered a match in the Search method. The default value for the property is faDirectory. -

-

- DirectoryAttribute is used in the Search 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 FindFirstUTF8 and FindNextUTF8. The value is compared to the file attributes returned in a TSearchRec instance from those routines. -

-

- Use FollowSymLink to include or exclude directories which are symbolic links on the local file system. -

-

- Use FileAttribute to set the file attributes needed for files considered a match in the Search method. -

- - - - - - FindFirstUTF8 - FindNextUTF8 - TSearchRec - - + + +File attribute needed for directories considered a match in the Search method. + + +

+DirectoryAttribute is a Word property with the file +attribute needed for directories considered a match in the Search method. The +default value for the property is faDirectory. +

+

+DirectoryAttribute is used in the Search 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 +FindFirstUTF8 and FindNextUTF8. The value is compared +to the file attributes returned in a TSearchRec instance from +those routines. +

+

+Use FollowSymLink to include or exclude directories which are +symbolic links on the local file system. +

+

+Use FileAttribute to set the file attributes needed for files +considered a match in the Search method. +

+ + + + + +FindFirstUTF8 +FindNextUTF8 +TSearchRec + + - - Event handler signalled when a new directory is found in the Search method. - -

- OnDirectoryFound is a TDirectoryFoundEvent property with the event handler signalled when a new directory is found in the Search method. It is signalled after values in the Path, FileInfo, and Level properties have been updated in the file iterator. -

-

- An application must implement and assign an object procedure to the handler to respond to the event notification. The FileIterator argument is the TFileIterator instance for the event notification, and allows access to its properties and methods. Call the Stop method in FileIterator to stop the search process. -

-

- Use OnDirectoryEnter to perform actions needed when a new directory is processed in the search method. -

- - - - - - - - - - - - + + +Event handler signalled when a new directory is found in the Search method. + + +

+OnDirectoryFound is a TDirectoryFoundEvent property +with the event handler signalled when a new directory is found in the Search +method. It is signalled after values in the Path, +FileInfo, and Level properties have been updated in the +file iterator. +

+

+An application must implement and assign an object procedure to the handler +to respond to the event notification. The FileIterator argument is +the TFileIterator instance for the event notification, and allows +access to its properties and methods. Call the Stop method in +FileIterator to stop the search process. +

+

+Use OnDirectoryEnter to perform actions needed when a new +directory is processed in the search method. +

+ + + + + + + + + + + + - - - Event handler signalled when a file matching the file mask is found in the Search method. - - -

- OnFileFound is a TFileFoundEvent 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 Path, FileInfo, and Level properties have been updated in the file iterator. -

-

- An application must implement and assign an object procedure to the handler to respond to the event notification. The FileIterator argument is the TFileIterator instance for the event notification, and allows access to its properties and methods. Call the Stop method in FileIterator to stop the search process. -

-

- Use OnDirectoryFound to respond to directory names found in the Search method. -

-

- Use OnDirectoryEnter to respond to a new directory processed in the Search method. -

- - - - - - - - - - - - - + + +Event handler signalled when a file matching the file mask is found in the +Search method. + + +

+OnFileFound is a TFileFoundEvent 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 Path, FileInfo, and Level properties +have been updated in the file iterator. +

+

+An application must implement and assign an object procedure to the handler +to respond to the event notification. The FileIterator argument is +the TFileIterator instance for the event notification, and allows +access to its properties and methods. Call the Stop method in +FileIterator to stop the search process. +

+

+Use OnDirectoryFound to respond to directory names found in the +Search method. +

+

+Use OnDirectoryEnter to respond to a new directory processed in +the Search method. +

+ + + + + + + + + + + + + - - - Event handler signalled when a new directory is processed in the Search method. - - -

- OnDirectoryEnter is a TDirectoryEnterEvent property with the event handler signalled when a new directory is processed in the Search 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. -

-

- An application must implement and assign an object procedure to the handler to respond to the event notification. The FileIterator argument is the TFileIterator instance for the event notification, and allows access to its properties and methods. Call the Stop method in FileIterator to stop the search process. -

-

- Use OnDirectoryFound to respond to directory names found in the Search method. -

-

- Use OnFileFound to respond to a new file name processed as a match in the Search method. -

- - - - - - - - - - - - - + + +Event handler signalled when a new directory is processed in the Search +method. + + +

+OnDirectoryEnter is a TDirectoryEnterEvent property +with the event handler signalled when a new directory is processed in the +Search 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. +

+

+An application must implement and assign an object procedure to the handler +to respond to the event notification. The FileIterator argument is +the TFileIterator instance for the event notification, and allows +access to its properties and methods. Call the Stop method in +FileIterator to stop the search process. +

+

+Use OnDirectoryFound to respond to directory names found in the +Search method. +

+

+Use OnFileFound to respond to a new file name processed as a match +in the Search method. +

+ + + + + + + + + + + + + - - - Stores file names matching a search criteria in a TStrings class instance. - - -

- TListFileSearcher is a TFileSearcher descendant used to used store file names matching a specified search criteria in a TStrings 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 Search method. -

- - Resources allocated to the TStrings instance must be freed by the caller. TListFileSearcher does not own or manage the resources for the TStrings instance. - - - - - - + + +Stores file names matching a search criteria in a TStrings class instance. + + +

+TListFileSearcher is a TFileSearcher descendant used to +used store file names matching a specified search criteria in a +TStrings 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 Search method. +

+ +Resources allocated to the TStrings instance must be freed by the caller. +TListFileSearcher does not own or manage the resources for the TStrings +instance. + + + + + + - - Internal list used to store matching file names in the file searcher. - + + +Internal list used to store matching file names in the file searcher. + + - - - Performs actions required to add a file name to the list of matches for the file searcher. - - -

- DoFileFound is an overridden method in TListFileSearcher. 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). -

-

- DoFileFound is called from the Search method when a file on the local file system is located that matches a given mask. -

- - - - - - - + + +Performs actions required to add a file name to the list of matches for the +file searcher. + + +

+DoFileFound is an overridden method in +TListFileSearcher. 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). +

+

+DoFileFound is called from the Search method when a file on the local file +system is located that matches a given mask. +

+ + + + + + + - - Constructor for the class instance. - -

- Create is an alternate constructor for the class instance. Create calls the inherited constructor, and stores the TStrings instance in AList to the the internal member used in the class instance. -

- - Resources allocated to the TStrings instance must be freed by the caller. TListFileSearcher does not own or manage the resources for the TStrings instance. - - - - - - TStrings class instance used to store matching file names. - + + +Constructor for the class instance. + + +

+Create is an alternate constructor for the class instance. Create +calls the inherited constructor, and stores the TStrings instance +in AList to the the internal member used in the class instance. +

+ +Resources allocated to the TStrings instance must be freed by the caller. +TListFileSearcher does not own or manage the resources for the TStrings +instance. + + + + + + +TStrings class instance used to store matching file names. + + - - - Stores directory names matching a given search criteria in a TStrings class instance. - - -

- TListDirectoriesSearcher is a TFileSearcher descendant used to store directory names matching the specified search criteria in a TStrings class instance. -

- - - + + +Stores directory names matching a given search criteria in a TStrings class +instance. + + +

+TListDirectoriesSearcher is a TFileSearcher descendant +used to store directory names matching the specified search criteria in a +TStrings class instance. +

+ + + - - Stores directory paths matching the specified search criteria. - + + +Stores directory paths matching the specified search criteria. + + - - - Performs actions needed to add a directory path to the list of matches for the searcher. - - -

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

-

- DoDirectoryFound is called from the Search method when a directory on the local file system is located that matches a given mask. -

- - - - - - - + + +Performs actions needed to add a directory path to the list of matches for +the searcher. + + +

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

+

+DoDirectoryFound is called from the Search method when a directory on the +local file system is located that matches a given mask. +

+ + + + + + + - - - Constructor for the class instance. - - -

- Create is the constructor for the class instance. Create calls the inherited constructor, and stores the value in AList to the internal member used to capture matching directory names in the class instance. -

- - Resources allocated to the TStrings instance must be freed by the caller. TListFileSearcher does not own or manage the resources for the TStrings instance. - - - - - - - TStrings class instance used to store directory names matching the specified search criteria. - - - - + + +Constructor for the class instance. + + +

+Create is the constructor for the class instance. Create calls the +inherited constructor, and stores the value in AList to the +internal member used to capture matching directory names in the class +instance. +

+ +Resources allocated to the TStrings instance must be freed by the caller. +TListFileSearcher does not own or manage the resources for the TStrings +instance. + + + + + + +TStrings class instance used to store directory names matching the specified +search criteria. + + + + - - - Returns the list of files in the specified path matching the search criteria. - - -

- FindAllFiles is an overloaded routine used to populate a TStringList 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. -

- - The function variant of FindAllFiles 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. - - - - - - - List of file names matching the search criteria. - -

- The StringList is created in the FindAllFiles function; you should not instantiate it before calling the function. -

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

- - - - Base path for searching files. - - - - A list of masks, separated by a semicolon (;) to which found files should match. - - -

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

- - - - True to search sub-directories in the process. - -

- Parameter DirAttr is int file attribute: if file-system item has this attribute(s), it is considered as a directory. It can be faDirectory, faSymLink, (faDirectory+faSymLink) or maybe another bits can be used. -

- - - - If search recursively sub directories. - + + +Returns the list of files in the specified path matching the search criteria. + + +

+FindAllFiles is an overloaded routine used to populate a +TStringList 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. +

+ +The function variant of FindAllFiles 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. + + + + + + + +List of file names matching the search criteria. + + +

+The StringList is created in the FindAllFiles function; you should not +instantiate it before calling the function. +

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

+ + + + +Base path for searching files. + + + + +A list of masks, separated by a semicolon (;) to which found files should +match. + + +

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

+ + + +True to search sub-directories in the process. + +

+Parameter DirAttr is int file attribute: if file-system item has this +attribute(s), it is considered as a directory. It can be +faDirectory, faSymLink, (faDirectory+ +faSymLink) or maybe another bits can be used. +

+ + + + +If search recursively sub directories. + + - - - Stores directory names matching the search criteria in a TStringList class instance. - - -

- FindAllDirectories is an overloaded routine used to store directory path names that match the specified search criteria in a TStringList 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. -

- - - - - Stores directory names matching the search criteria. - - - Stores directory names matching the search criteria. - - - Path(s) to the directories examined in the routine. - - - True to recurse into sub-directories in the search. - - - Delimiter used to separate path names in the SearchPath parameter. - + + +Stores directory names matching the search criteria in a TStringList class +instance. + + +

+FindAllDirectories is an overloaded routine used to store +directory path names that match the specified search criteria in a +TStringList 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. +

+ + + + + +Stores directory names matching the search criteria. + + + + +Stores directory names matching the search criteria. + + + + +Path(s) to the directories examined in the routine. + + + + +True to recurse into sub-directories in the search. + + + + +Delimiter used to separate path names in the SearchPath parameter. + + - - Contains flags used to control actions performed in CopyFile or CopyDirTree. - - - - - - - - - Overwrites the destination file if it already exists. - - - - Create the directory for the destination fie if it does not already exist. - - - - Preserves the timestamp for the source file in the destination file. - + + +Contains flags used to control actions performed in CopyFile or CopyDirTree. + + + + + + + + + + +Overwrites the destination file if it already exists. + + + + +Create the directory for the destination fie if it does not already exist. + + + + +Preserves the timestamp for the source file in the destination file. + + - - Set type used to store TCopyFileFlag enumeration values. - - - - - - - + + +Set type used to store TCopyFileFlag enumeration values. + + +

+TCopyFileFlags is a set type used to store 0 or more values from +the TCopyFileFlag enumeration. TCopyFileFlags is passed as an +argument to the CopyFile and CopyDirTree routines. +

+ + + + + + + - - Copies the source file to the destination file using the specified options. - -

- CopyFile is an overloaded Boolean function used to copy the file in SrcFilename to the destination in DestFilename. Both parameters contain a fully-qualified path with file name and extension (if needed) for the respective files. -

-

- Flags contains TCopyFileFlag value(s) that are enforced in the copy operation. The default value for the parameter is [cffOverwriteFile] and indicates that the destination file is overwritten if it already exists on the local file system. -

-

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

-

- The return value is set to True when the copy operation has been completed successfully. Otherwise, the return value is False. -

- - - An Exception is raised if the copy process does not complete successfully or correctly. - - - - Returns True if successful, False if there was an error. - - - The source file name for the copy operation. - - - The destination file name for the copy operation. - - - Set with flags enabled for the copy operation. - - - If True, the timestamp of the original file is preserved in the copied file. - - - If True, and exception is raised if the copy operation cannot be performed. - + + +Copies the source file to the destination file using the specified options. + + +

+CopyFile is an overloaded Boolean function used to copy +the file in SrcFilename to the destination in +DestFilename. Both parameters contain a fully-qualified path with +file name and extension (if needed) for the respective files. +

+

+Flags contains TCopyFileFlag value(s) that are enforced +in the copy operation. The default value for the parameter is +[cffOverwriteFile] and indicates that the destination file is +overwritten if it already exists on the local file system. +

+

+PreserveTime 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. +

+

+The return value is set to True when the copy operation has been +completed successfully. Otherwise, the return value is False. +

+ + +An Exception is raised if the copy process does not complete successfully or +correctly. + + + + +Returns True if successful, False if there was an error. + + + + +The source file name for the copy operation. + + + + +The destination file name for the copy operation. + + + + +Set with flags enabled for the copy operation. + + + + +If True, the timestamp of the original file is preserved in the copied +file. + + + + +If True, and exception is raised if the copy operation cannot be +performed. + + - - - Copies all file system entries in a source directory to the destination directory using the specified options. - - -

- CopyDirTree is a Boolean function used to copy file system entries from the directory in SourceDir to the directory in TargetDir. -

-

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

-

- Flags contains values representing the options enabled in the copy operation. The default value for the parameters is an empty set ([]) and indicates that none of the TCopyFileFlag options are enabled. The value cffCreateDestDirectory is always added to the values in Flags internally; CopyDirTree requires the destination directory to be created if it does not already exist. -

-

- See TCopyFileFlag for more information about the option values and their meanings. -

-

- The return value is True 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 False. -

-

- Use CopyFile to copy a single file with a given name to a new file name. -

- - - - - - - - True when all files are successfully copied in the routine. - - - Directory with the files copied in the routine. - - - Directory where the copied files are stored. - - - Options enabled for the copy operation; default value is an empty set [] - + + +Copies all file system entries in a source directory to the destination +directory using the specified options. + + +

+CopyDirTree is a Boolean function used to copy file +system entries from the directory in SourceDir to the directory in +TargetDir. +

+

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

+

+Flags contains values representing the options enabled in the copy operation. +The default value for the parameters is an empty set ([]) and +indicates that none of the TCopyFileFlag options are enabled. The +value cffCreateDestDirectory is always added to the values in +Flags internally; CopyDirTree requires the destination directory to be +created if it does not already exist. +

+

+See TCopyFileFlag for more information about +the option values and their meanings. +

+

+The return value is True 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 +False. +

+

+Use CopyFile to copy a single file with a given name to a new file +name. +

+ + + + + + + + +True when all files are successfully copied in the routine. + + + + +Directory with the files copied in the routine. + + + + +Directory where the copied files are stored. + + + + +Options enabled for the copy operation; default value is an empty set ([]) + + - - File extensions used for Pascal source code files. - -

- PascalFileExt is an array constant which contains the file extensions (including the initial '.') used for Pascal source code files (units). -

- - - - - + + +File extensions used for Pascal source code files. + + +

+PascalFileExt is an array constant which contains the file +extensions (including the initial '.') used for Pascal source code files +(units). +

+ + + + + - - File extensions considered to be Pascal source code. - -

- PascalSourceExt is an array constant which contains the file extensions (including the initial '.') used for Pascal source code files. Similar to PascalFileExt, but includes extensions used for project and package files. -

- - - - - + + +File extensions considered to be a Pascal source, project or package file. + + +

+PascalSourceExt is an array constant which contains the +file extensions (including the initial '.') used for Pascal source code +files. Similar to PascalFileExt, but includes extensions used for +project and package files. +

+ + + + + - - File masked used to match all directories entries on the local file system. - -

- Used in the implementation of the TFileSearcher.Search method. -

- - - - - + + +File mask used to match all directories entries on the local file system. + + +

+Used in the implementation of the TFileSearcher.Search method. +

+ + + + + - - - - + + +