Unit CastleUriUtils

Extracts #anchor from URI. On input, URI contains full URI. On output, Anchor is removed from URI and saved in Anchor. If no #anchor existed, Anchor is set to ''.

Like UriExtractAnchor, but URI remains unchanged.

Calculate #anchor from an URI, and split it into a key-value map.

This supports special CGE syntax within URL anchor to specify loading parameters for Spine, sprite sheets, images.

On output, the key-value pairs from anchor are saved in TStringStringMap. The SettingsFromAnchor is always cleared at the beginning. If no anchor existed, SettingsFromAnchor will be empty when this ends.

Return URI with anchor (if was any) stripped.

Replace all sequences like %xx with their actual 8-bit characters.

The intention is that this is similar to PHP function with the same name.

To account for badly encoded strings, invalid encoded URIs do not raise an error — they are only reported to WritelnWarning. So you can simply ignore them, or write a warning about them for user. This is done because often you will use this with URIs provided by the user, read from some file etc., so you can't be sure whether they are correctly encoded, and raising error unconditionally is not OK. (Considering the number of bad HTML pages on WWW.)

The cases of badly encoded strings are:

• "%xx" sequence ends unexpectedly at the end of the string. That is, string ends with "%" or "%x". In this case we simply keep "%" or "%x" in resulting string.

• "xx" in "%xx" sequence is not a valid hexadecimal number. In this case we also simply keep "%xx" in resulting string.

Get protocol from given URI.

This is very similar to how UriParser.ParseUri function detects the protocol, although not 100% compatible:

• We allow whitespace (including newline) before protocol name.

  This is useful, because some VRML/X3D files have the ECMAScript code inlined and there is sometimes whitespace before "ecmascript:" protocol.

• We never detect a single-letter protocol name.

  This is useful, because we do not use any single-letter protocol name, and it allows to detect Windows absolute filenames like c:\blah.txt as filenames. Otherwise, Windows absolute filenames could not be accepted by any of our routines that work with URLs (like the Download function), since they would be detected as URLs with unknown protocol "c".

  Our UriProtocol will answer that protocol is empty for c:\blah.txt. Which means no protocol, so our engine will treat it as a filename. (In contrast with UriParser.ParseUri that would detect protocol called "c".) See doc/uri_filename.txt in sources for more comments about differentiating Uri and filenames in our engine.

• We always return lowercase protocol. This is comfortable, since you almost always calculate protocol to compare it, and protocol names are not case-sensitive, and you should always produce URLs with lowercase protocol names (see http://tools.ietf.org/html/rfc3986#section-3.1).

Check does URI contain given Protocol. This is equivalent to checking UriProtocol(S) = Protocol, ignoring case, although may be a little faster. Given Protocol string cannot contain ":" character.

Warning: this symbol is deprecated: use ParseUri to extract Uri.Path + Uri.Document, instead of this routine that doesn't do decoding

Remove the protocol part from URI.

Is the S a valid protocol scheme.

Following https://datatracker.ietf.org/doc/html/rfc3986 , protocol scheme must

• begin with an (ASCII) letter

• and be followed by any combination of (ASCII) letters, digits, plus ("+"), period ("."), or hyphen ("-").

Return absolute URI, given base and relative URI.

Base URI must be either an absolute (with protocol) URI, or only an absolute filename (in which case we'll convert it to file:// URI under the hood, if necessary). This is usually the URI of the containing file, for example an HTML file referencing the image, processed by AbsoluteURI.

Relative URI may be a relative URI or an absolute URI. In the former case it is merged with Base. In the latter case it is simply returned.

If you want to support relative URIs, you want to use this routine. It treats Relative always as an URI (so it should be percent-escaped, with slashes and such). Other routines in our engine, like AbsoluteUri and Download, treat strings without protocol as a filename (so it's not percent-escaped, it uses PathDelim specific to OS — slash or backslash etc.). This routine, on the other hand, treats Relative string always as an URI (when it doesn't include protocol, it just means it's relative to Base).

Make sure that the URI is absolute (always has a protocol). This function treats an URI without a protocol as a simple filename (absolute or relative to the current directory). This includes treating empty string as equivalent to current directory.

Does URI contain only an absolute filename. Useful to detect unwanted paths in data files, you usually do not want to have such paths in data files, as they make it impossible to transfer the data (move/copy files) to other system/location.

Convert URI (or filename) to a filename.

This is an improved UriToFilename from UriParser. When URI is already a filename, this does a better job than UriToFilename, as it handles also Windows absolute filenames (see UriProtocol). Returns empty string in case of problems, for example when this is not a file URI.

Just like UriParser.UriToFilename, this percent-decodes the parameter. For example, %4d in URI will turn into letter M in result.

It also handles our castle-data: protocol.

Convert filename to URI.

This is a fixed version of UriParser.FilenameToUri, that correctly percent-encodes the parameter, making it truly a reverse of UriToFilenameSafe. In FPC > 2.6.2 UriParser.FilenameToUri will also do this (after Michalis' patch, see http://svn.freepascal.org/cgi-bin/viewvc.cgi?view=revision&revision=24321 ).

It also makes sure the filename is absolute (it uses ExpandFileName, so if the FileName is relative — it will be expanded, treating it as relative to the current directory).

Convert filename to URI, if the filename is relative – the URI will also be relative.

In contrast to FilenameToUriSafe, which always returns absolute URI, this will return relative URI if the filename is relative. If the given filename is absolute, this is equivalent to FilenameToUriSafe.

The FileName = '' is also considered relative, and returns ''.

Tries change URI to use castle-data: protocol. It's used in our editor to change absolute paths to relative to castle-data directory.

Get MIME type for content of the URI without downloading the file. For local and remote files (file, http, and similar protocols) it guesses MIME type based on file extension.

Using this function is not adviced if you want to properly support MIME types returned by http server for network resources. For this, you have to download the file, and look at what MIME type the http server reports. The Download function returns such proper MimeType. This function only guesses without downloading.

Returns empty string if MIME type is unknown.

Overloaded version returns also Gzipped to detect whether file contents are gzipped.

The recognition mechanism can be enhanced by adding your own mappings to the UriMimeExtensions.

This item has no description.

Map from an extension to a MIME type, used by UriMimeType. The extension should be lowercase, and includes a leading dot, like .png.

Convert URI to a nice form for display (to show in messages and such). It makes sure to nicely trim URLs that would be too long/unreadable otherwise (like "data:" URI, or multi-line URLs with inlined ECMAScript/CastleScript/shader code).

When Short = False (default), then for most "file:" and "http:" URLs, it just returns them untouched.

When Short = True, it will try to extract the last path component from URLs like "file:" and "http:", if this last component is not empty. Similar to what ExtractFileName does for filenames. It will also decode the URI (convert %xx to normal charaters). Because of the percent-decoding, it is not advised to use this on filenames with Short=true. Usually, you want to call UriCaption that makes sure that argument is URL (using AbsoluteUri) and then returns UriDisplay with Short=true.

It is safe to use this on both absolute and relative URLs. It does not resolve relative URLs in any way. It also means that it returns empty string for empty URI (contrary to most other routines that convert empty string to a current directory when resolving relative URLs).

Convert URI to a nice form for a short caption.

Returns empty string for empty URI (contrary to most other routines that treat empty string like a current directory).

See UriDisplay documentation for details. This calls UriDisplay with Short = True.

Change extension of the URL.

Delete extension of the URL.

Extract filename (last part after slash) from URL.

Extract path (everything before last part), including final slash, from URL.

Ensure URL ends with slash.

For an empty URL, returns empty string (so it does not turn "" into "/"). For an URL ending with bashslash (which usually means you passed Windows path name), it removes the backslash before adding slash.

This should be used instead of InclPathDelim or IncludeTrailingPathDelimiter, when you use URLs instead of filenames.

Ensure URL does not end with slash. In case you passed Windows path name, it also removes the backslash.

This should be used instead of ExclPathDelim or ExcludeTrailingPathDelimiter, when you use URLs instead of filenames.

Does a file exist, that is: whether it makes sense to load it with the Download function.

Returns True for URLs where we cannot determine whether the file exists (like http / https).

This is simply a shortcut for UriExists(Url) in [ueFile, ueUnknown].

Does a file or directory exist under this URL. See TUriExists for possible return values.

Current working directory of the application, expressed as URL, including always final slash at the end.

If the given URL uses "castle-data:..." protocol, resolve it, returning a URL that does not use "castle-data:..." protocol any more. For example may resolve "castle-data:/xxx" into "file:///home/michalis/my-application/data/xxx". See https://castle-engine.io/data for documentation how our "data directory" works.

If the URL has a different protocol, it is returned unchanged.

If this URL indicates something inside the CGE data directory then return URL relative to this data directory. E.g. for "castle-data:/foo/bar.txt" it returns "foo/bar.txt".

It accepts any URL, relative (to the current working directory) or absolute (with any protocol). It works when the URL starts with castle-data:/ protocol, it works when the URL starts with other (like file:/) protocol that still points to a file inside data.

If the URL does not point to a file in data, it is returned untouched.

Result of the UriExists query.

Values

• ueNotExists: Given path does not indicate either a file or directory.
• ueFile: Given path is a regular file. In particular, this means it can be read with the Download function.

  Note that there is no guarantee that opening it will work. On a multi-process system the file can be always deleted between the call to UriExists and Download. And the file permissions may not allow reading. We merely say that "right now this file exists".

• ueDirectory: Given path is a directory. E.g. it can be used as path for the FindFiles function.
• ueUnknown: Detecting existence of given path is tricky, it could be time-consuming.

  This applies e.g. to URLs using http / https protocols. The only way to detect their existence would be to actually open them. But this involves a network request, so it may take some time, and should be done asynchronously (see TCastleDownload).

  If you really want to check the file existence, you can always try to open it by Download:

  try
    Stream := Download(Url);
    FreeAndNil(Stream);
    ItExists := true;
  except
    on E: Exception do
    begin
      WritelnLog('Opening URL %s failed with exception %s', [
        UriCaption(Url),
        ExceptMessage(E)
      ]);
      ItExists := false;
    end;
  end;

  Depending on the circumstances, the "ueUnknown" can be sometimes interpreted as "it exists" and sometimes as "it doesn't exist". Opening it with Download may either fail or succeed, we cannot detect.

On systems where filesystems are usually case-sensitive (Unix; like Linux, FreeBSD, macOS), accept any 'castle-data:/xxx' URLs, even when they have different case than the actual files.

This is a quick way to run applications prepared / tested on case-insensitive systems (like Windows) on Unix. It causes a small additional work when we open data files, but in many cases it is acceptable.