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

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

BaseUnix
Unix
SysUtils
CastleUtils

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 RegularFileExists(const FileName: String): Boolean;

function NormalFileExists(const FileName: String): Boolean; deprecated 'use RegularFileExists';

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);

procedure CopyDirectory(SourcePath, DestinationPath: string);

function FileNameAutoInc(const UrlPattern: string): string; overload;

function FileNameAutoInc(const UrlPrefix, UrlSuffixWithPattern: string): string; overload;

function FnameAutoInc(const UrlPattern: string): string; deprecated 'use FileNameAutoInc';

function ParentPath(DirName: string; DoExpandDirName: Boolean = true): string; deprecated 'use URLs and operate on them using CastleURIUtils unit';

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; out MimeType: string): AnsiString; overload;

function FileToString(const URL: string): AnsiString; overload;

procedure StringToFile(const URL: String; const Contents: AnsiString);

function SaveScreenPath: 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 RegularFileExists(const FileName: String): Boolean;

Returns True if file exists and is a "regular" file.

Detects and returns False for special Windows files like 'con', 'c:\con', 'c:\somedir\con' etc. ('con' is a special device name).

Returns False for directories (on all operating systems, unlike FPC FileExists which is inconsistent between OSes – on Unix, FPC FileExists surprisingly answers True for a directory).

Consider using URIExists or URIFileExists instead of this function, since in CGE you should use URLs for everything.

function NormalFileExists(const FileName: String): Boolean; deprecated 'use RegularFileExists';

Warning: this symbol is deprecated: use RegularFileExists

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 an URL, which is comfortable since our engine operates on URLs everywhere. On normal desktop systems this will return a file://... URL, usually pointing to the "data" subdirectory of your project. See the list below for a detailed description how it behaves on all platforms.

See the manual about the purpose of "data" directory: https://castle-engine.io/manual_data_directory.php . Using 'castle-data:/xxx' is adviced over explicitly calling ApplicationData('xxx').

Given Path parameter must specify 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 "/" to separate subdirectories (regardless of OS), and you can escape characters by %xx. You can use Path = '' to get the URL to the whole data directory.

Remember that files inside the data directory may be read-only on some systems. If you want to write files, use the ApplicationConfig instead.

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 look inside standard user-specific directories, then inside standard system-wide directories, then we look for the "data" subdirectory in the current exe directory (under Windows) or in the current working directory (under other OSes).

The algorithm specification below is non-trivial. Don't read it :) Instead folow the short version: just place the files inside the data subdirectory of your project, and everything will work out-of-the-box.

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.
Otherwise: just our exe directory. But this alternative is deprecated, please don't depend on it. Instead, place the data inside the "data" subdirectory.

macOS and iOS

On desktop macOS: Contents/Resources/data subdirectory inside our bundle directory, if we are inside a bundle and such subdirectory exists.
On iOS: data subdirectory inside our bundle directory, if we are inside a bundle and such subdirectory exists.
Otherwise, algorithm follows the algorithm on desktop Unix.

Android

We always return castle-android-assets:/ directory, which is a special location on Android where application should store it's assets.

Nintendo Switch

We always return castle-nx-contents:/ directory, which is a special location where application should store it's data files.

Desktop Unix (Linux, macOS, FreeBSD...)

˜/.local/share/ + ApplicationName. This is 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 the current directory, if exists. This is easiest and comfortable for development, just keep the "data" subdirectory alongside the executable binary.
Note: This is searched *after* system-wide specific dirs above, to avoid accidentally picking unrelated "data" in current directory instead of system-wide data.
As a last resort, we just return the current directory. So you can just place data files directly inside the current directory.
This alternative is deprecated, please don't depend on it. Instead, place the data inside the "data" subdirectory.

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.

In case of symlinks, removes the symlink (but does not descend inside, i.e. will not remove files inside a symlink to a directory).

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 CopyDirectory(SourcePath, DestinationPath: string);

Copies the contents from SourceDir to DestinationDir. DestinationDir and necessary subdirectories are created, if needed. Both SourceDir and DestinationDir may, but do not have to, end with PathDelim.

Note that DestinationDir contents are not cleared here. In effect, the existing files (present in DestinationDir before the copy operation, and not overwritten by corresponding files in SourceDir) will be left. If you need to clear them, consider using

if DirectoryExists(DestinationDir) then
  RemoveNonEmptyDir(DestinationDir);
CopyDirectory(SourceDir, DestinationDir);

function FileNameAutoInc(const UrlPattern: string): string; overload;

Substitute %d in given URL (UrlPattern) with successive numbers, until the resulting URL (which can be just a filename) doesn't exist.

We start with number = 0 and do Url := Format(UrlPattern, [Number]), until we find non-existing URL. Example UrlPattern is 'screenshot_%d.png', by saving to this UrlPattern you're relatively sure that each save goes to a new file.

Since we use standard Format function, you can use any Format placeholder syntax. E.g. use 'screenshot_%.04d.png' to have a number padded with zeros, with results like 'screenshot_0005.png'.

Note that it's possible on every OS that some other program, or a second copy of your own program, will write to the resulting URL 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 – as always, be prepared for anything happening in parallel when dealing with a filesystem.

The overloaded version with separate UrlPrefix and UrlSuffixWithPattern replaces %d in UrlSuffixWithPattern, and then glues (unmodified) UrlPrefix with (processed) UrlSuffixWithPattern. This is useful when you have a user-specified path, where you don't want to perform %d substitution. Alternative is to wrap the string in SUnformattable.

Example usage to save a screenshot:

ScreenshotUrl := FileNameAutoInc(SaveScreenPath, 'screenshot_%d.png');

Note that to save a screenshot in the most cross-platform way possible, we advise using Window.Container.SaveScreenToDefaultFile instead, it will use SaveScreenPath or more elebarate mechanism to work on all platforms.

Example usage to save anything else to user config:

SaveSomethingUrl := FileNameAutoInc(ApplicationConfig('save_something_%d.png'));

Note that it will be replaced soon by SaveSomethingUrl := FileNameAutoInc('castle-config:/', 'save_something_%d.png') which also deals with the (unlikely, but still) possibility that ApplicationConfig will contain a percent sign.

function FileNameAutoInc(const UrlPrefix, UrlSuffixWithPattern: string): string; overload;

function FnameAutoInc(const UrlPattern: string): string; deprecated 'use FileNameAutoInc';

Warning: this symbol is deprecated: use FileNameAutoInc

function ParentPath(DirName: string; DoExpandDirName: Boolean = true): string; deprecated 'use URLs and operate on them using CastleURIUtils unit';

Warning: this symbol is deprecated: use URLs and operate on them using CastleURIUtils unit

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; out MimeType: string): AnsiString; overload;

Read file or URL contents to a string. MimeType is returned, calculated just like the Download function.

function FileToString(const URL: string): AnsiString; overload;

procedure StringToFile(const URL: String; const Contents: AnsiString);

function SaveScreenPath: String;

Recommended path where to put screenshots on the current platform. Always ends with PathDelim and returns a directory that exists.

Empty string means that we cannot recommend any safe path to store screenshots (on some platforms, like mobile or console, it's not so easy to just store a file in the filesystem, without any permissions; and on some platforms they may have special API for this stuff).

Variables

ApplicationConfigOverride: string;

URL used as a prefix of all ApplicationConfig returned URLs. This overrides any autodetection of a suitable "user config" directory done by default by ApplicationConfig.

This must always end with a slash, if it's not empty.

ApplicationDataOverride: string;

URL used as a prefix of all ApplicationData returned URLs. This overrides any autodetection of a suitable "data" directory done by default by ApplicationData.

This must always end with a slash, if it's not empty.

Generated by PasDoc 0.16.0.