Sign in Join
Wiki copytemporary

fileutil: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

OldNewLine
1-The Lazarus **FileUtil** unit contains functions and procedures to maintain compatibility with Delphi's FileUtil unit. File routines that specifically deal with UTF8 file names should go into the [[LazFileUtils]] unit.
1+The Lazarus **FileUtil** unit contains functions and procedures to maintain compatibility with Delphi's FileUtil unit. File routines that specifically deal with UTF8 file names should go into the [[LazFileUtils]] unit.
22
33## List of functions
4-```
5-// file attributes and states
6- function CompareFilenames(const Filename1, Filename2: string): integer; inline;
7- function CompareFilenamesIgnoreCase(const Filename1, Filename2: string): integer; inline;
8- function CompareFilenames(const Filename1, Filename2: string; ResolveLinks: boolean): integer;
9- function CompareFilenames(Filename1: PChar; Len1: integer; Filename2: PChar; Len2: integer; ResolveLinks: boolean): integer;
10- function FilenameIsAbsolute(const TheFilename: string):boolean; inline;
11- function FilenameIsWinAbsolute(const TheFilename: string):boolean; inline;
12- function FilenameIsUnixAbsolute(const TheFilename: string):boolean; inline;
13- procedure CheckIfFileIsExecutable(const AFilename: string); inline;
14- procedure CheckIfFileIsSymlink(const AFilename: string); inline;
15- function FileIsReadable(const AFilename: string): boolean; inline;
16- function FileIsWritable(const AFilename: string): boolean; inline;
17- function FileIsText(const AFilename: string): boolean; inline;
18- function FileIsText(const AFilename: string; out FileReadable: boolean): boolean; inline;
19- function FileIsExecutable(const AFilename: string): boolean; inline;
20- function FileIsSymlink(const AFilename: string): boolean; inline;
21- function FileIsHardLink(const AFilename: string): boolean; inline;
22- function FileSize(const Filename: string): int64; overload; inline;
23- function GetFileDescription(const AFilename: string): string; inline;
24- function ReadAllLinks(const Filename: string; ExceptionOnError: boolean): string; // if a link is broken returns ''
25- function TryReadAllLinks(const Filename: string): string; // if a link is broken returns Filename
26-
27- // directories
28- function DirPathExists(const FileName: String): Boolean; inline;
29- function ForceDirectory(DirectoryName: string): boolean; inline;
30- function DeleteDirectory(const DirectoryName: string; OnlyChildren: boolean): boolean;
31- function ProgramDirectory: string;
32- function DirectoryIsWritable(const DirectoryName: string): boolean; inline;
33-
34- // filename parts
35- function ExtractFileNameOnly(const AFilename: string): string; inline;
36- function ExtractFileNameWithoutExt(const AFilename: string): string;
37- function CompareFileExt(const Filename, Ext: string; CaseSensitive: boolean): integer; overload; inline;
38- function CompareFileExt(const Filename, Ext: string): integer; overload; inline;
39- function FilenameIsPascalUnit(const Filename: string): boolean;
40- function AppendPathDelim(const Path: string): string; inline;
41- function ChompPathDelim(const Path: string): string; inline;
42- function TrimFilename(const AFilename: string): string; inline;
43- function CleanAndExpandFilename(const Filename: string): string; inline;
44- function CleanAndExpandDirectory(const Filename: string): string; inline;
45- function CreateAbsoluteSearchPath(const SearchPath, BaseDirectory: string): string;
46- function CreateRelativePath(const Filename, BaseDirectory: string; UsePointDirectory: boolean = false; AlwaysRequireSharedBaseFolder: Boolean = True): string; inline;
47- function CreateAbsolutePath(const Filename, BaseDirectory: string): string;
48- function FileIsInPath(const Filename, Path: string): boolean;
49- function FileIsInDirectory(const Filename, Directory: string): boolean;
50-
51- // file search
52- type
53- TSearchFileInPathFlag = (
54- sffDontSearchInBasePath,
55- sffSearchLoUpCase
56- );
57- TSearchFileInPathFlags = set of TSearchFileInPathFlag;
58- const
59- AllDirectoryEntriesMask = '*';
60-
61- function GetAllFilesMask: string; inline;
62- function GetExeExt: string; inline;
63- function SearchFileInPath(const Filename, BasePath, SearchPath, Delimiter: string; Flags: TSearchFileInPathFlags): string;
64- function SearchAllFilesInPath(const Filename, BasePath, SearchPath, Delimiter: string; Flags: TSearchFileInPathFlags): TStrings;
65- function FindDiskFilename(const Filename: string): string;
66- function FindDiskFileCaseInsensitive(const Filename: string): string;
67- function FindDefaultExecutablePath(const Executable: string; const BaseDir: string = ''): string;
68-
69- type
70- TFileIterator = class
71- private
72- FPath: String;
73- FLevel: Integer;
74- FFileInfo: TSearchRec;
75- FSearching: Boolean;
76- function GetFileName: String;
77- public
78- procedure Stop;
79- function IsDirectory: Boolean;
80- public
81- property FileName: String read GetFileName;
82- property FileInfo: TSearchRec read FFileInfo;
83- property Level: Integer read FLevel;
84- property Path: String read FPath;
85- property Searching: Boolean read FSearching;
86- end;
87-
88- TFileFoundEvent = procedure (FileIterator: TFileIterator) of object;
89- TDirectoryFoundEvent = procedure (FileIterator: TFileIterator) of object;
90- TDirectoryEnterEvent = procedure (FileIterator: TFileIterator) of object;
91-
92- TFileSearcher = class(TFileIterator)
93- private
94- FMaskSeparator: char;
95- FFollowSymLink: Boolean;
96- FOnFileFound: TFileFoundEvent;
97- FOnDirectoryFound: TDirectoryFoundEvent;
98- FOnDirectoryEnter: TDirectoryEnterEvent;
99- FFileAttribute: Word;
100- FDirectoryAttribute: Word;
101- procedure RaiseSearchingError;
102- protected
103- procedure DoDirectoryEnter; virtual;
104- procedure DoDirectoryFound; virtual;
105- procedure DoFileFound; virtual;
106- public
107- constructor Create;
108- procedure Search(const ASearchPath: String; ASearchMask: String = '';
109- ASearchSubDirs: Boolean = True; CaseSensitive: Boolean = False);
110- public
111- property MaskSeparator: char read FMaskSeparator write FMaskSeparator;
112- property FollowSymLink: Boolean read FFollowSymLink write FFollowSymLink;
113- property FileAttribute: Word read FFileAttribute write FFileAttribute default faAnyfile;
114- property DirectoryAttribute: Word read FDirectoryAttribute write FDirectoryAttribute default faDirectory;
115- property OnDirectoryFound: TDirectoryFoundEvent read FOnDirectoryFound write FOnDirectoryFound;
116- property OnFileFound: TFileFoundEvent read FOnFileFound write FOnFileFound;
117- property OnDirectoryEnter: TDirectoryEnterEvent read FOnDirectoryEnter write FOnDirectoryEnter;
118- end;
119-
120- function [[FindAllFiles]]( const SearchPath: String; SearchMask: String = ''; SearchSubDirs: Boolean = True): TStringList;
121- function FindAllDirectories(const SearchPath: string; SearchSubDirs: Boolean = True): TStringList;
122-
123- // Copy a file or a whole directory tree
124- function [[CopyFile]](const SrcFilename, DestFilename: string; Flags: TCopyFileFlags=[cffOverwriteFile]): boolean;
125- function [[CopyFile]](const SrcFilename, DestFilename: string; PreserveTime: boolean): boolean;
126- function CopyDirTree(const SourceDir, TargetDir: string; Flags: TCopyFileFlags=[]): Boolean;
127-
128- // file actions
129- function ReadFileToString(const Filename: string): string;
130- function GetTempFilename(const Directory, Prefix: string): string; inline;
131-
132- // basic functions similar to the RTL but working with UTF-8 instead of the system encoding
133- // AnsiToUTF8 and UTF8ToAnsi need a widestring manager under Linux, BSD, MacOSX
134- // but normally these OS use UTF-8 as system encoding so the widestringmanager is not needed.
135- function NeedRTLAnsi: boolean; inline;// true if system encoding is not UTF-8
136- procedure SetNeedRTLAnsi(NewValue: boolean); inline;
137- function UTF8ToSys(const s: string): string; inline;// as UTF8ToAnsi but more independent of widestringmanager
138- function SysToUTF8(const s: string): string; inline;// as AnsiToUTF8 but more independent of widestringmanager
139- function ConsoleToUTF8(const s: string): string; inline;// converts OEM encoded string to UTF8 (used with some Windows specific functions )
140- function UTF8ToConsole(const s: string): string; inline;// converts UTF8 string to console encoding (used by Write, WriteLn)
141-
142- // file operations
143- function FileExistsUTF8(const Filename: string): boolean; inline;
144- function FileAgeUTF8(const FileName: string): Longint; inline;
145- function DirectoryExistsUTF8(const Directory: string): Boolean; inline;
146- function ExpandFileNameUTF8(const FileName: string): string; inline;
147- function ExpandUNCFileNameUTF8(const FileName: string): string;
148- function ExtractShortPathNameUTF8(Const FileName : String) : String;
149- function FindFirstUTF8(const Path: string; Attr: Longint; out Rslt: TSearchRec): Longint; inline;
150- function FindNextUTF8(var Rslt: TSearchRec): Longint; inline;
151- procedure FindCloseUTF8(var F: TSearchrec); inline;
152- function FileSetDateUTF8(const FileName: String; Age: Longint): Longint; inline;
153- function FileGetAttrUTF8(const FileName: String): Longint; inline;
154- function FileSetAttrUTF8(const Filename: String; Attr: longint): Longint; inline;
155- function DeleteFileUTF8(const FileName: String): Boolean; inline;
156- function RenameFileUTF8(const OldName, NewName: String): Boolean; inline;
157- function FileSearchUTF8(const Name, DirList : String; ImplicitCurrentDir : Boolean = True): String; inline;
158- function FileIsReadOnlyUTF8(const FileName: String): Boolean; inline;
159- function GetCurrentDirUTF8: String; inline;
160- function SetCurrentDirUTF8(const NewDir: String): Boolean; inline;
161- function CreateDirUTF8(const NewDir: String): Boolean; inline;
162- function RemoveDirUTF8(const Dir: String): Boolean; inline;
163- function ForceDirectoriesUTF8(const Dir: string): Boolean; inline;
164- function FileOpenUTF8(Const FileName : string; Mode : Integer) : THandle; inline;
165- function FileCreateUTF8(Const FileName : string) : THandle; overload; inline;
166- function FileCreateUTF8(Const FileName : string; Rights: Cardinal) : THandle; overload; inline;
167-
168- // environment
169- function ParamStrUTF8(Param: Integer): string; inline;
170- function GetEnvironmentStringUTF8(Index: Integer): string; inline;
171- function GetEnvironmentVariableUTF8(const EnvVar: string): String; inline;
172- function GetAppConfigDirUTF8(Global: Boolean; Create: boolean = false): string; inline;
173- function GetAppConfigFileUTF8(Global: Boolean; SubDir: boolean = false; CreateDir: boolean = false): string; inline;
174-
175- // other
176- function SysErrorMessageUTF8(ErrorCode: Integer): String; inline;
4+
5+``` pascal
6+ // file attributes and states
7+ function CompareFilenames(const Filename1, Filename2: string): integer; inline;
8+ function CompareFilenamesIgnoreCase(const Filename1, Filename2: string): integer; inline;
9+ function CompareFilenames(const Filename1, Filename2: string; ResolveLinks: boolean): integer;
10+ function CompareFilenames(Filename1: PChar; Len1: integer; Filename2: PChar; Len2: integer; ResolveLinks: boolean): integer;
11+ function FilenameIsAbsolute(const TheFilename: string):boolean; inline;
12+ function FilenameIsWinAbsolute(const TheFilename: string):boolean; inline;
13+ function FilenameIsUnixAbsolute(const TheFilename: string):boolean; inline;
14+ procedure CheckIfFileIsExecutable(const AFilename: string); inline;
15+ procedure CheckIfFileIsSymlink(const AFilename: string); inline;
16+ function FileIsReadable(const AFilename: string): boolean; inline;
17+ function FileIsWritable(const AFilename: string): boolean; inline;
18+ function FileIsText(const AFilename: string): boolean; inline;
19+ function FileIsText(const AFilename: string; out FileReadable: boolean): boolean; inline;
20+ function FileIsExecutable(const AFilename: string): boolean; inline;
21+ function FileIsSymlink(const AFilename: string): boolean; inline;
22+ function FileIsHardLink(const AFilename: string): boolean; inline;
23+ function FileSize(const Filename: string): int64; overload; inline;
24+ function GetFileDescription(const AFilename: string): string; inline;
25+ function ReadAllLinks(const Filename: string; ExceptionOnError: boolean): string; // if a link is broken returns ''
26+ function TryReadAllLinks(const Filename: string): string; // if a link is broken returns Filename
27+
28+ // directories
29+ function DirPathExists(const FileName: String): Boolean; inline;
30+ function ForceDirectory(DirectoryName: string): boolean; inline;
31+ function DeleteDirectory(const DirectoryName: string; OnlyChildren: boolean): boolean;
32+ function ProgramDirectory: string;
33+ function DirectoryIsWritable(const DirectoryName: string): boolean; inline;
34+
35+ // filename parts
36+ function ExtractFileNameOnly(const AFilename: string): string; inline;
37+ function ExtractFileNameWithoutExt(const AFilename: string): string;
38+ function CompareFileExt(const Filename, Ext: string; CaseSensitive: boolean): integer; overload; inline;
39+ function CompareFileExt(const Filename, Ext: string): integer; overload; inline;
40+ function FilenameIsPascalUnit(const Filename: string): boolean;
41+ function AppendPathDelim(const Path: string): string; inline;
42+ function ChompPathDelim(const Path: string): string; inline;
43+ function TrimFilename(const AFilename: string): string; inline;
44+ function CleanAndExpandFilename(const Filename: string): string; inline;
45+ function CleanAndExpandDirectory(const Filename: string): string; inline;
46+ function CreateAbsoluteSearchPath(const SearchPath, BaseDirectory: string): string;
47+ function CreateRelativePath(const Filename, BaseDirectory: string; UsePointDirectory: boolean = false; AlwaysRequireSharedBaseFolder: Boolean = True): string; inline;
48+ function CreateAbsolutePath(const Filename, BaseDirectory: string): string;
49+ function FileIsInPath(const Filename, Path: string): boolean;
50+ function FileIsInDirectory(const Filename, Directory: string): boolean;
51+
52+ // file search
53+ type
54+ TSearchFileInPathFlag = (
55+ sffDontSearchInBasePath,
56+ sffSearchLoUpCase
57+ );
58+ TSearchFileInPathFlags = set of TSearchFileInPathFlag;
59+ const
60+ AllDirectoryEntriesMask = '*';
61+
62+ function GetAllFilesMask: string; inline;
63+ function GetExeExt: string; inline;
64+ function SearchFileInPath(const Filename, BasePath, SearchPath, Delimiter: string; Flags: TSearchFileInPathFlags): string;
65+ function SearchAllFilesInPath(const Filename, BasePath, SearchPath, Delimiter: string; Flags: TSearchFileInPathFlags): TStrings;
66+ function FindDiskFilename(const Filename: string): string;
67+ function FindDiskFileCaseInsensitive(const Filename: string): string;
68+ function FindDefaultExecutablePath(const Executable: string; const BaseDir: string = ''): string;
69+
70+ type
71+ TFileIterator = class
72+ private
73+ FPath: String;
74+ FLevel: Integer;
75+ FFileInfo: TSearchRec;
76+ FSearching: Boolean;
77+ function GetFileName: String;
78+ public
79+ procedure Stop;
80+ function IsDirectory: Boolean;
81+ public
82+ property FileName: String read GetFileName;
83+ property FileInfo: TSearchRec read FFileInfo;
84+ property Level: Integer read FLevel;
85+ property Path: String read FPath;
86+ property Searching: Boolean read FSearching;
87+ end;
88+
89+ TFileFoundEvent = procedure (FileIterator: TFileIterator) of object;
90+ TDirectoryFoundEvent = procedure (FileIterator: TFileIterator) of object;
91+ TDirectoryEnterEvent = procedure (FileIterator: TFileIterator) of object;
92+
93+ TFileSearcher = class(TFileIterator)
94+ private
95+ FMaskSeparator: char;
96+ FFollowSymLink: Boolean;
97+ FOnFileFound: TFileFoundEvent;
98+ FOnDirectoryFound: TDirectoryFoundEvent;
99+ FOnDirectoryEnter: TDirectoryEnterEvent;
100+ FFileAttribute: Word;
101+ FDirectoryAttribute: Word;
102+ procedure RaiseSearchingError;
103+ protected
104+ procedure DoDirectoryEnter; virtual;
105+ procedure DoDirectoryFound; virtual;
106+ procedure DoFileFound; virtual;
107+ public
108+ constructor Create;
109+ procedure Search(const ASearchPath: String; ASearchMask: String = '';
110+ ASearchSubDirs: Boolean = True; CaseSensitive: Boolean = False);
111+ public
112+ property MaskSeparator: char read FMaskSeparator write FMaskSeparator;
113+ property FollowSymLink: Boolean read FFollowSymLink write FFollowSymLink;
114+ property FileAttribute: Word read FFileAttribute write FFileAttribute default faAnyfile;
115+ property DirectoryAttribute: Word read FDirectoryAttribute write FDirectoryAttribute default faDirectory;
116+ property OnDirectoryFound: TDirectoryFoundEvent read FOnDirectoryFound write FOnDirectoryFound;
117+ property OnFileFound: TFileFoundEvent read FOnFileFound write FOnFileFound;
118+ property OnDirectoryEnter: TDirectoryEnterEvent read FOnDirectoryEnter write FOnDirectoryEnter;
119+ end;
120+
121+ function [[FindAllFiles]]( const SearchPath: String; SearchMask: String = ''; SearchSubDirs: Boolean = True): TStringList;
122+ function FindAllDirectories(const SearchPath: string; SearchSubDirs: Boolean = True): TStringList;
123+
124+ // Copy a file or a whole directory tree
125+ function [[CopyFile]](const SrcFilename, DestFilename: string; Flags: TCopyFileFlags=[cffOverwriteFile]): boolean;
126+ function [[CopyFile]](const SrcFilename, DestFilename: string; PreserveTime: boolean): boolean;
127+ function CopyDirTree(const SourceDir, TargetDir: string; Flags: TCopyFileFlags=[]): Boolean;
128+
129+ // file actions
130+ function ReadFileToString(const Filename: string): string;
131+ function GetTempFilename(const Directory, Prefix: string): string; inline;
132+
133+ // basic functions similar to the RTL but working with UTF-8 instead of the system encoding
134+ // AnsiToUTF8 and UTF8ToAnsi need a widestring manager under Linux, BSD, MacOSX
135+ // but normally these OS use UTF-8 as system encoding so the widestringmanager is not needed.
136+ function NeedRTLAnsi: boolean; inline;// true if system encoding is not UTF-8
137+ procedure SetNeedRTLAnsi(NewValue: boolean); inline;
138+ function UTF8ToSys(const s: string): string; inline;// as UTF8ToAnsi but more independent of widestringmanager
139+ function SysToUTF8(const s: string): string; inline;// as AnsiToUTF8 but more independent of widestringmanager
140+ function ConsoleToUTF8(const s: string): string; inline;// converts OEM encoded string to UTF8 (used with some Windows specific functions )
141+ function UTF8ToConsole(const s: string): string; inline;// converts UTF8 string to console encoding (used by Write, WriteLn)
142+
143+ // file operations
144+ function FileExistsUTF8(const Filename: string): boolean; inline;
145+ function FileAgeUTF8(const FileName: string): Longint; inline;
146+ function DirectoryExistsUTF8(const Directory: string): Boolean; inline;
147+ function ExpandFileNameUTF8(const FileName: string): string; inline;
148+ function ExpandUNCFileNameUTF8(const FileName: string): string;
149+ function ExtractShortPathNameUTF8(Const FileName : String) : String;
150+ function FindFirstUTF8(const Path: string; Attr: Longint; out Rslt: TSearchRec): Longint; inline;
151+ function FindNextUTF8(var Rslt: TSearchRec): Longint; inline;
152+ procedure FindCloseUTF8(var F: TSearchrec); inline;
153+ function FileSetDateUTF8(const FileName: String; Age: Longint): Longint; inline;
154+ function FileGetAttrUTF8(const FileName: String): Longint; inline;
155+ function FileSetAttrUTF8(const Filename: String; Attr: longint): Longint; inline;
156+ function DeleteFileUTF8(const FileName: String): Boolean; inline;
157+ function RenameFileUTF8(const OldName, NewName: String): Boolean; inline;
158+ function FileSearchUTF8(const Name, DirList : String; ImplicitCurrentDir : Boolean = True): String; inline;
159+ function FileIsReadOnlyUTF8(const FileName: String): Boolean; inline;
160+ function GetCurrentDirUTF8: String; inline;
161+ function SetCurrentDirUTF8(const NewDir: String): Boolean; inline;
162+ function CreateDirUTF8(const NewDir: String): Boolean; inline;
163+ function RemoveDirUTF8(const Dir: String): Boolean; inline;
164+ function ForceDirectoriesUTF8(const Dir: string): Boolean; inline;
165+ function FileOpenUTF8(Const FileName : string; Mode : Integer) : THandle; inline;
166+ function FileCreateUTF8(Const FileName : string) : THandle; overload; inline;
167+ function FileCreateUTF8(Const FileName : string; Rights: Cardinal) : THandle; overload; inline;
168+
169+ // environment
170+ function ParamStrUTF8(Param: Integer): string; inline;
171+ function GetEnvironmentStringUTF8(Index: Integer): string; inline;
172+ function GetEnvironmentVariableUTF8(const EnvVar: string): String; inline;
173+ function GetAppConfigDirUTF8(Global: Boolean; Create: boolean = false): string; inline;
174+ function GetAppConfigFileUTF8(Global: Boolean; SubDir: boolean = false; CreateDir: boolean = false): string; inline;
175+
176+ // other
177+ function SysErrorMessageUTF8(ErrorCode: Integer): String; inline;
177178```
178179
179180## How to use the unit
180181
181-To enable FileUtil in a project, just add LazUtils into required package. Follow this steps:
182+To enable FileUtil in a project, just add LazUtils into required package. Follow this steps:
182183
183-1- Go to Lazarus IDE Menu "Project > Project Inspector".
184+1- Go to Lazarus IDE Menu "Project \> Project Inspector".
184185
185-[![FindAllFiles01.png](/wiki-images/d/d0/FindAllFiles01.png)](</File:FindAllFiles01.png>)
186+![](/wiki-images/d/d0/FindAllFiles01.png)
186187
187-2- In the "Project Inspector" dialog window, click "Add > New Requirement".
188+2- In the "Project Inspector" dialog window, click "Add \> New Requirement".
188189
189-[![FindAllFiles02.png](/wiki-images/3/36/FindAllFiles02.png)](</File:FindAllFiles02.png>)
190+![](/wiki-images/3/36/FindAllFiles02.png)
190191
191-3- In the "New Requirement" dialog window, find LazUtils package then click OK.
192+3- In the "New Requirement" dialog window, find LazUtils package then click OK.
192193
193-[![FindAllFiles03.png](/wiki-images/1/1c/FindAllFiles03.png)](</File:FindAllFiles03.png>)
194+![](/wiki-images/1/1c/FindAllFiles03.png)
194195
195-4- You can now add _FileUtil_ in a _Uses_ clause.
196+4- You can now add *FileUtil* in a *Uses* clause.
196197
197198---
198-*From the Free Pascal wiki, page "fileutil", as the Internet Archive kept it on 2024-03-04. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*
199+*From the Free Pascal wiki, page "fileutil", as it stood on 2022-01-21 after a change by Alextp, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*

Back to history