Miscellaneous procedures, functions, types, and classes for manipulating files and file names

This unit contains functions, procedures, 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 defauilt system encoding. Please note that AnsiToUTF8 and UTF8ToAnsi need a widestring manager under Linux, BSD, and MacOSX. Normally these OS's use UTF-8 as system encoding so the WideStringManager is not needed.

Byte Order Mark (BOM) used at the beginning of UTF-8-encoded files When True, uppercase and lowercase file names are treated as equivalent The value is determined by the presence of the CaseInsensitiveFilenames compiler define. When True, file names can be compared using the = string operator The value is determined by the presence of the NotLiteralFilenames compiler define. CompareFileNames - compares two file names to see whether they are equal Returns zero if files are equal, or the index of differences, or the difference in length if filenames are not equal First filename Length of first filename Second filename Length of second filename ResolveLinks - if True, searches through links to find the actual file for comparison DeleteDirectory - Delete the named directory (or only its contents if OnlyChildren is True) If there was an error, such as trying to removing . or .., or there were insufficient permissions, or the file did not exist, False is returned 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 ProgramDirectory - returns the directory in which the currently running program resides Returns the name of the directory in which the current program is found FileSize - finds the size of the named file Returns the size of the file, or -1 if not there The name of the file for checking FilenameIsPascalUnit - checks that the supplied name is a correct Pascal unit name

FilenameIsPascalUnit - checks that the supplied name is a correct Pascal unit name. It examines the file extension to see if it matches one of the standard Pascal extensions (currently .p, .pp, .pas).

Returns True if the supplied name is a correct Pascal Unit filename The name of the file to examine FileIsInPath - checks that FileName refers to a file that exists within the given Path Returns True if a file named Filename exists within the given Path The name of the file for checking The Path to be searched FileIsInDirectory - checks whether a file with FileName exists within the given Directory

FileIsInDirectory - checks whether a file with FileName exists within the given Directory.

Returns True if the file is in the directory The name of the file to be checked The name of the directory to be searched for the file ExtractFileNameWithoutExt - returns just the name of the file without an 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 CreateAbsoluteSearchPath - concatenates BaseDirectory and SearchPath to form an absolute path to search for files

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 function from the LazFileUtils unit. File mask representing all files suitable for showing in a file filter. GetAllFilesMask returns a File Mask suitable for showing in a filter of a Open File Dialog. For Windows, '*.*' is returned; on other operating systems just '*'. GetExeExt - find the correct extension (including the starting .) for an executable file Returns '.exe' in Windows, nothing in other systems. 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 in 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 SearchFileInPath - searches for Filename in the given SearchPath using the supplied BasePath with the specified Delimiter and the options listed in Flags

Searches the whole path. Relative folder file names are expanded using BasePath. By default if BasePath is set it is searched as well, unless sffDontSearchInBasePath flag is present.

Returns the first file that matches the supplied criteria.

If the file does not exist, an empty string is returned Returns fully specified file name of the first file that matches the supplied criteria, or empty string if file not found The name of the file for searching The BasePathto be used for the search The path for searching The directory Delimiter to be used in the search 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 searches the whole path unless the sffDontSearchInBasePath flag is present.

Returns all files that match the supplied criteria

Returns fully specified file names of all files that match the supplied criteria, or empty string if file not found The name of the file for searching The BasePath to be used for the search The path for searching The directory Delimiter to be used in the search Flags specifying how to search: e.g. don't search in base path, case independent search FindDiskFilename - finds the file that best fits the supplied filename

FindDiskFilename - finds the file that best fits the supplied filename. Searches for the filename case on disk. The file must exist.

For example: If Filename='file' and there is only a 'File', then 'File' will be returned.

Returns the best fitting filename from the disk (taking case into consideration) The name of the file for checking 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 FindDefaultExecutablePath - 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 Class for getting info about found file or directory. Stops the searching process. If the current file is directory. Gets the current file name. Gets the current file info. Gets the current file path level relative to base search path. Gets the current file path. If the searching is in process. Class for searching files TFileSearcher is a TFileIterator descendant used to search for files that match s search mask in a given directory path. Creates new file searcher object Searches for files in specified path with passed options

Searches for files in the specified path. When a matching file is found, the OnFileFound event is invoked. For directories, the OnDirectoryFound event is signalled. You can abort the search process by calling the Stop method in either of these events.

Base path for searching files Mask used to determine file names that match in the search Indicates if sub directories are searched recursively Indicates if file names are compared using case sensitivity Character used as a delimiter between file masks in the search critera Character used as a delimiter between directory paths in the search criteria Indicates if a search should follow paths that are symbolic links FileAttribute is a Word property. The default value for the property is faAnyfile. DirectoryAttribute is a Word property. The default value for the property is faDirectory. Is invoked when directory is found. Is invoked when file is found. Event handler signalled when the searcher enters a new directory Stores file matching a search criteria in a TStrings class instance TListFileSearcher is a TFileSearcher descendant used to used store files matching a specified search criteria in a TStrings class instance. 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 Constructor for the class instance Create is the 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. TStrings class instance used to store matching file names Stores directory names matching a 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 Performs actions needed to add a directory path to the list of matches for the searcher 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. 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 method 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.

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. If search recursively sub directories 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 CopyFile - copies Source file to Destination file, optionally preserving the timestamp of the original file 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 filename for the Copy The destination filename for the Copy If True, the timestamp of the original file is preserved in the copied file PascalFileExt - typically '.pas', '.pp' or '.p' An array of file extensions considered to be Pascal source code File masked used to match all directories entries