1# UTILS 2 3`FoX_utils` 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. 4 5All functions are accessible from the `FoX_utils` module. 6 7NB 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. 8 9For any end-users interested in the code who are worried about interface changes, it is recommended that the relevant code (all found in the `utils/` directory be lifted directly and imported into other projects, rather than accessed through the FoX interfaces. 10 11Two sets of utility functions are provided; one concerned with [UUID](#UUID)s, and a set concerned with [URI](#URI)s. 12 13<a name="UUID"/> 14 15## UUID 16 17UUIDs (see [RFC 4122](http://tools.ietf.org/html/rfc4122)) are Universally Unique IDentifiers. They are a 128-bit number, represented as a 36-character string. For example: 18 19 f81d4fae-7dec-11d0-a765-00a0c91e6bf6 20 21The 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. 22 23This 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 24 25 urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 26 27UUIDs 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. 28 29In 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 [this service](http://www.famkruithof.net/uuid/uuidgen?typeReq=-1)) to verify creation time. 30 31This 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. 32 33* `generate_UUID` 34**version**: *integer* 35 36This function returns a 36-character string containing the UUID. 37 38**version** 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. 39 40Version 1 is the default, and is recommended. 41 42(Note: all pseudo-random-numbers are generated using the high-quality Mersenne Twister algorithm, using the Fortran implementation of [Scott Robert Ladd](http://www.coyotegulch.com).) 43 44<a name="URI"/> 45 46## URI 47 48URIs (see [RFC 2396](http://tools.ietf.org/html/rfc2396)) 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. 49 50For example: 51 52 http://www.uszla.me.uk/FoX/DoX/index.html 53 54is a URI pointing to the FoX documentation. 55 56Equally, however: 57 58 FoX/configure 59 60is a URI reference pointing to the FoX configure script (relative to the current directory, or `base URI`). 61 62A string which is a URI reference contains several components, some of which are optional. 63 64* `scheme` - eg, `http` 65* `authority` - eg, `www.uszla.me.uk` 66* `path` - eg, `/FoX/DoX/index.html` 67 68In addition, a URI reference may contain `userinfo`, `host`, `port`, `query`, and `fragment` information. (see the [RFC](http://tools.ietf.org/html/rfc2396) for full details.) 69 70The FoX URI library provides the following features: 71 72* `type(URI)` 73This is an opaque Fortran type which is used to hold URI information. The functions described below use this type. 74 75* `parseURI` 76This takes one argument, a URI reference, and returns a pointer to a newly-allocated URI object. 77 78If 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. 79 80* `expressURI` 81This takes one argument, a URI object, and returns the (fully-escaped) string representing that URI. 82 83* `rebaseURI` 84This 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. 85 86Thus, if the first URI were `/FoX/DoX`, and the second `../DoX2/index.html`, then the resulting URI would be `/FoX/DoX2/index.html` 87 88* `destroyURI` 89This takes one argument, a pointer to a URI object, and clears up all memory associated with it. 90 91For each component a URI might have (`scheme`, `authority`, `userinfo`, `host`, `port`, `path`, `query`, `fragment`) there are two functions for extracting the component: 92 93* `hasXXX` will return a logical variable according to whether the component is defined. (except for `path` which is always defined, but may be empty) 94 95* `getXXX` will return a string containing the value of the component. (except for `port` which is returned as an integer. 96 97Thus, listing these functions in full: 98 99* `hasScheme` 100Is there a scheme associated with the URI? 101 102* `getScheme` 103Return the value of the scheme 104 105* `hasAuthority` 106Is there an authority associated with the URI? 107 108* `getAuthority` 109Return the value of the authority 110 111* `hasUserinfo` 112Is there userinfo associated with the URI? 113 114* `getUserinfo` 115Return the value of the userinfo 116 117* `hasHost` 118Is there a host associated with the URI? 119 120* `getHost` 121Return the value of the host 122 123* `hasPort` 124Is there a port associated with the URI? 125 126* `getPort` 127Return the value of the port 128 129* `getPath` 130Return the value of the path 131 132* `hasQuery` 133Is there a query associated with the URI? 134 135* `getQuery` 136Return the value of the query 137 138* `hasFragment` 139Is there a fragment associated with the URI? 140 141* `getFragment` 142Return the value of the fragment 143 144