1 | URL Pathnames ABCL |
---|
2 | ================== |
---|
3 | |
---|
4 | Mark Evenson |
---|
5 | Created: 25 MAR 2010 |
---|
6 | Modified: 21 JUN 2011 |
---|
7 | |
---|
8 | Notes towards an implementation of URL references to be contained in |
---|
9 | Common Lisp `PATHNAME` objects within ABCL. |
---|
10 | |
---|
11 | |
---|
12 | References |
---|
13 | ---------- |
---|
14 | |
---|
15 | RFC3986 Uniform Resource Identifier (URI): Generic Syntax |
---|
16 | |
---|
17 | |
---|
18 | URL vs URI |
---|
19 | ---------- |
---|
20 | |
---|
21 | We use the term URL as shorthand in describing the URL Pathnames, even |
---|
22 | though the corresponding encoding is more akin to a URI as described |
---|
23 | in RFC3986. |
---|
24 | |
---|
25 | |
---|
26 | Goals |
---|
27 | ----- |
---|
28 | |
---|
29 | 1. Use Common Lisp pathnames to refer to representations referenced |
---|
30 | by a URL. |
---|
31 | |
---|
32 | 2. The URL schemes supported shall include at least "http", and those |
---|
33 | enabled by the URLStreamHandler extension mechanism. |
---|
34 | |
---|
35 | 3. Use URL schemes that are understood by the java.net.URL object. |
---|
36 | |
---|
37 | Example of a Pathname specified by URL: |
---|
38 | |
---|
39 | #p"http://example.org/org/armedbear/systems/pgp.asd" |
---|
40 | |
---|
41 | 4. MERGE-PATHNAMES |
---|
42 | |
---|
43 | (merge-pathnames "url.asd" |
---|
44 | "http://example/org/armedbear/systems/pgp.asd") |
---|
45 | ==> "http://example/org/armedbear/systems/url.asd" |
---|
46 | |
---|
47 | 5. PROBE-FILE returning the state of URL accesibility. |
---|
48 | |
---|
49 | 6. TRUENAME "aliased" to PROBE-FILE signalling an error if the URL is |
---|
50 | not accessible (see "Non-goal 1"). |
---|
51 | |
---|
52 | 7. DIRECTORY works for non-wildcards. |
---|
53 | |
---|
54 | 8. URL pathname work as a valid argument for OPEN with :DIRECTION :INPUT. |
---|
55 | |
---|
56 | 9. Enable the loading of ASDF2 systems referenced by a URL pathname. |
---|
57 | |
---|
58 | 10. Pathnames constructed with the "file" scheme |
---|
59 | (i.e. #p"file:/this/file") need to be properly URI encoded according |
---|
60 | to RFC3986 or otherwise will signal FILE-ERROR. |
---|
61 | |
---|
62 | 11. The "file" scheme will continue to be represented by an |
---|
63 | "ordinary" Pathname. Thus, after construction of a URL Pathname with |
---|
64 | the "file" scheme, the namestring of the resulting PATHNAME will no |
---|
65 | longer contain the "file:" prefix. |
---|
66 | |
---|
67 | 12. The "jar" scheme will continue to be represented by a jar |
---|
68 | Pathname. |
---|
69 | |
---|
70 | |
---|
71 | Non-goals |
---|
72 | --------- |
---|
73 | |
---|
74 | 1. We will not implement canonicalization of URL schemas (such as |
---|
75 | following "http" redirects). |
---|
76 | |
---|
77 | 2. DIRECTORY will not work for URL pathnames containing wildcards. |
---|
78 | |
---|
79 | |
---|
80 | Implementation |
---|
81 | -------------- |
---|
82 | |
---|
83 | A PATHNAME refering to a resource referenced by a URL is known as a |
---|
84 | URL PATHNAME. |
---|
85 | |
---|
86 | A URL PATHNAME always has a HOST component which is a proper list. |
---|
87 | This list will be an property list (plist). The property list |
---|
88 | values must be character strings. |
---|
89 | |
---|
90 | :SCHEME |
---|
91 | Scheme of URI ("http", "ftp", "bundle", etc.) |
---|
92 | :AUTHORITY |
---|
93 | Valid authority according to the URI scheme. For "http" this |
---|
94 | could be "example.org:8080". |
---|
95 | :QUERY |
---|
96 | The query of the URI |
---|
97 | :FRAGMENT |
---|
98 | The fragment portion of the URI |
---|
99 | |
---|
100 | The DIRECTORY, NAME and TYPE fields of the PATHNAME are used to form |
---|
101 | the URI `path` according to the conventions of the UNIX filesystem |
---|
102 | (i.e. '/' is the directory separator). In a sense the HOST contains |
---|
103 | the base URL, to which the `path` is a relative URL (although this |
---|
104 | abstraction is violated somwhat by the storing of the QUERY and |
---|
105 | FRAGMENT portions of the URI in the HOST component). |
---|
106 | |
---|
107 | For the purposes of PATHNAME-MATCH-P, two URL pathnames may be said to |
---|
108 | match if their HOST compoments are EQUAL, and all other components are |
---|
109 | considered to match according to the existing rules for Pathnames. |
---|
110 | |
---|
111 | A URL pathname must have a DEVICE whose value is NIL. |
---|
112 | |
---|
113 | Upon creation, the presence of ".." and "." components in the |
---|
114 | DIRECTORY are removed. The DIRECTORY component, if present, is always |
---|
115 | absolute. |
---|
116 | |
---|
117 | The namestring of a URL pathname shall be formed by the usual |
---|
118 | conventions of a URL. |
---|
119 | |
---|
120 | A URL Pathname has type URL-PATHNAME, derived from PATHNAME. |
---|
121 | |
---|
122 | |
---|
123 | URI Encoding |
---|
124 | ------------ |
---|
125 | |
---|
126 | For dealing with URI Encoding (also known as [Percent Encoding]() we |
---|
127 | adopt the following rules |
---|
128 | |
---|
129 | [Percent Encoding]: http://en.wikipedia.org/wiki/Percent-encoding |
---|
130 | |
---|
131 | 1. All pathname components are represented "as is" without escaping. |
---|
132 | |
---|
133 | 2. Namestrings are suitably escaped if the Pathname is a URL-PATHNAME |
---|
134 | or a JAR-PATHNAME. |
---|
135 | |
---|
136 | 3. Namestrings should all "round-trip": |
---|
137 | |
---|
138 | (when (typep p 'pathname) |
---|
139 | (equal (namestring p) |
---|
140 | (namestring (pathname p)))) |
---|
141 | |
---|
142 | |
---|
143 | Status |
---|
144 | ------ |
---|
145 | |
---|
146 | This design has been implemented. |
---|
147 | |
---|
148 | |
---|
149 | History |
---|
150 | ------- |
---|
151 | |
---|
152 | 26 NOV 2010 Changed implemenation to use URI encodings for the "file" |
---|
153 | schemes including those nested with the "jar" scheme by like |
---|
154 | aka. "jar:file:/location/of/some.jar!/". |
---|
155 | |
---|
156 | 21 JUN 2011 Fixed implementation to properly handle URI encodings |
---|
157 | refering nested jar archive. |
---|
158 | |
---|