README 3.29 KB
Newer Older
1 2
uri-template is an implementation of the URI Template proposed
standard draft version 01
3
(https://tools.ietf.org/html/draft-gregorio-uritemplate-01) as a reader
4
macro, used for both creating and parsing URIs.
5 6 7 8 9 10

Although uri-template does not implement the operators introduced in
the 02 and later drafts of the URI Template standard, it does allow
arbitrary Lisp expressions in template placeholders, which gives
simpler and more powerful templates.

11 12 13 14 15
Example use:

Template interpolation:

(let ((foo 1))
16
  #Uhttps://www.example.com/widget/{foo}/parts)
17

18
=> "https://www.example.com/widget/1/parts"
19 20 21 22


Template destructuring:

23 24
(uri-template-bind (#Uhttps://www.example.com/{part}/{number})
    "https://www.example.com/widget/1"
25 26 27 28 29 30 31 32 33
  (list part (parse-integer number) %uri-host))

=> ("widget" 1 "www.example.com")


Template desctructuring also binds several handy standard components
to anaphoric variables:

(uri-template-bind (#U{uri})
34
    "https://user@www.foo.com:8080/dir/abc?bar=baz&xyz=1#hash"
35 36 37 38 39 40 41 42 43 44
  (list %uri-scheme          =>     ("http"
        %uri-authority               "user@www.foo.com:8080"
        %uri-user                    "user"
        %uri-host                    "www.foo.com"
        %uri-port                    "8080"
        %uri-path                    "/dir/abc"
        %uri-directory               "/dir/"
        %uri-file                    "abc"
        %uri-query                   "bar=baz&xyz=1"
        %uri-fragment                "hash"
45
        %uri-head                    "https://user@www.foo.com:8080"
46
        %uri-tail))                  "/dir/abc?bar=baz&xyz=1#hash")
47

48
More examples can be found in the uri-template-test.lisp file.
49

50 51
uri-templates can be enabled by merging or using the
uri-template:uri-template readtable via the named-readtables library:
52
https://common-lisp.net/project/named-readtables/
53 54 55 56 57 58 59 60

Function reference:

read-uri-template (function)
  A function suitable for inserting into the readtable so you can
  read URI templates from your own dispatch character.

uri-template (symbol)
61
  This symbol names the named-readtables readtable that provides
62 63 64 65 66 67 68
  the #U dispatch macro.

uri-template-bind (macro)
  Binds URI template placeholders (which must be symbols) in given
  URI, as well as attempting to bind a set of standard URI components to
  their respective parts of the given URI. Body executes only if all
  explicitly specified URI template placeholders can be bound.
69 70 71 72 73 74 75 76

uri-template works with Parenscript to provide template interpolation
for JavaScript. To enable this functionality, load Parenscript before
compiling uri-template (you might need to re-compile if you have
previously loaded uri-template without first loading
Parenscript). Note that destructuring is currently unsupported for
Parenscript.

77
For more information about uri-template, see the project homepage:
78
https://common-lisp.net/project/uri-template/
79

80 81 82 83
The uri-template mailing list is: uri-template-devel@common-lisp.net
Any questions, bug reports and patches are welcome.
You can subscribe by visiting:
https://mailman.common-lisp.net/listinfo/uri-template-devel
84

85
The author, Vladimir Sedach, can be contacted at: vas@oneofus.la
86

87 88 89
uri-template is distributed under the terms of the GNU General Public
License, version 3 or any later version. See the file COPYING,
included with the distribution, or https://www.gnu.org/licenses/