Castle Game Engine: CastleFilesUtils

# Unit CastleFilesUtils
Description | Uses | Classes, Interfaces, Objects and Records | Functions and Procedures | Types | Constants | Variables
## Description Operations on files. Includes functions to help cross-platform programs to know where to read/write files: ApplicationConfig – user config files ApplicationData – installed program's data files List of things to do / not to do if you want to write truly cross-platform program (that also handles URLs everywhere): Never use things like ParamStr(0), or Lazarus Application.ExeName. If you really want the filename of your executable, we have CastleFilesUtils.ExeName, but this also should not be depended on (it may raise exception on some OSes). If you want a nice application name, use SysUtils.ApplicationName (our units use it too). If you want to load program data or save program config, it's best to use ApplicationConfig and ApplicationData for all paths. Do not use standard FindFirst/FindNext. If you need to search a directory for some files, use CastleFindFiles unit. But it only works for local filesystems (or Android assets filesystem), of course you cannot search for files within http URLs. So in general avoid such file searching. Read / write all data using streams (TStream) descendants. Open and save these streams using our CastleDownload unit. ## Uses BaseUnix Unix SysUtils CastleUtils ## Overview ### Classes, Interfaces, Objects and Records
Name | Description
--- | ---
Class `EExeNameNotAvailable` |
### Functions and Procedures
`function ExeName: string;`
`function ProgramName: string; deprecated;`
`function NormalFileExists(const fileName: string): boolean; deprecated;`
`function UserConfigPath: string; deprecated;`
`function UserConfigFile(const Extension: string): string; deprecated;`
`function ProgramDataPath: string; deprecated;`
`function ApplicationConfig(const Path: string): string;`
`function ApplicationData(const Path: string): string;`
`function HomePath: string;`
`function ExpandHomePath(const FileName: string): string;`
`procedure CheckDeleteFile(const FileName: string; const Warn: boolean = false);`
`procedure CheckRemoveDir(const DirFileName: string);`
`procedure CheckForceDirectories(const Dir: string);`
`procedure CheckRenameFile(const Source, Dest: string);`
`procedure RemoveNonEmptyDir(const DirName: string);`
`function FileNameAutoInc(const FileNamePattern: string): string;`
`function FnameAutoInc(const FileNamePattern: string): string; deprecated;`
`function ParentPath(DirName: string; DoExpandDirName: boolean = true): string;`
`function CombinePaths(BasePath, RelPath: string): string; deprecated;`
`Function PathFileSearch(Const Name : String; ImplicitCurrentDir : Boolean = True) : String;`
`function FindExe(const ExeName: string): string;`
`function GetTempFileNameCheck: string;`
`function GetTempFileNamePrefix: string;`
## 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; deprecated;`
Warning: this symbol is deprecated. The name of our program. Deprecated, this is equivalent to ApplicationName, and you should just call ApplicationName directly in new code. ApplicationName is included in standard FPC SysUtils unit, had good default and is easily configurable by callback OnGetApplicationName. See http://www.freepascal.org/docs-html/rtl/sysutils/getappconfigdir.html . This is suitable to show to user. It should also indicate how to run the program, usually it should be the basename of the executable (although we do not depend on it technically). It is used to derive config and data paths for our program, see ApplicationConfig and ApplicationData.
`function NormalFileExists(const fileName: string): boolean; deprecated;`
Warning: this symbol is deprecated. 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. Deprecated, since we use URLs everywhere, use URIFileExists to check does file exist.
`function UserConfigPath: string; deprecated;`
Warning: this symbol is deprecated. Path to store user configuration files. This is some directory that should be 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. Deprecated, use ApplicationConfig instead.
`function UserConfigFile(const Extension: string): string; deprecated;`
Warning: this symbol is deprecated. Filename to store user configuration. Always returns absolute (not relative) path. Returns filename that: is inside UserConfigPath depends on OnGetApplicationName has given Extension. Extension should contain beginning dot. E.g. FExtension = '.ini'. This way you can pass FExtension = '' to have a filename without extension. Deprecated, use ApplicationConfig(ApplicationName + Extension) instead.
`function ProgramDataPath: string; deprecated;`
Warning: this symbol is deprecated. Path to access installed data files. Returns absolute path, containing trailing PathDelim. Deprecated, use ApplicationData instead.
`function ApplicationConfig(const Path: string): string;`
URL where we should read and write configuration files. This always returns a `file://...` URL, which is comfortable since our engine operates on URLs most of the time. Given Path specifies a name of the file (with possible subdirectories) under the user config directory. The Path is a relative URL, so you should always use slashes (regardless of OS), and you can escape characters by %xx. We make sure that the directory (including the subdirectories you specify in Path) exists, creating it if necessary. But we do not create the file. We should have permissions to write inside the given directory (although, as always on multi-process OS, the only 100% way to know if you can write there is to actually try it). This uses FPC GetAppConfigDir under the hood. Which in turn looks at OnGetApplicationName, and may use OS-specific algorithm to find good config directory, 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 (simplifying: looks inside ˜/.config/<application-name>/).
`function ApplicationData(const Path: string): string;`
URL from which we should read data files. This returns URL, which is comfortable since our engine operates on URLs everywhere. On normal desktops systems this will return a `file://...` URL. On Android, it will return an URL indicating assets (files packages together inside Android apk) starting with `assets:/...`. Given Path specifies a path under the data directory, with possible subdirectories, with possible filename at the end. The Path is a relative URL, so you should always use slashes (regardless of OS), and you can escape characters by %xx. You can use Path = '' to get the URL to whole data directory. Note that files there may be read-only, do not try to write there. The algorithm to find base data directory (with respect to which Path is resolved) is OS-specific. It looks at ApplicationName, and searches a couple of common locations, using the first location that exists. We try to look first inside user-specific directories, then inside system-wide directories, and as a fallback we use current exe directory (under Windows) or current working directory (under other OSes). The exact details how we currently look for data directory (specified here so that you know how to install your program): Windows `data` subdirectory inside our exe directory, if exists. Last resort fallback: just our exe directory. Mac OS X `Contents/Resources/data` subdirectory inside our bundle directory, if we are inside a bundle and such subdirectory exists. Otherwise, algorithm on Mac OS X follows algorithm on other Unixes, see below. Android We always return `assets:/` directory, to read assets from the apk. Unix (Linux, Mac OS X, FreeBSD etc.) `˜/.local/share/` + ApplicationName. This is nice user-specific data directory, following the default dictated by http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html . If such directory exists, it is returned. This is checked first, to allow user to always override system-wide installation of a program with his own installation. E.g. consider the situation when an old version of a 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 ˜/.local/share/my_program/ is checked 1st, before system-wide paths. `HomePath +'.' +ApplicationName+'.data/'`. If such directory exists, it is returned. This is another location of user-specific data directory, deprecated now. You should instead use more standard `˜/.local/share/` + ApplicationName. `'/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. `data` subdirectory of current directory, if exists. Using `data` subdirectory is usually comfortable, it allows you to separate code from data better. As a last resort, we just return the current directory. So you can just place data files inside the current directory, and if user will run your game from it's own directory — it will work without any fuss.
`function HomePath: string;`
User's home directory, with trailing PathDelim. Taken from environment variable $HOME, unless it's empty or unset, in which case we take this from Unix 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 Kambi 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; const Warn: boolean = false);`
Call SysUtils.DeleteFile and check result. When Warn = `False` (default) raises an exception on failure, otherwise (when Warn = `True`) makes only OnWarning on failure. ###### Exceptions raised `Exception` If delete failed, and Warn = `False`.
`procedure CheckRemoveDir(const DirFileName: string);`
Call RemoveDir and check result. ###### Exceptions raised `Exception` If delete failed.
`procedure CheckForceDirectories(const Dir: string);`
Make sure directory exists, eventually creating it, recursively, checking result.
`procedure CheckRenameFile(const Source, Dest: string);`
`procedure RemoveNonEmptyDir(const DirName: string);`
Remove the directory DirName, recursively, unconditionally, with all the files and subdirectories inside. DirName may but doesn't have to end with PathDelim.
`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.
`function CombinePaths(BasePath, RelPath: string): string; deprecated;`
Warning: this symbol is deprecated. 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. This is deprecated, you should instead operate on URLs and combine them using CastleURIUtils.Combines.
`Function PathFileSearch(Const Name : String; ImplicitCurrentDir : Boolean = True) : String;`
Search a file on $PATH. Works with double quotes around components of path list, avoiding this bug: http://bugs.freepascal.org/view.php?id=19279. See http://www.freepascal.org/docs-html/rtl/sysutils/filesearch.html for original FileSearch docs. In FPC >= 2.5.1, you should instead use just ExeSearch(Name). It also will use $PATH and avoid double quotes problems on Windows. See http://bugs.freepascal.org/view.php?id=19282 and fix on http://svn.freepascal.org/cgi-bin/viewvc.cgi?view=rev&revision=17717 .
`function FindExe(const ExeName: string): string;`
Find program on $PATH. Automatically adds ExeExtension, so don't add it yourself. Searches in $PATH (and, if OS does this, in current directory — this is standard on Windows but not on Unix). Returns '' (if not found) or absolute filename.
`function GetTempFileNameCheck: string;`
Get temporary filename, suitable for ApplicationName, checking that it doesn't exist.
`function GetTempFileNamePrefix: string;`
Return a prefix (beginning of an absolute filename) to save a series of temporary files.
Generated by PasDoc 0.13.0 on 2015-06-15 04:43:09