Castle Game EngineIntroduction Units Class Hierarchy Classes, Interfaces, Objects and Records Types Variables Constants Functions and Procedures Identifiers |
Unit CastleFilesUtils
Description
Operations on files.
Includes functions to help cross-platform programs to know where to read/write files:
Uses
Overview
Classes, Interfaces, Objects and Records
Functions and Procedures
function ExeName: string; |
function ProgramName: string; |
function NormalFileExists(const fileName: string): boolean; |
function GetTempPath: string; |
function UserConfigPath: string; |
function UserConfigFile(const Extension: string): string; |
function ProgramDataPath: string; |
function IsSymLink(const FileName: string): boolean; overload; |
function HomePath: string; |
function ExpandHomePath(const FileName: string): string; |
procedure CheckDeleteFile(const FileName: string); |
procedure CheckRemoveDir(const DirFileName: string); |
procedure FileCopy(const SourceFileName, DestFileName: string; CanOverwrite: boolean); |
function TryFileCopy(const SourceFileName, DestFileName: string; CanOverwrite: boolean): boolean; |
procedure FileMove(const SourceFileName, DestFileName: string; CanOverwrite: boolean = false); overload; |
procedure ChangeDir(const NewDir: string); |
function FileNameAutoInc(const FileNamePattern: string): string; |
function FnameAutoInc(const FileNamePattern: string): string; deprecated; |
function ParentPath(DirName: string; DoExpandDirName: boolean = true): string; |
procedure SafeReset(var f: file; const filename: string; readonly: boolean; opensize: word = 1); overload; |
procedure SafeReset(var f: text; const filename: string; readonly: boolean); overload; |
procedure SafeRewrite(var f: file; const filename: string; opensize: word = 1); overload; |
procedure SafeRewrite(var f: text; const filename: string); overload; |
function CombinePaths(BasePath, RelPath: string): string; |
Function PathFileSearch(Const Name : String; ImplicitCurrentDir : Boolean = True) : String; |
procedure ScanForFiles(Path: string; const Name: string; const HandleFile: THandleFileMethod); |
Types
Constants
Description
Functions and Procedures
function ExeName: string; |
Full (absolute) filename to executable file of this program. If it's impossible to obtain, raises exception EExeNameNotAvailable.
Under Windows this is simply ParamStr(0) (and it never raises exception), but under other OSes it's not so simple to obtain (although it's important to note that usually programs under UNIX should not need this, actually).
Internal implementation notes:
Under UNIXes other than Linux I don't know how to obtain this, so e.g. under FreeBSD this will always raise an exception. Under Linux I'm trying to read file /proc/getpid()/exe, this should work under most Linuxes as long as user compiled Linux kernel with /proc support. So under Linux this may work, but still you should be always prepared that it may raise EExeNameNotAvailable.
|
function ProgramName: string; |
A name of our program.
Suitable to show to user. Should also indicate how to run the program, that is: should be the basename of the executable (although we do depend on it technically, but some log messages may suggest it). Also suitable to derive config/data paths for this program.
Right now this is simply equivalent to FPC's ApplicationName. We had a complicated mechanisms for this in earlier versions, but ultimately the FPC's ApplicationName approach, which is fully configurable by callback OnGetApplicationName and has a nice default, is good.
|
function NormalFileExists(const fileName: string): boolean; |
Returns true if file exists and is a normal file. Detects and returns False for special Windows files like 'con', 'c:\con', 'c:\somedir\con' etc. ('con' is a special device name). For all other files (and other OSes) this function returns the same as FileExists.
|
function GetTempPath: string; |
Directory suitable for creating temporary files/directories. Note that this directory is shared by other programs, so be careful when creating here anything — to minimize name conflicts usually all filenames created here should start with ApplicationName and then should follow things like process id (or sometimes user name, when you can guarantee that one user runs always only one instance of this program) or some random number.
Also remember that good program should avoid creating temporary files — you should keep your content in memory, and store in it filesystem only when user really wants to. One exception to this rule is when program must cooperate with other program, sometimes the only possible (or stable, or fast) way to do this is by use of temporary files.
Always ends with trailing PathDelim.
|
function UserConfigPath: string; |
Path to store user configuration files. This is some directory that is probably writeable and that is a standard directory under this OS to put user config files. Always returns absolute (not relative) path. Result contains trailing PathDelim.
Right now, this is simply a comfortable wrapper around FPC's GetAppConfigDir, making sure dir exists and we return it with final path delimiter. Which means we look at OnGetApplicationName, and we use OS-specific algorithm, see http://www.freepascal.org/docs-html/rtl/sysutils/ongetapplicationname.html . On UNIX this follows XDG Base Directory Specification, see http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html (in short: look inside ˜/.config/<application-name>/).
|
function UserConfigFile(const Extension: string): string; |
Filename to store user configuration. Always returns absolute (not relative) path.
Returns filename that:
|
function ProgramDataPath: string; |
Path to access installed data files. Returns absolute path, containing trailing PathDelim.
Based on ApplicationName (and possibly ExeName under Windows). Here are details:
(Note that in normal circumstances such details are treated as internal implementation notes that shouldn't be exposed... But in case of this function, they must be exposed, since user and programmer must know how this function works (and usually it should be described in documentation of a program).)
Under Windows: returns ExtractFilePath(ExeName).
Under UNIXes: tries these three locations, in order:
HomePath +'.' +ApplicationName+'.data/' . If such directory exists, it is returned.
This is checked first, to allow local user to always override system-wide installation of my program with his own installation. E.g. consider the situation when an old version of my program is installed system-wide in /usr/local/share/my_program/, but some user (with no access to root account) wants to install a newer version of it for himself. Now he can do it, because ˜/.my_program.data/ is checked 1st, system-wide /usr/local/share/my_program/ is used only if ˜/.my_program.data/ does not exist.
'/usr/local/share/' +ApplicationName+ '/' . If such directory exists, it is returned.
This is suitable for system-wide installations without package manager.
'/usr/share/' +ApplicationName+ '/' . If such directory exists, it is returned.
This is suitable for system-wide installations with package manager.
As a last resort, we return the current directory. This always exists, and is an easy way for users to run my game without making any symlinks.
Although conceptually this should be checked first (even before HomePath +'.' +ApplicationName+'.data/' ), as it's "most local", but we can't: current directory always exists. To remedy this, we would need to know some filename inside this directory that is required to exist. Maybe for later.
|
function IsSymLink(const FileName: string): boolean; overload; |
Is FileName a symbolic link.
|
function HomePath: string; |
User's home directory, with trailing PathDelim.
Taken from $HOME, unless $HOME = '' or is not defined, then I'm trying to take this from user-database by real-uid. This is what bash does (more-or-less, when home directory does not exist strange things happen), that's what programs should do according to `info libc' and my (Kambi's) preferences.
|
function ExpandHomePath(const FileName: string): string; |
Expand tilde (˜) in path, just like shell. Expands ˜ to ExclPathDelim(HomePath) under UNIX. Under Windows, does nothing.
|
procedure CheckDeleteFile(const FileName: string); |
Call SysUtils.DeleteFile and check result.
Exceptions raised
Exception
- If delete failed.
|
procedure CheckRemoveDir(const DirFileName: string); |
Call RemoveDir and check result.
Exceptions raised
Exception
- If delete failed.
|
procedure FileCopy(const SourceFileName, DestFileName: string; CanOverwrite: boolean); |
Copy file. If CanOverwrite than the destination wil be overwritten if exists.
Cannot copy a directory for now.
Exceptions raised
- EFileExists
- If file exists and CanOverwrite =
False .
Exception
- In case of various errors.
|
function TryFileCopy(const SourceFileName, DestFileName: string; CanOverwrite: boolean): boolean; |
Copy file. Like FileCopy, but returns False when failed (no exception).
|
procedure FileMove(const SourceFileName, DestFileName: string; CanOverwrite: boolean = false); overload; |
Move or rename the file. Allows to move files and directories, also across disks (partitions). If possible, will do a fast move ("rename" under Unix, MoveFile under Windows), but if not possible it will make copy and then delete.
DestFileName will be overwritten if exists and CanOverwrite. If exists and CanOverwrite = False then EFileExists is raised.
Notes: if SourceFileName and DestFileName are two names of the same file, the situation may be undefined. So says docs for Libc, I don't know what really happens with FPC's Unix/BaseUnix stuff.
TODO: moving dirs is actually not implemented (well, sometimes may work but not generally). Use only for files now.
Exceptions raised
- EFileExists
- If file exists and CanOverwrite =
False .
Exception
- In case of various errors.
|
procedure ChangeDir(const NewDir: string); |
Change directory, raising exception if not possible. NewDir may (but doesn't have to) include trailing PathDelim.
Improvements over ChDir:
Fixes a bug in Delphi 6, in Delphi 6 ChDir when fails (and program is compiled in $I+) does not raise EInOutError (but it sets IOResult).
Fixes a bug in FPC 2.4.2-2.4.4: http://bugs.freepascal.org/view.php?id=19977 , causing EInOutError to be deferred to later I/O call.
Better error message (that will always contain NewDir).
Exceptions raised
EInOutError
- If changing dir is not possible.
|
function FileNameAutoInc(const FileNamePattern: string): string; |
Substitute %d in given filename pattern with successive numbers, until the filename doesn't exist.
The idea is to start with number = 0 and do Format(FileNamePattern, [number]) , until you find non-existing filename. Example filename pattern is screenshot_%d.png , by saving to this filename you're relatively sure that each save goes to a new file. Since we use standard Format function, you can use e.g. screenshot_%04d.png to have a number inside the filename always at least 4 digits long.
Note that it's possible on every OS that some other program, or a second copy of your own program, will write to the filename between FileNameAutoInc determined it doesn't exist and you opened the file. So using this cannot guarantee that you really always write to a new file (use proper file open modes for this).
|
function FnameAutoInc(const FileNamePattern: string): string; deprecated; |
Warning: this symbol is deprecated.
Deprecated name for FileNameAutoInc.
|
function ParentPath(DirName: string; DoExpandDirName: boolean = true): string; |
Parent directory name.
Given DirName may be absolute or relative. Given DirName may but doesn't have to include trailing PathDelim. Result is always absolute filename, and contains trailing PathDelim.
Returns the same DirName if there's no parent directory.
When DoExpandDirName = false then it is assumed that DirName already is absolute path. Then this function is pure string-operation (no actual reading of any filesystem info), so it works faster and DirName does not need to exist.
|
procedure SafeReset(var f: file; const filename: string; readonly: boolean; opensize: word = 1); overload; |
Safely open files. Does Assign and then resets/rewrites a file.
SafeReset sets always FileMode variable (to fmOpenRead if ReadOnly, or fmOpenReadWrite if not ReadOnly). This is important, and too easy to forget otherwise.
For undefined files, default size is 1, not the strange default 128.
Exceptions raised
- EFileOpenError
- In case of error. Error message is nice and contains filename, contrary to standard EInOutError.
|
procedure SafeReset(var f: text; const filename: string; readonly: boolean); overload; |
|
procedure SafeRewrite(var f: file; const filename: string; opensize: word = 1); overload; |
|
procedure SafeRewrite(var f: text; const filename: string); overload; |
|
function CombinePaths(BasePath, RelPath: string): string; |
Combines BasePath with RelPath into complete path. BasePath MUST be an absolute path, on Windows it must contain at least drive specifier (like 'c:'), on Unix it must begin with "/". RelPath can be relative and can be absolute. If RelPath is absolute, result is RelPath. Else the result is an absolute path calculated by combining RelPath with BasePath.
|
procedure ScanForFiles(Path: string; const Name: string; const HandleFile: THandleFileMethod); |
Scan recursively subdirectories of given path for files named Name. For each file, the HandleFile method is called, with filename (given filename is relative or absolute, just like given Path parameter).
|
Types
THandleFileMethod = procedure (const FileName: string) of object; |
|
Constants
RegularFileAttr = faReadOnly or faHidden or faArchive; |
|
RegularWriteableFileAttr = RegularFileAttr and (not faReadOnly); |
Regular file that is possibly writeable. Possibly writeable, not writeable for sure.
|
faReallyAnyFile = faAnyFile or faSymLink; |
Any file, including symlinks.
|
Generated by PasDoc 0.12.1 on 2013-02-04 20:26:50
|