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
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="Start" href="index.html">
<link rel="previous" href="Netulex_tut.html">
<link rel="next" href="Netsys.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of extensions" rel=Appendix href="index_extensions.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of class attributes" rel=Appendix href="index_attributes.html">
<link title="Index of class methods" rel=Appendix href="index_methods.html">
<link title="Index of classes" rel=Appendix href="index_classes.html">
<link title="Index of class types" rel=Appendix href="index_class_types.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Uq_gtk" rel="Chapter" href="Uq_gtk.html">
<link title="Uq_tcl" rel="Chapter" href="Uq_tcl.html">
<link title="Equeue" rel="Chapter" href="Equeue.html">
<link title="Unixqueue" rel="Chapter" href="Unixqueue.html">
<link title="Unixqueue_pollset" rel="Chapter" href="Unixqueue_pollset.html">
<link title="Unixqueue_select" rel="Chapter" href="Unixqueue_select.html">
<link title="Uq_resolver" rel="Chapter" href="Uq_resolver.html">
<link title="Uq_engines" rel="Chapter" href="Uq_engines.html">
<link title="Uq_multiplex" rel="Chapter" href="Uq_multiplex.html">
<link title="Uq_transfer" rel="Chapter" href="Uq_transfer.html">
<link title="Uq_socks5" rel="Chapter" href="Uq_socks5.html">
<link title="Uq_io" rel="Chapter" href="Uq_io.html">
<link title="Uq_lwt" rel="Chapter" href="Uq_lwt.html">
<link title="Uq_libevent" rel="Chapter" href="Uq_libevent.html">
<link title="Uq_mt" rel="Chapter" href="Uq_mt.html">
<link title="Uq_client" rel="Chapter" href="Uq_client.html">
<link title="Uq_server" rel="Chapter" href="Uq_server.html">
<link title="Uq_datagram" rel="Chapter" href="Uq_datagram.html">
<link title="Uq_engines_compat" rel="Chapter" href="Uq_engines_compat.html">
<link title="Equeue_intro" rel="Chapter" href="Equeue_intro.html">
<link title="Equeue_howto" rel="Chapter" href="Equeue_howto.html">
<link title="Netcamlbox" rel="Chapter" href="Netcamlbox.html">
<link title="Netcgi_apache" rel="Chapter" href="Netcgi_apache.html">
<link title="Netcgi_modtpl" rel="Chapter" href="Netcgi_modtpl.html">
<link title="Netcgi_plex" rel="Chapter" href="Netcgi_plex.html">
<link title="Netcgi_common" rel="Chapter" href="Netcgi_common.html">
<link title="Netcgi" rel="Chapter" href="Netcgi.html">
<link title="Netcgi_ajp" rel="Chapter" href="Netcgi_ajp.html">
<link title="Netcgi_scgi" rel="Chapter" href="Netcgi_scgi.html">
<link title="Netcgi_cgi" rel="Chapter" href="Netcgi_cgi.html">
<link title="Netcgi_fcgi" rel="Chapter" href="Netcgi_fcgi.html">
<link title="Netcgi_dbi" rel="Chapter" href="Netcgi_dbi.html">
<link title="Netcgi1_compat" rel="Chapter" href="Netcgi1_compat.html">
<link title="Netcgi_test" rel="Chapter" href="Netcgi_test.html">
<link title="Netcgi_porting" rel="Chapter" href="Netcgi_porting.html">
<link title="Nethttp_client_conncache" rel="Chapter" href="Nethttp_client_conncache.html">
<link title="Nethttp_client" rel="Chapter" href="Nethttp_client.html">
<link title="Nettelnet_client" rel="Chapter" href="Nettelnet_client.html">
<link title="Netftp_data_endpoint" rel="Chapter" href="Netftp_data_endpoint.html">
<link title="Netftp_client" rel="Chapter" href="Netftp_client.html">
<link title="Nethttp_fs" rel="Chapter" href="Nethttp_fs.html">
<link title="Netftp_fs" rel="Chapter" href="Netftp_fs.html">
<link title="Netsmtp" rel="Chapter" href="Netsmtp.html">
<link title="Netpop" rel="Chapter" href="Netpop.html">
<link title="Netldap" rel="Chapter" href="Netldap.html">
<link title="Netclient_tut" rel="Chapter" href="Netclient_tut.html">
<link title="Netgss_bindings" rel="Chapter" href="Netgss_bindings.html">
<link title="Netgss" rel="Chapter" href="Netgss.html">
<link title="Nethttpd_types" rel="Chapter" href="Nethttpd_types.html">
<link title="Nethttpd_kernel" rel="Chapter" href="Nethttpd_kernel.html">
<link title="Nethttpd_reactor" rel="Chapter" href="Nethttpd_reactor.html">
<link title="Nethttpd_engine" rel="Chapter" href="Nethttpd_engine.html">
<link title="Nethttpd_services" rel="Chapter" href="Nethttpd_services.html">
<link title="Nethttpd_plex" rel="Chapter" href="Nethttpd_plex.html">
<link title="Nethttpd_util" rel="Chapter" href="Nethttpd_util.html">
<link title="Nethttpd_intro" rel="Chapter" href="Nethttpd_intro.html">
<link title="Netmcore" rel="Chapter" href="Netmcore.html">
<link title="Netmcore_camlbox" rel="Chapter" href="Netmcore_camlbox.html">
<link title="Netmcore_mempool" rel="Chapter" href="Netmcore_mempool.html">
<link title="Netmcore_heap" rel="Chapter" href="Netmcore_heap.html">
<link title="Netmcore_ref" rel="Chapter" href="Netmcore_ref.html">
<link title="Netmcore_array" rel="Chapter" href="Netmcore_array.html">
<link title="Netmcore_sem" rel="Chapter" href="Netmcore_sem.html">
<link title="Netmcore_mutex" rel="Chapter" href="Netmcore_mutex.html">
<link title="Netmcore_condition" rel="Chapter" href="Netmcore_condition.html">
<link title="Netmcore_queue" rel="Chapter" href="Netmcore_queue.html">
<link title="Netmcore_buffer" rel="Chapter" href="Netmcore_buffer.html">
<link title="Netmcore_matrix" rel="Chapter" href="Netmcore_matrix.html">
<link title="Netmcore_hashtbl" rel="Chapter" href="Netmcore_hashtbl.html">
<link title="Netmcore_process" rel="Chapter" href="Netmcore_process.html">
<link title="Netmcore_tut" rel="Chapter" href="Netmcore_tut.html">
<link title="Netmcore_basics" rel="Chapter" href="Netmcore_basics.html">
<link title="Netplex_types" rel="Chapter" href="Netplex_types.html">
<link title="Netplex_mp" rel="Chapter" href="Netplex_mp.html">
<link title="Netplex_mt" rel="Chapter" href="Netplex_mt.html">
<link title="Netplex_log" rel="Chapter" href="Netplex_log.html">
<link title="Netplex_controller" rel="Chapter" href="Netplex_controller.html">
<link title="Netplex_container" rel="Chapter" href="Netplex_container.html">
<link title="Netplex_sockserv" rel="Chapter" href="Netplex_sockserv.html">
<link title="Netplex_workload" rel="Chapter" href="Netplex_workload.html">
<link title="Netplex_main" rel="Chapter" href="Netplex_main.html">
<link title="Netplex_config" rel="Chapter" href="Netplex_config.html">
<link title="Netplex_kit" rel="Chapter" href="Netplex_kit.html">
<link title="Rpc_netplex" rel="Chapter" href="Rpc_netplex.html">
<link title="Netplex_cenv" rel="Chapter" href="Netplex_cenv.html">
<link title="Netplex_semaphore" rel="Chapter" href="Netplex_semaphore.html">
<link title="Netplex_sharedvar" rel="Chapter" href="Netplex_sharedvar.html">
<link title="Netplex_mutex" rel="Chapter" href="Netplex_mutex.html">
<link title="Netplex_encap" rel="Chapter" href="Netplex_encap.html">
<link title="Netplex_mbox" rel="Chapter" href="Netplex_mbox.html">
<link title="Netplex_internal" rel="Chapter" href="Netplex_internal.html">
<link title="Netplex_intro" rel="Chapter" href="Netplex_intro.html">
<link title="Netplex_advanced" rel="Chapter" href="Netplex_advanced.html">
<link title="Netplex_admin" rel="Chapter" href="Netplex_admin.html">
<link title="Netshm" rel="Chapter" href="Netshm.html">
<link title="Netshm_data" rel="Chapter" href="Netshm_data.html">
<link title="Netshm_hashtbl" rel="Chapter" href="Netshm_hashtbl.html">
<link title="Netshm_array" rel="Chapter" href="Netshm_array.html">
<link title="Netshm_intro" rel="Chapter" href="Netshm_intro.html">
<link title="Netstring_pcre" rel="Chapter" href="Netstring_pcre.html">
<link title="Netconversion" rel="Chapter" href="Netconversion.html">
<link title="Netchannels" rel="Chapter" href="Netchannels.html">
<link title="Netstream" rel="Chapter" href="Netstream.html">
<link title="Netmime_string" rel="Chapter" href="Netmime_string.html">
<link title="Netmime" rel="Chapter" href="Netmime.html">
<link title="Netsendmail" rel="Chapter" href="Netsendmail.html">
<link title="Neturl" rel="Chapter" href="Neturl.html">
<link title="Netaddress" rel="Chapter" href="Netaddress.html">
<link title="Netbuffer" rel="Chapter" href="Netbuffer.html">
<link title="Netmime_header" rel="Chapter" href="Netmime_header.html">
<link title="Netmime_channels" rel="Chapter" href="Netmime_channels.html">
<link title="Neturl_ldap" rel="Chapter" href="Neturl_ldap.html">
<link title="Netdate" rel="Chapter" href="Netdate.html">
<link title="Netencoding" rel="Chapter" href="Netencoding.html">
<link title="Netulex" rel="Chapter" href="Netulex.html">
<link title="Netaccel" rel="Chapter" href="Netaccel.html">
<link title="Netaccel_link" rel="Chapter" href="Netaccel_link.html">
<link title="Nethtml" rel="Chapter" href="Nethtml.html">
<link title="Netstring_str" rel="Chapter" href="Netstring_str.html">
<link title="Netmappings" rel="Chapter" href="Netmappings.html">
<link title="Netaux" rel="Chapter" href="Netaux.html">
<link title="Nethttp" rel="Chapter" href="Nethttp.html">
<link title="Netpagebuffer" rel="Chapter" href="Netpagebuffer.html">
<link title="Netfs" rel="Chapter" href="Netfs.html">
<link title="Netglob" rel="Chapter" href="Netglob.html">
<link title="Netauth" rel="Chapter" href="Netauth.html">
<link title="Netsockaddr" rel="Chapter" href="Netsockaddr.html">
<link title="Netnumber" rel="Chapter" href="Netnumber.html">
<link title="Netxdr_mstring" rel="Chapter" href="Netxdr_mstring.html">
<link title="Netxdr" rel="Chapter" href="Netxdr.html">
<link title="Netcompression" rel="Chapter" href="Netcompression.html">
<link title="Netunichar" rel="Chapter" href="Netunichar.html">
<link title="Netasn1" rel="Chapter" href="Netasn1.html">
<link title="Netasn1_encode" rel="Chapter" href="Netasn1_encode.html">
<link title="Netoid" rel="Chapter" href="Netoid.html">
<link title="Netstring_tstring" rel="Chapter" href="Netstring_tstring.html">
<link title="Netdn" rel="Chapter" href="Netdn.html">
<link title="Netx509" rel="Chapter" href="Netx509.html">
<link title="Netascii_armor" rel="Chapter" href="Netascii_armor.html">
<link title="Nettls_support" rel="Chapter" href="Nettls_support.html">
<link title="Netmech_scram" rel="Chapter" href="Netmech_scram.html">
<link title="Netmech_scram_gssapi" rel="Chapter" href="Netmech_scram_gssapi.html">
<link title="Netmech_scram_sasl" rel="Chapter" href="Netmech_scram_sasl.html">
<link title="Netmech_scram_http" rel="Chapter" href="Netmech_scram_http.html">
<link title="Netgssapi_support" rel="Chapter" href="Netgssapi_support.html">
<link title="Netgssapi_auth" rel="Chapter" href="Netgssapi_auth.html">
<link title="Netchannels_crypto" rel="Chapter" href="Netchannels_crypto.html">
<link title="Netx509_pubkey" rel="Chapter" href="Netx509_pubkey.html">
<link title="Netx509_pubkey_crypto" rel="Chapter" href="Netx509_pubkey_crypto.html">
<link title="Netsaslprep" rel="Chapter" href="Netsaslprep.html">
<link title="Netmech_plain_sasl" rel="Chapter" href="Netmech_plain_sasl.html">
<link title="Netmech_crammd5_sasl" rel="Chapter" href="Netmech_crammd5_sasl.html">
<link title="Netmech_digest_sasl" rel="Chapter" href="Netmech_digest_sasl.html">
<link title="Netmech_digest_http" rel="Chapter" href="Netmech_digest_http.html">
<link title="Netmech_krb5_sasl" rel="Chapter" href="Netmech_krb5_sasl.html">
<link title="Netmech_gs2_sasl" rel="Chapter" href="Netmech_gs2_sasl.html">
<link title="Netmech_spnego_http" rel="Chapter" href="Netmech_spnego_http.html">
<link title="Netchannels_tut" rel="Chapter" href="Netchannels_tut.html">
<link title="Netmime_tut" rel="Chapter" href="Netmime_tut.html">
<link title="Netsendmail_tut" rel="Chapter" href="Netsendmail_tut.html">
<link title="Netulex_tut" rel="Chapter" href="Netulex_tut.html">
<link title="Neturl_tut" rel="Chapter" href="Neturl_tut.html">
<link title="Netsys" rel="Chapter" href="Netsys.html">
<link title="Netsys_posix" rel="Chapter" href="Netsys_posix.html">
<link title="Netsys_pollset" rel="Chapter" href="Netsys_pollset.html">
<link title="Netlog" rel="Chapter" href="Netlog.html">
<link title="Netexn" rel="Chapter" href="Netexn.html">
<link title="Netsys_win32" rel="Chapter" href="Netsys_win32.html">
<link title="Netsys_pollset_posix" rel="Chapter" href="Netsys_pollset_posix.html">
<link title="Netsys_pollset_win32" rel="Chapter" href="Netsys_pollset_win32.html">
<link title="Netsys_pollset_generic" rel="Chapter" href="Netsys_pollset_generic.html">
<link title="Netsys_signal" rel="Chapter" href="Netsys_signal.html">
<link title="Netsys_oothr" rel="Chapter" href="Netsys_oothr.html">
<link title="Netsys_xdr" rel="Chapter" href="Netsys_xdr.html">
<link title="Netsys_rng" rel="Chapter" href="Netsys_rng.html">
<link title="Netsys_crypto_types" rel="Chapter" href="Netsys_crypto_types.html">
<link title="Netsys_types" rel="Chapter" href="Netsys_types.html">
<link title="Netsys_mem" rel="Chapter" href="Netsys_mem.html">
<link title="Netsys_tmp" rel="Chapter" href="Netsys_tmp.html">
<link title="Netsys_sem" rel="Chapter" href="Netsys_sem.html">
<link title="Netsys_pmanage" rel="Chapter" href="Netsys_pmanage.html">
<link title="Netsys_crypto" rel="Chapter" href="Netsys_crypto.html">
<link title="Netsys_tls" rel="Chapter" href="Netsys_tls.html">
<link title="Netsys_ciphers" rel="Chapter" href="Netsys_ciphers.html">
<link title="Netsys_digests" rel="Chapter" href="Netsys_digests.html">
<link title="Netsys_crypto_modes" rel="Chapter" href="Netsys_crypto_modes.html">
<link title="Netsys_gssapi" rel="Chapter" href="Netsys_gssapi.html">
<link title="Netsys_sasl_types" rel="Chapter" href="Netsys_sasl_types.html">
<link title="Netsys_sasl" rel="Chapter" href="Netsys_sasl.html">
<link title="Netsys_polypipe" rel="Chapter" href="Netsys_polypipe.html">
<link title="Netsys_polysocket" rel="Chapter" href="Netsys_polysocket.html">
<link title="Netsys_global" rel="Chapter" href="Netsys_global.html">
<link title="Nettls_gnutls_bindings" rel="Chapter" href="Nettls_gnutls_bindings.html">
<link title="Nettls_nettle_bindings" rel="Chapter" href="Nettls_nettle_bindings.html">
<link title="Nettls_gnutls" rel="Chapter" href="Nettls_gnutls.html">
<link title="Netunidata" rel="Chapter" href="Netunidata.html">
<link title="Netgzip" rel="Chapter" href="Netgzip.html">
<link title="Rpc_auth_local" rel="Chapter" href="Rpc_auth_local.html">
<link title="Rpc_xti_client" rel="Chapter" href="Rpc_xti_client.html">
<link title="Rpc" rel="Chapter" href="Rpc.html">
<link title="Rpc_program" rel="Chapter" href="Rpc_program.html">
<link title="Rpc_util" rel="Chapter" href="Rpc_util.html">
<link title="Rpc_portmapper_aux" rel="Chapter" href="Rpc_portmapper_aux.html">
<link title="Rpc_packer" rel="Chapter" href="Rpc_packer.html">
<link title="Rpc_transport" rel="Chapter" href="Rpc_transport.html">
<link title="Rpc_client" rel="Chapter" href="Rpc_client.html">
<link title="Rpc_simple_client" rel="Chapter" href="Rpc_simple_client.html">
<link title="Rpc_portmapper_clnt" rel="Chapter" href="Rpc_portmapper_clnt.html">
<link title="Rpc_portmapper" rel="Chapter" href="Rpc_portmapper.html">
<link title="Rpc_server" rel="Chapter" href="Rpc_server.html">
<link title="Rpc_auth_sys" rel="Chapter" href="Rpc_auth_sys.html">
<link title="Rpc_auth_gssapi" rel="Chapter" href="Rpc_auth_gssapi.html">
<link title="Rpc_proxy" rel="Chapter" href="Rpc_proxy.html">
<link title="Rpc_intro" rel="Chapter" href="Rpc_intro.html">
<link title="Rpc_mapping_ref" rel="Chapter" href="Rpc_mapping_ref.html">
<link title="Rpc_intro_gss" rel="Chapter" href="Rpc_intro_gss.html">
<link title="Shell_sys" rel="Chapter" href="Shell_sys.html">
<link title="Shell" rel="Chapter" href="Shell.html">
<link title="Shell_uq" rel="Chapter" href="Shell_uq.html">
<link title="Shell_fs" rel="Chapter" href="Shell_fs.html">
<link title="Shell_intro" rel="Chapter" href="Shell_intro.html">
<link title="Intro" rel="Chapter" href="Intro.html">
<link title="Platform" rel="Chapter" href="Platform.html">
<link title="Foreword" rel="Chapter" href="Foreword.html">
<link title="Ipv6" rel="Chapter" href="Ipv6.html">
<link title="Regexp" rel="Chapter" href="Regexp.html">
<link title="Tls" rel="Chapter" href="Tls.html">
<link title="Crypto" rel="Chapter" href="Crypto.html">
<link title="Authentication" rel="Chapter" href="Authentication.html">
<link title="Credentials" rel="Chapter" href="Credentials.html">
<link title="Gssapi" rel="Chapter" href="Gssapi.html">
<link title="Ocamlnet4" rel="Chapter" href="Ocamlnet4.html">
<link title="Get" rel="Chapter" href="Get.html"><title>Ocamlnet 4 Reference Manual : Neturl_tut</title>
</head>
<body>
<div class="navbar"><a class="pre" href="Netulex_tut.html" title="Netulex_tut">Previous</a>
<a class="up" href="index.html" title="Index">Up</a>
<a class="post" href="Netsys.html" title="Netsys">Next</a>
</div>
<h1>Neturl_tut</h1>
<div class="info-desc">
<h2 id="tutorial">Neturl Tutorial</h2>
<p>This module is a quite flexible parser for various kinds of URLs
occuring in practice. The syntax is configurable such that one
URL module can handle a lot of URL types in a generic way.</p>
<h3 id="2_GenericParsing">Generic Parsing</h3>
<p>In order to parse an absolute URL (beginning with a scheme identifier
like "http:...") of unknown type just call</p>
<pre class="codepre"><code class="code">
let url = parse_url "http://me@server/directory"
</code></pre>
<p>By default, this function can parse all URL types listed
at <a href="Neturl.html#VALcommon_url_syntax"><code class="code">Neturl.common_url_syntax</code></a>. However, the default configuration
implies also that</p>
<ul>
<li>relative URLs cannot be parsed</li>
<li>fragment identifiers are rejected (i.e. the part after the hash
mark like in "http://server/document#location")</li>
<li>characters are rejected when the most significant bit (MSB) is set</li>
</ul>
<p>The latter two features can be simply enabled by passing the
arguments <code class="code">~enable_fragment:true</code> and <code class="code">~accept_8bits:true</code>,
respectively.</p>
<p>The restriction that relative URLs are rejected has to do with
the problem that context information is missing. Because the scheme
identifier (like "http") is not available, the function does not
know which syntax the relative URL should have. For example,
the relative URL <code class="code">dir/file?x=1</code> is differently parsed when
it is taken relative to an <code class="code">http</code> URL and when it is interpreted
relative to an <code class="code">ftp</code> URL. In the first case, the path component
of the URL is <code class="code">"dir/file"</code> and the query component is <code class="code">"?x=1"</code>,
but in the latter case the path component is <code class="code">"dir/file?x=1"</code>,
and a query component is not allowed.</p>
<p>The solution is that the syntax of the base URL, relative to which
the URL is seen, must be passed as additional argument. Under the
assumption that <code class="code">base_url</code> is the base URL, use</p>
<pre class="codepre"><code class="code">let url = parse_url
~base_syntax:(url_syntax_of_url base_url)
"/dir/file?x=1"
</code></pre><p>Of course, this assumes that the base URL is known when the url
is parsed.</p>
<h3 id="2_ParsingForaCertainSyntax">Parsing For a Certain Syntax</h3>
<p>The function <code class="code">url_of_string</code> is also a parser, but you must pass
the URL syntax as argument, e.g.</p>
<pre class="codepre"><code class="code">let url = url_of_string syntax "ipp://server/printer"
</code></pre><p>Pass as <code class="code">syntax</code> one of the elements of <a href="Neturl.html#VALcommon_url_syntax"><code class="code">Neturl.common_url_syntax</code></a>,
e.g.</p>
<pre class="codepre"><code class="code"> let syntax = Hashtbl.find common_url_syntax "ipp" </code></pre><p>or a self-defined syntax.</p>
<h3 id="2_PrintingURLs">Printing URLs</h3>
<p>This is much easier, just call <code class="code">string_of_url</code> to convert an URL
to a string. It is ensured that every URL always has an
unambiguous representation as string.</p>
<h3 id="2_URLComponents">URL Components</h3>
<p>Internally, the parsed URL is decomposed into its components. This
module supports two ways of decomposition:</p>
<OL>
<li><code class="code">scheme://user;userparams:password@host:port/path;params?query#fragment</code></li>
<li><code class="code">scheme:other;params?query#fragment</code></li>
</OL>
<p>The first form is used for services that directly connect to a
certain service running on a certain host. The second form can
be used for everything else not falling under this category.</p>
<p>Examples:</p>
<ul>
<li><code class="code">http://me:abrakadabra@server/dir?x=5#section1</code>
scheme=<code class="code">"http"</code>, user=<code class="code">"me"</code>, password=<code class="code">"abrakadabra"</code>, host=<code class="code">"server"</code>,
path=<code class="code">"/dir"</code>, query=<code class="code">"x=5"</code>, fragment=<code class="code">"section1"</code> </li>
<li><code class="code">pop://you;auth=digest-md5@mail</code>
scheme=<code class="code">"pop"</code>, user=<code class="code">"you"</code>, user_params=<code class="code">["auth=digest-md5"]</code>, host=<code class="code">"mail"</code> </li>
<li><code class="code">mailto:gerd@gerd-stolpmann.de?cc=you@domain.com</code>
scheme=<code class="code">"mailto"</code>, other=<code class="code">"gerd@gerd-stolpmann.de"</code>,
query=<code class="code">"cc=you@domain.com"</code> </li>
</ul>
<p>It is important to mention that the decomposition is not fully
performed, but only down to a certain level. For example, the
query <code class="code">"x=5"</code> could be further analysed and be split into
the syntactic parts <code class="code">"x"</code> and <code class="code">"5"</code>. However, this is not done,
just because the author seeked a compromise between the depth
of analysis and the genericy of application.</p>
<h3 id="2_URLEscaping">URL Escaping</h3>
<p>In order to represent the so-called unsafe characters, one can
use <code class="code">%</code>-escaping in URLs. For example, this URL contains a
password with <code class="code">@</code>, an unsafe character encoded as <code class="code">%40</code>:</p>
<pre class="codepre"><code class="code"> http://user:!$%40?@server </code></pre><p>The question is how this module handles such escapings.</p>
<p>It is surprising that the URL parser does not decode these
escaped forms (it checks, however, whether they are syntactically
correct). Internally, the components are stored as parsed,
and one can even retrieve them in their original form.
The function <code class="code">url_password</code> returns the password component.
Applied to the above URL, one can get the password in
its original, "encoded" form, or as decoded string:</p>
<ul>
<li><code class="code">url_password ~encoded:true url</code> returns <code class="code">"!$%40?"</code></li>
<li><code class="code">url_password url</code> returns <code class="code">"!$@?"</code></li>
</ul>
<h3 id="2_RepresentationofURLComponents">Representation of URL Components</h3>
<p>The URL components can be retrieved with the functions</p>
<ul>
<li><code class="code">url_scheme</code></li>
<li><code class="code">url_user</code></li>
<li><code class="code">url_user_param</code></li>
<li><code class="code">url_password</code></li>
<li><code class="code">url_host</code></li>
<li><code class="code">url_port</code></li>
<li><code class="code">url_path</code></li>
<li><code class="code">url_param</code></li>
<li><code class="code">url_query</code></li>
<li><code class="code">url_fragment</code></li>
<li><code class="code">url_other</code></li>
</ul>
<p>Most components are just strings. Of course, the port number is an
integer.</p>
<p>The path component (<code class="code">url_path</code>) has a non-obvious representation. The path
is represented as string list, e.g. "a/b/c" is represented
as <code class="code"> ["a";"b";"c"] </code>. Note, however, that absolute paths have
an empty string at the beginning of the list, e.g.
"/a/b/" is <code class="code"> [""; "a"; "b"; "" ] </code>. In most cases, the paths
found in URLs are absolute, and because of this it is quite
common to find this empty string at the beginning of the
path list. The corner cases are:</p>
<ul>
<li><code class="code"> [] </code> is used when the path is missing in the URL</li>
<li><code class="code"> [ "" ] </code> is "/"</li>
<li><code class="code"> [ ""; "" ] </code> is considered as illegal</li>
</ul>
<p>The last two cases are somewhat arbitrary.</p>
<p>There is the helper function <code class="code">split_path</code> to convert the string
representation of paths into the list representation.</p>
<p>The parameters (<code class="code">url_user_param</code> and <code class="code">url_param</code>) are lists, too.
A parameter starts with a semicolon as delimiter and runs until
the next component, which can be another parameter. The contents,
i.e. the values after the semicolons are put into the list. For example,
the parameter ";auth=unix;type=i" is represented as
<code class="code"> ["auth=unix"; "type=i"] </code>.</p>
<h3 id="2_HintGettingQueryArguments">Hint: Getting Query Arguments</h3>
<p>The query component is represented as a single string. When queries
use the standard syntax "name1=value1&name2=value2&...", one can
parse this string using</p>
<pre class="codepre"><code class="code">let args = Netencoding.Url.dest_url_encoded_parameters
(url_query ~encoded:true url)
</code></pre><p>Note that <code class="code">encoded:true</code> is needed.</p>
<h3 id="2_CreatingandModifyingURLs">Creating and Modifying URLs</h3>
<p>In order to create a URL for a certain syntax, call <code class="code">make_url</code>:</p>
<pre class="codepre"><code class="code">let url = make_url
~scheme:"http"
~user:"user"
~password:"!$@?"
~host:"server"
syntax
</code></pre><p>It is checked whether the URL conforms to the passed syntax. By default,
the components are passed in decoded form, and <code class="code">make_url</code> automatically
encodes them if necessary (here, for example, the at sign in the
password). Alternatively, one can set <code class="code">~encoded:true</code>, and pass the
already escaped components. In this case, <code class="code">make_url</code> checks whether
the encoding is sufficient to represent the URL as string.</p>
<p>The functions <code class="code">modify_url</code>, <code class="code">default_url</code>, <code class="code">undefault_url</code>, and
<code class="code">remove_from_url</code> can be used to modify an existing URL.</p>
<h3 id="2_RelativeURLs">Relative URLs</h3>
<p>A URL is relative when the scheme identifier at the beginning is
omitted. In this case, the URL can be transformed to an absolute
URL when the base URL is known. The algorithm for this is defined
in RFC 1808, and quite complicated. It is implemented in
<code class="code">apply_relative_url</code>, but usually <a href="Neturl.html#VALensure_absolute_url"><code class="code">Neturl.ensure_absolute_url</code></a>
is the more convenient function. Just call</p>
<pre class="codepre"><code class="code"> let url' = ensure_absolute_url ~base url </code></pre><p>to convert <code class="code">url</code> to its absolute counterpart <code class="code">url'</code> when it is
relative, and to pass the URL unchanged when it is already
absolute.</p>
</div>
</body></html>
|
