1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html>
<head>
<title>Castle Game Engine: CastleURIUtils</title>
<meta name="generator" content="PasDoc 0.13.0">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<link rel="StyleSheet" type="text/css" href="pasdoc.css">
</head>
<body>
<table class="container"><tr><td class="navigation">
<h2>Castle Game Engine</h2><p><a href="introduction.html" class="navigation">Introduction</a></p><p><a href="AllUnits.html" class="navigation">Units</a></p><p><a href="ClassHierarchy.html" class="navigation">Class Hierarchy</a></p><p><a href="AllClasses.html" class="navigation">Classes, Interfaces, Objects and Records</a></p><p><a href="AllTypes.html" class="navigation">Types</a></p><p><a href="AllVariables.html" class="navigation">Variables</a></p><p><a href="AllConstants.html" class="navigation">Constants</a></p><p><a href="AllFunctions.html" class="navigation">Functions and Procedures</a></p><p><a href="AllIdentifiers.html" class="navigation">Identifiers</a></p></td><td class="content">
<h1 class="unit">Unit CastleURIUtils</h1>
<table class="sections wide_list">
<tr>
<td><a class="section" href="#PasDoc-Description">Description</a></td><td><a class="section" href="#PasDoc-Uses">Uses</a></td><td>Classes, Interfaces, Objects and Records</td><td><a class="section" href="#PasDoc-FuncsProcs">Functions and Procedures</a></td><td>Types</td><td>Constants</td><td>Variables</td></tr></table>
<a name="PasDoc-Description"></a><h2 class="description">Description</h2>
<p>
URI utilities. These extend standard FPC URIParser unit.</p>
<a name="PasDoc-Uses"></a><h2 class="uses">Uses</h2>
<ul class="useslist"><li>Classes</li></ul><h2 class="overview">Overview</h2>
<a name="PasDoc-FuncsProcs"></a><h3 class="summary">Functions and Procedures</h3>
<table class="summary wide_list">
<tr class="list">
<td class="itemcode"><code>procedure <b><a href="CastleURIUtils.html#URIExtractAnchor">URIExtractAnchor</a></b>(var URI: string; out Anchor: string; const RecognizeEvenEscapedHash: boolean = false);</code></td>
</tr>
<tr class="list2">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#URIDeleteAnchor">URIDeleteAnchor</a></b>(const URI: string; const RecognizeEvenEscapedHash: boolean = false): string;</code></td>
</tr>
<tr class="list">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#RawURIDecode">RawURIDecode</a></b>(const S: string): string;</code></td>
</tr>
<tr class="list2">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#URIProtocol">URIProtocol</a></b>(const URI: string): string;</code></td>
</tr>
<tr class="list">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#URIProtocolIs">URIProtocolIs</a></b>(const S: string; const Protocol: string; out Colon: Integer): boolean;</code></td>
</tr>
<tr class="list2">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#URIDeleteProtocol">URIDeleteProtocol</a></b>(const S: string): string;</code></td>
</tr>
<tr class="list">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#CombineURI">CombineURI</a></b>(const Base, Relative: string): string;</code></td>
</tr>
<tr class="list2">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#AbsoluteURI">AbsoluteURI</a></b>(const URI: string): string;</code></td>
</tr>
<tr class="list">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#AbsoluteFileURI">AbsoluteFileURI</a></b>(const URI: string): boolean;</code></td>
</tr>
<tr class="list2">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#URIToFilenameSafe">URIToFilenameSafe</a></b>(const URI: string): string;</code></td>
</tr>
<tr class="list">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#FilenameToURISafe">FilenameToURISafe</a></b>(FileName: string): string;</code></td>
</tr>
<tr class="list2">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#URIMimeType">URIMimeType</a></b>(const URI: string): string;</code></td>
</tr>
<tr class="list">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#URIMimeType">URIMimeType</a></b>(const URI: string; out Gzipped: boolean): string;</code></td>
</tr>
<tr class="list2">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#URIDisplay">URIDisplay</a></b>(const URI: string; const Short: boolean = false): string;</code></td>
</tr>
<tr class="list">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#URICaption">URICaption</a></b>(const URI: string): string;</code></td>
</tr>
<tr class="list2">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#ChangeURIExt">ChangeURIExt</a></b>(const URL, Extension: string): string;</code></td>
</tr>
<tr class="list">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#DeleteURIExt">DeleteURIExt</a></b>(const URL: string): string;</code></td>
</tr>
<tr class="list2">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#ExtractURIName">ExtractURIName</a></b>(const URL: string): string;</code></td>
</tr>
<tr class="list">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#ExtractURIPath">ExtractURIPath</a></b>(const URL: string): string;</code></td>
</tr>
<tr class="list2">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#URIFileExists">URIFileExists</a></b>(const URL: string): boolean;</code></td>
</tr>
<tr class="list">
<td class="itemcode"><code>function <b><a href="CastleURIUtils.html#URICurrentPath">URICurrentPath</a></b>: string;</code></td>
</tr>
</table>
<h2 class="description">Description</h2>
<h3 class="detail">Functions and Procedures</h3>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="URIExtractAnchor"></a><code>procedure <b>URIExtractAnchor</b>(var URI: string; out Anchor: string; const RecognizeEvenEscapedHash: boolean = false);</code></td>
</tr>
<tr><td colspan="1">
<p>
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 ''.
<p>When RecognizeEvenEscapedHash, we also recognize as a delimiter escaped hash, %23. This is a hack and should not be used (prevents from using actual filename with hash, thus making the escaping process useless). Unless there's no other sensible way — e.g. specify Spine skin name when opening Spine json file...</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="URIDeleteAnchor"></a><code>function <b>URIDeleteAnchor</b>(const URI: string; const RecognizeEvenEscapedHash: boolean = false): string;</code></td>
</tr>
<tr><td colspan="1">
<p>
Return URI with anchor (if was any) stripped.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="RawURIDecode"></a><code>function <b>RawURIDecode</b>(const S: string): string;</code></td>
</tr>
<tr><td colspan="1">
<p>
Replace all sequences like %xx with their actual 8-bit characters.
<p>The intention is that this is similar to PHP function with the same name.
<p>To account for badly encoded strings, invalid encoded URIs do not raise an error — they are only reported to <a class="normal" href="CastleWarnings.html#OnWarning">OnWarning</a>. 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.)
<p>The cases of badly encoded strings are:
<p></p>
<ul class="paragraph_spacing">
<li><p>"%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.</p></li>
<li><p>"xx" in "%xx" sequence is not a valid hexadecimal number. In this case we also simply keep "%xx" in resulting string.</p></li>
</ul>
<p></p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="URIProtocol"></a><code>function <b>URIProtocol</b>(const URI: string): string;</code></td>
</tr>
<tr><td colspan="1">
<p>
Get protocol from given URI.
<p>This is very similar to how URIParser.ParseURI function detects the protocol, although not 100% compatible:
<p></p>
<ul class="paragraph_spacing">
<li><p>We allow whitespace (including newline) before protocol name.
<p>This is useful, because some VRML/X3D files have the ECMAScript code inlined and there is sometimes whitespace before "ecmascript:" protocol.</p></li>
<li><p>We never detect a single-letter protocol name.
<p>This is useful, because we do not use any single-letter protocol name, and it allows to detect Windows absolute filenames like <code>c:\blah.txt</code> as filenames. Otherwise, Windows absolute filenames could not be accepted by any of our routines that work with URLs (like the <a class="normal" href="CastleDownload.html#Download">Download</a> function), since they would be detected as URLs with unknown protocol "c".
<p>Our <code>URIProtocol</code> will answer that protocol is empty for <code>c:\blah.txt</code>. 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.</p></li>
<li><p>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 (see <a href="http://tools.ietf.org/html/rfc3986#section-3.1">http://tools.ietf.org/html/rfc3986#section-3.1</a>).</p></li>
</ul>
<p></p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="URIProtocolIs"></a><code>function <b>URIProtocolIs</b>(const S: string; const Protocol: string; out Colon: Integer): boolean;</code></td>
</tr>
<tr><td colspan="1">
<p>
Check does URI contain given Protocol. This is equivalent to checking <a class="normal" href="CastleURIUtils.html#URIProtocol">URIProtocol</a>(S) = Protocol, ignoring case, although may be a little faster. Given Protocol string cannot contain ":" character.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="URIDeleteProtocol"></a><code>function <b>URIDeleteProtocol</b>(const S: string): string;</code></td>
</tr>
<tr><td colspan="1">
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="CombineURI"></a><code>function <b>CombineURI</b>(const Base, Relative: string): string;</code></td>
</tr>
<tr><td colspan="1">
<p>
Return absolute URI, given base and relative URI.
<p>Base URI must be either an absolute (with protocol) URI, or only an absolute filename (in which case we'll convert it to <a href="file://">file://</a> 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 <a class="normal" href="CastleURIUtils.html#AbsoluteURI">AbsoluteURI</a>.
<p>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.
<p>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 <a class="normal" href="CastleURIUtils.html#AbsoluteURI">AbsoluteURI</a> and <a class="normal" href="CastleDownload.html#Download">Download</a>, 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).</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="AbsoluteURI"></a><code>function <b>AbsoluteURI</b>(const URI: string): string;</code></td>
</tr>
<tr><td colspan="1">
<p>
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.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="AbsoluteFileURI"></a><code>function <b>AbsoluteFileURI</b>(const URI: string): boolean;</code></td>
</tr>
<tr><td colspan="1">
<p>
Does URI contain only an absolute filename. Useful for warnings, since you usually do not want to have such paths in your data, as they it impossible to transfer the data (move/copy files) to other system/location.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="URIToFilenameSafe"></a><code>function <b>URIToFilenameSafe</b>(const URI: string): string;</code></td>
</tr>
<tr><td colspan="1">
<p>
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 <a class="normal" href="CastleURIUtils.html#URIProtocol">URIProtocol</a>). Returns empty string in case of problems, for example when this is not a file URI.
<p>Just like URIParser.URIToFilename, this percent-decodes the parameter. For example, <code>%4d</code> in URI will turn into letter <code>M</code> in result.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="FilenameToURISafe"></a><code>function <b>FilenameToURISafe</b>(FileName: string): string;</code></td>
</tr>
<tr><td colspan="1">
<p>
Convert filename to URI.
<p>This is a fixed version of URIParser.FilenameToURI, that correctly percent-encodes the parameter, making it truly a reverse of <a class="normal" href="CastleURIUtils.html#URIToFilenameSafe">URIToFilenameSafe</a>. In FPC > 2.6.2 URIParser.FilenameToURI will also do this (after Michalis' patch, see <a href="http://svn.freepascal.org/cgi-bin/viewvc.cgi?view=revision&revision=24321">http://svn.freepascal.org/cgi-bin/viewvc.cgi?view=revision&revision=24321</a> ).
<p>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).</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="URIMimeType"></a><code>function <b>URIMimeType</b>(const URI: string): string;</code></td>
</tr>
<tr><td colspan="1">
<p>
Get MIME type for content of the URI <i>without downloading the file</i>. For local and remote files (file, http, and similar protocols) it guesses MIME type based on file extension. (Although we may add here detection of local file types by opening them and reading a header, in the future.) Only for data: URI scheme it actually reads the MIME type.
<p>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, as look at what MIME type the http server reports. The <a class="normal" href="CastleDownload.html#Download">Download</a> function returns such proper MimeType. This function only guesses without downloading.
<p>Returns empty string if MIME type is unknown.
<p>Overloaded version returns also Gzipped to detect whether file contents are gzipped.
<p></p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="URIMimeType"></a><code>function <b>URIMimeType</b>(const URI: string; out Gzipped: boolean): string;</code></td>
</tr>
<tr><td colspan="1">
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="URIDisplay"></a><code>function <b>URIDisplay</b>(const URI: string; const Short: boolean = false): string;</code></td>
</tr>
<tr><td colspan="1">
<p>
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/<a class="normal" href="CastleScript.html">CastleScript</a>/shader code).
<p>When Short = <code>False</code> (default), then for most "file:" and "http:" URLs, it just returns them untouched.
<p>When Short = <code>True</code>, 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 <a class="normal" href="CastleURIUtils.html#URICaption">URICaption</a> that makes sure that argument is URL (using <a class="normal" href="CastleURIUtils.html#AbsoluteURI">AbsoluteURI</a>) and then returns <code>URIDisplay</code> with Short=true.
<p>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).</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="URICaption"></a><code>function <b>URICaption</b>(const URI: string): string;</code></td>
</tr>
<tr><td colspan="1">
<p>
Convert URI to a nice form for a short caption.
<p>Returns empty string for empty URI (contrary to most other routines that treat empty string like a current directory).
<p>See <a class="normal" href="CastleURIUtils.html#URIDisplay">URIDisplay</a> documentation for details.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="ChangeURIExt"></a><code>function <b>ChangeURIExt</b>(const URL, Extension: string): string;</code></td>
</tr>
<tr><td colspan="1">
<p>
Change extension of the URL.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="DeleteURIExt"></a><code>function <b>DeleteURIExt</b>(const URL: string): string;</code></td>
</tr>
<tr><td colspan="1">
<p>
Delete extension of the URL.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="ExtractURIName"></a><code>function <b>ExtractURIName</b>(const URL: string): string;</code></td>
</tr>
<tr><td colspan="1">
<p>
Extract filename (last part after slash) from URL.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="ExtractURIPath"></a><code>function <b>ExtractURIPath</b>(const URL: string): string;</code></td>
</tr>
<tr><td colspan="1">
<p>
Extract path (everything before last part), including final slash, from URL.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="URIFileExists"></a><code>function <b>URIFileExists</b>(const URL: string): boolean;</code></td>
</tr>
<tr><td colspan="1">
<p>
Does a local file exist. Always answers <code>True</code> for URLs that do not indicate local files (assume remote file exist).</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="itemcode"><a name="URICurrentPath"></a><code>function <b>URICurrentPath</b>: string;</code></td>
</tr>
<tr><td colspan="1">
<p>
Current working directory of the application, expressed as URL, including always final slash at the end.</p>
</td></tr>
</table>
<!-- Piwik -->
<script type="text/javascript">
var _paq = _paq || [];
_paq.push(["trackPageView"]);
_paq.push(["enableLinkTracking"]);
(function() {
var u=(("https:" == document.location.protocol) ? "https" : "http") + "://michalis.ii.uni.wroc.pl/piwik-castle-engine/";
_paq.push(["setTrackerUrl", u+"piwik.php"]);
_paq.push(["setSiteId", "1"]);
var d=document, g=d.createElement("script"), s=d.getElementsByTagName("script")[0]; g.type="text/javascript";
g.defer=true; g.async=true; g.src=u+"piwik.js"; s.parentNode.insertBefore(g,s);
})();
</script>
<!-- End Piwik Code -->
<noscript>
<!-- Piwik Image Tracker -->
<img src="http://michalis.ii.uni.wroc.pl/piwik-castle-engine/piwik.php?idsite=1&rec=1" style="border:0" alt="" />
<!-- End Piwik -->
</noscript>
<hr noshade size="1"><span class="appinfo"><em>Generated by <a href="http://pasdoc.sourceforge.net/">PasDoc 0.13.0</a> on 2015-06-15 04:43:12</em>
</span>
</td></tr></table></body></html>
|
