/
FoX_utils.html
155 lines (113 loc) · 7.59 KB
/
FoX_utils.html
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
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>FoX_utils</title>
<link rel="stylesheet" type="text/css" href="DoX.css"/>
</head>
<body>
<div class="DoX">
<h1>UTILS</h1>
<p><code>FoX_utils</code> is a collection of general utility functions that the rest of FoX depends on, but which may be of independent use. They are documented here.</p>
<p>All functions are accessible from the <code>FoX_utils</code> module. </p>
<p>NB Unlike the APIs of WXML, WCML, and SAX, the UTILS APIs may not remain constant between FoX versions. While some effort will be expended to ensure they don't change unnecessarily, no guarantees are made.</p>
<p>For any end-users interested in the code who are worried about interface changes, it is recommended that the relevant code (all found in the <code>utils/</code> directory be lifted directly and imported into other projects, rather than accessed through the FoX interfaces.</p>
<p>Two sets of utility functions are provided; one concerned with <a href="#UUID">UUID</a>s, and a set concerned with <a href="#URI">URI</a>s.</p>
<p><a name="UUID"/></p>
<h2>UUID</h2>
<p>UUIDs (see <a href="http://tools.ietf.org/html/rfc4122">RFC 4122</a>) are Universally Unique IDentifiers. They are a 128-bit number, represented as a 36-character string. For example:</p>
<pre><code> f81d4fae-7dec-11d0-a765-00a0c91e6bf6
</code></pre>
<p>The intention of UUIDs is to enable distributed systems to uniquely identify information without significant central coordination. Thus, anyone can create a UUID and use it to identify something with reasonable confidence that the identifier will never be unintentionally used by anyone for anything else.</p>
<p>This property also makes them useful as Uniform Resource Names, to refer to a given document without requiring a position in a particular URI scheme. Thus the above UUID could be referred to as</p>
<pre><code>urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
</code></pre>
<p>UUIDs are used by WCML to ensure that every document generated has a unique ID. This enables users to go back later on and have confidence that they are examining the same document, regardless of where it might have ended up in file-system hierarchies or databases.</p>
<p>In addition, UUIDs come in several flavours, one of which stores the time of creation to 100-nanosecond accuracy. This can later be extracted (see, for example <a href="http://www.famkruithof.net/uuid/uuidgen?typeReq=-1">this service</a>) to verify creation time.</p>
<p>This may well be useful for other XML document types, or indeed in non-XML applications. Thus, UUIDs may be generated by the following function, with one optional argument.</p>
<ul>
<li><code>generate_UUID</code> <br />
<strong>version</strong>: <em>integer</em></li>
</ul>
<p>This function returns a 36-character string containing the UUID.</p>
<p><strong>version</strong> identifies the version of UUID to be used (see section 4.1.3 of the RFC). Only versions 0, 1, and 4 are supported. Version 0 generates a nil UUID; version 1 a time-based UUID, and version 4 a pseudo-randomly-generated UUID.</p>
<p>Version 1 is the default, and is recommended.</p>
<p>(Note: all pseudo-random-numbers are generated using the high-quality Mersenne Twister algorithm, using the Fortran implementation of <a href="http://www.coyotegulch.com">Scott Robert Ladd</a>.)</p>
<p><a name="URI"/></p>
<h2>URI</h2>
<p>URIs (see <a href="http://tools.ietf.org/html/rfc2396">RFC 2396</a>) are Universal Resource Identifiers. A URI is a string, containing several components, which identifies a resource. Very often, this resource is a file, and the URI represents the local or network path to this file.</p>
<p>For example:</p>
<pre><code>http://www.uszla.me.uk/FoX/DoX/index.html
</code></pre>
<p>is a URI pointing to the FoX documentation.</p>
<p>Equally, however:</p>
<pre><code>FoX/configure
</code></pre>
<p>is a URI reference pointing to the FoX configure script (relative to the current directory, or <code>base URI</code>).</p>
<p>A string which is a URI reference contains several components, some of which are optional.</p>
<ul>
<li><code>scheme</code> - eg, <code>http</code></li>
<li><code>authority</code> - eg, <code>www.uszla.me.uk</code></li>
<li><code>path</code> - eg, <code>/FoX/DoX/index.html</code></li>
</ul>
<p>In addition, a URI reference may contain <code>userinfo</code>, <code>host</code>, <code>port</code>, <code>query</code>, and <code>fragment</code> information. (see the <a href="http://tools.ietf.org/html/rfc2396">RFC</a> for full details.)</p>
<p>The FoX URI library provides the following features:</p>
<ul>
<li><p><code>type(URI)</code>
This is an opaque Fortran type which is used to hold URI information. The functions described below use this type.</p></li>
<li><p><code>parseURI</code>
This takes one argument, a URI reference, and returns a pointer to a newly-allocated URI object.</p></li>
</ul>
<p>If the string provided is not a valid URI reference, then a null pointer is returned; thus this function can be used to check whether a URI is valid.</p>
<ul>
<li><p><code>expressURI</code>
This takes one argument, a URI object, and returns the (fully-escaped) string representing that URI.</p></li>
<li><p><code>rebaseURI</code>
This takes two arguments, both URI objects, and returns a pointer to a third URI object. It calculates the location of the second URI with reference to the first.</p></li>
</ul>
<p>Thus, if the first URI were <code>/FoX/DoX</code>, and the second <code>../DoX2/index.html</code>, then the resulting URI would be <code>/FoX/DoX2/index.html</code></p>
<ul>
<li><code>destroyURI</code>
This takes one argument, a pointer to a URI object, and clears up all memory associated with it.</li>
</ul>
<p>For each component a URI might have (<code>scheme</code>, <code>authority</code>, <code>userinfo</code>, <code>host</code>, <code>port</code>, <code>path</code>, <code>query</code>, <code>fragment</code>) there are two functions for extracting the component:</p>
<ul>
<li><p><code>hasXXX</code> will return a logical variable according to whether the component is defined. (except for <code>path</code> which is always defined, but may be empty)</p></li>
<li><p><code>getXXX</code> will return a string containing the value of the component. (except for <code>port</code> which is returned as an integer.</p></li>
</ul>
<p>Thus, listing these functions in full:</p>
<ul>
<li><p><code>hasScheme</code>
Is there a scheme associated with the URI?</p></li>
<li><p><code>getScheme</code>
Return the value of the scheme</p></li>
<li><p><code>hasAuthority</code>
Is there an authority associated with the URI?</p></li>
<li><p><code>getAuthority</code>
Return the value of the authority</p></li>
<li><p><code>hasUserinfo</code>
Is there userinfo associated with the URI?</p></li>
<li><p><code>getUserinfo</code>
Return the value of the userinfo</p></li>
<li><p><code>hasHost</code>
Is there a host associated with the URI?</p></li>
<li><p><code>getHost</code>
Return the value of the host</p></li>
<li><p><code>hasPort</code>
Is there a port associated with the URI?</p></li>
<li><p><code>getPort</code>
Return the value of the port</p></li>
<li><p><code>getPath</code>
Return the value of the path</p></li>
<li><p><code>hasQuery</code>
Is there a query associated with the URI?</p></li>
<li><p><code>getQuery</code>
Return the value of the query</p></li>
<li><p><code>hasFragment</code>
Is there a fragment associated with the URI?</p></li>
<li><p><code>getFragment</code>
Return the value of the fragment</p></li>
</ul>
</div>
</body>
</html>