Unit CastleFilesUtils

Description

Operations on files.

Includes functions to help cross-platform programs to know where to read/write files:

Hints about what to use (and what not to use) in a cross-platform applications using Castle Game Engine:

  • To get a nice application name, use the ApplicationName function (defined in the standard SysUtils unit for FPC, or CastleUtils unit for Delphi). Every application can customize it by assigning OnGetApplicationName or (often more comfortable) assigning ApplicationProperties.ApplicationName. The Castle Game Engine units use it where appropriate.

  • Use the ApplicationData for all URLs from which you load your application read-only data. For example,

    MyImage := LoadImage(ApplicationData('gui/my_image.png'))

  • Use the ApplicationConfig for all URLs where you save or load the user configuration files, savegames etc.

  • Do not try to get the application name, or executable file name, using ParamStr(0). Do not rely on Lazarus Application.ExeName or our own (deprecated) ExeName.

    The "executable file name" is just not 100% reliably available on all OSes. And in some cases, like Android or iOS, the concept of "executable file name" doesn't even make sense, as your application is a library being called by a higher-level application (written in Java or Objective-C), and it's really an "internal matter" where is the executable file that started it.

  • Use CastleFindFiles unit to search for files and directories. It nicely works with URLs, has some support for the Android "assets" filesystem, and it has more comfortable API (e.g. searching recursively or not is just a matter of passing a particular flag).

    Do not use standard FindFirst/FindNext.

  • Read and write all data using streams (TStream) descendants. Open and save these streams using our CastleDownload unit.

Uses

Overview

Classes, Interfaces, Objects and Records

Name Description
Class EExeNameNotAvailable  
Class ERemoveFailed  

Functions and Procedures

function ExeName: string; deprecated 'as this function is not portable (may raise exception on non-Windows), it should not be used in a cross-platform game code';
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; const Warn: boolean = false);
procedure CheckForceDirectories(const Dir: string);
procedure CheckCopyFile(const Source, Dest: string);
procedure CheckRenameFile(const Source, Dest: string);
procedure RemoveNonEmptyDir(const DirName: string; const Warn: boolean = false);
function FileNameAutoInc(const FileNamePattern: string): string;
function FnameAutoInc(const FileNamePattern: string): string; deprecated 'use FileNameAutoInc';
function ParentPath(DirName: string; DoExpandDirName: boolean = true): string;
function CombinePaths(BasePath, RelPath: string): string;
Function PathFileSearch(Const Name : String; ImplicitCurrentDir : Boolean = True) : String;
function FindExe(const ExeName: string): string;
function AddExeExtension(const ExePath: string): string;
function GetTempFileNameCheck: string;
function GetTempFileNamePrefix: string;
function FileToString(const URL: string; const AllowStdIn: boolean; out MimeType: string): string; overload;
function FileToString(const URL: string; const AllowStdIn: boolean = false): string; overload;
procedure StringToFile(const URL, contents: string);

Variables

ApplicationConfigOverride: string;
ApplicationDataOverride: string;

Description

Functions and Procedures

function ExeName: string; deprecated 'as this function is not portable (may raise exception on non-Windows), it should not be used in a cross-platform game code';

Warning: this symbol is deprecated: as this function is not portable (may raise exception on non-Windows), it should not be used in a cross-platform game code

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 for FPC, has good default and is easily configurable by callback OnGetApplicationName or our ApplicationProperties.ApplicationName. 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 ApplicationName

  • 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 ApplicationName, 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

  1. data subdirectory inside our exe directory, if exists.

  2. Last resort fallback: just our exe directory.

macOS

  1. Contents/Resources/data subdirectory inside our bundle directory, if we are inside a bundle and such subdirectory exists.

  2. Otherwise, algorithm on macOS follows algorithm on other Unixes, see below.

Android

  1. We always return assets:/ directory, to read assets from the apk.

Unix (Linux, macOS, FreeBSD etc.)

  1. ˜/.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.

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

  3. '/usr/local/share/' +ApplicationName+ '/'. If such directory exists, it is returned.

    This is suitable for system-wide installations without package manager.

  4. '/usr/share/' +ApplicationName+ '/'. If such directory exists, it is returned.

    This is suitable for system-wide installations with package manager.

  5. data subdirectory of current directory, if exists. Using data subdirectory is usually comfortable, it allows you to separate code from data better.

  6. 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 WritelnWarning on failure.

Exceptions raised
ERemoveFailed
If delete failed, and Warn = False.
procedure CheckRemoveDir(const DirFileName: string; const Warn: boolean = false);

Call RemoveDir and check result.

When Warn = False (default) raises an exception on failure, otherwise (when Warn = True) makes only WritelnWarning on failure.

Exceptions raised
ERemoveFailed
If delete failed, and Warn = False.
procedure CheckForceDirectories(const Dir: string);

Make sure directory exists, eventually creating it, recursively, checking result.

procedure CheckCopyFile(const Source, Dest: string);
 
procedure CheckRenameFile(const Source, Dest: string);
 
procedure RemoveNonEmptyDir(const DirName: string; const Warn: boolean = false);

Remove the directory DirName, recursively, unconditionally, with all the files and subdirectories inside. DirName may but doesn't have to end with PathDelim.

When Warn = False (default) raises an exception on failure, otherwise (when Warn = True) makes only WritelnWarning on failure.

Exceptions raised
ERemoveFailed
If delete failed, and Warn = False.
function FileNameAutoInc(const FileNamePattern: string): string;

Substitute %d in given filename (or URL) 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 'use FileNameAutoInc';

Warning: this symbol is deprecated: use 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;

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.

Usually you should instead operate on URLs and combine them using CastleURIUtils.CombineURI.

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. On Windows, may also add alternative executable extensions (.com, .bat, .cmd). 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 AddExeExtension(const ExePath: string): string;

Add an exe file extension, searching for an existing file starting with ExePath. On non-Windows, this is just equal to ExePath + ExeExtension, which in practice is just equal to ExePath (since ExeExtension is empty on Unix). But on Windows, this tries to append other extensions (.com, .bat, .cmd, just like FindExe), depending on what file exists.

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.

function FileToString(const URL: string; const AllowStdIn: boolean; out MimeType: string): string; overload;

Read file or URL contents to a string. MimeType is returned, calculated just like the Download function. If AllowStdIn, then URL = '-' (one dash) is treated specially: it means to read contents from standard input (stdin, Input in Pascal).

function FileToString(const URL: string; const AllowStdIn: boolean = false): string; overload;
 
procedure StringToFile(const URL, contents: string);
 

Variables

ApplicationConfigOverride: string;
 
ApplicationDataOverride: string;
 

Generated by PasDoc 0.15.0.