The uri-template Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The uri-template Reference Manual

This is the uri-template Reference Manual, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:43:06 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

uri-template is an implementation of the URI Template proposed
standard draft version 01
(http://tools.ietf.org/html/draft-gregorio-uritemplate-01) as a reader
macro, used for both creating and parsing URIs.

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.

Example use:

Template interpolation:

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

=> "http://www.example.com/widget/1/parts"


Template destructuring:

(uri-template-bind (#Uhttp://www.example.com/{part}/{number})
    "http://www.example.com/widget/1"
  (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})
    "http://user@www.foo.com:8080/dir/abc?bar=baz&xyz=1#hash"
  (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"
        %uri-head                    "http://user@www.foo.com:8080"
        %uri-tail))                  "/dir/abc?bar=baz&xyz=1#hash")

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

uri-templates can be enabled by calling enable-uri-template-syntax, or
by merging or using the uri-template:uri-template readtable via the
named-readtables library
(http://common-lisp.net/project/named-readtables/)

Function reference:

enable-uri-template-syntax (function)
  Binds the #U dispatch character to read a URI template.

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

uri-decode? (special variable)
  Controls whether URI decoding/unescaping is done on the templated
  value when destructuring. True by default.

uri-encode? (special variable)
  Controls whether URI encoding/escaping is done on the templated value.
  True by default.

uri-decode (function)
  Decodes URI encoded/escaped characters in the given string.

uri-encode (function)
  URI encodes/escapes the given string.

uri-template (symbol)
  The car of the list that the URI template reader produces. A
  function or macro.
  This symbol also names the named-readtables readtable that provides
  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.

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.

For more information about uri-template, see the project homepage:
http://common-lisp.net/project/uri-template/

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:
http://common-lisp.net/cgi-bin/mailman/listinfo/uri-template-devel

The author, Vladimir Sedach, can be contacted at vsedach@gmail.com.

The code is licensed under the LLGPL (see the file COPYING included
with the distribution for details), except for the unit tests, which
are in the public domain.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 uri-template

Author

Vladimir Sedach <vsedach@gmail.com>

License

LLGPLv3

Description

An implementation of the URI Template proposed standard draft version 01.

Long Description

An implementation of the URI Template proposed standard draft version 01.
Lets you easily create and parse URIs by using the URI Template reader macro syntax.

Dependencies
Source

uri-template.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 uri-template.asd

Location

uri-template.asd

Systems

uri-template (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 uri-template/package.lisp

Parent

uri-template (system)

Location

package.lisp

Packages

uri-template


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 uri-template/uri-template.lisp

Dependency

package.lisp (file)

Parent

uri-template (system)

Location

uri-template.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 uri-template/destructure-uri.lisp

Dependency

uri-template.lisp (file)

Parent

uri-template (system)

Location

destructure-uri.lisp

Exported Definitions
Internal Definitions

weak-register-groups-bind (macro)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 uri-template

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: uri-decode?

Controls whether URI decoding/unescaping is done on the templated value when destructuring. True by default.

Package

uri-template

Source

destructure-uri.lisp (file)

Special Variable: uri-encode?

Controls whether URI encoding/escaping is done on the templated value. True by default.

Package

uri-template

Source

uri-template.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Macros

Macro: uri-template-bind (TEMPLATE) URI &body BODY

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.

Given the example URI http://user@www.foo.com:8080/dir/abc?bar=baz&xyz=1#hash The standard URI components look like:

%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
%uri-head http://user@www.foo.com:8080
%uri-tail /dir/abc?bar=baz&xyz=1#hash

Package

uri-template

Source

destructure-uri.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: enable-uri-template-syntax ()

Binds the #U dispatch character to read a URI template.

Package

uri-template

Source

uri-template.lisp (file)

Function: read-uri-template STREAM &optional RECURSIVE-P

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

Package

uri-template

Source

uri-template.lisp (file)

Function: uri-decode STR

Decodes URI encoded/escaped characters in the given string.

Package

uri-template

Source

destructure-uri.lisp (file)

Function: uri-encode STR

URI encodes/escapes the given string.

Package

uri-template

Source

uri-template.lisp (file)

Function: uri-template &rest TEMPLATE-ARGS

The car of the list that the URI template reader produces. A function or macro.

This symbol also names the named-readtables readtable that provides the #U dispatch macro.

Package

uri-template

Source

uri-template.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Macros

Macro: maybe-uri-encode X
Package

uri-template

Source

uri-template.lisp (file)

Macro: weak-register-groups-bind VARS REGEX STR &body BODY
Package

uri-template

Source

destructure-uri.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: uri-template-reader STREAM SUBCHAR ARG
Package

uri-template

Source

uri-template.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   U  
Index Entry  Section

F
File, Lisp, uri-template.asd: The uri-template<dot>asd file
File, Lisp, uri-template/destructure-uri.lisp: The uri-template/destructure-uri<dot>lisp file
File, Lisp, uri-template/package.lisp: The uri-template/package<dot>lisp file
File, Lisp, uri-template/uri-template.lisp: The uri-template/uri-template<dot>lisp file

L
Lisp File, uri-template.asd: The uri-template<dot>asd file
Lisp File, uri-template/destructure-uri.lisp: The uri-template/destructure-uri<dot>lisp file
Lisp File, uri-template/package.lisp: The uri-template/package<dot>lisp file
Lisp File, uri-template/uri-template.lisp: The uri-template/uri-template<dot>lisp file

U
uri-template.asd: The uri-template<dot>asd file
uri-template/destructure-uri.lisp: The uri-template/destructure-uri<dot>lisp file
uri-template/package.lisp: The uri-template/package<dot>lisp file
uri-template/uri-template.lisp: The uri-template/uri-template<dot>lisp file

Jump to:   F   L   U  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   E   F   M   R   U   W  
Index Entry  Section

E
enable-uri-template-syntax: Exported functions

F
Function, enable-uri-template-syntax: Exported functions
Function, read-uri-template: Exported functions
Function, uri-decode: Exported functions
Function, uri-encode: Exported functions
Function, uri-template: Exported functions
Function, uri-template-reader: Internal functions

M
Macro, maybe-uri-encode: Internal macros
Macro, uri-template-bind: Exported macros
Macro, weak-register-groups-bind: Internal macros
maybe-uri-encode: Internal macros

R
read-uri-template: Exported functions

U
uri-decode: Exported functions
uri-encode: Exported functions
uri-template: Exported functions
uri-template-bind: Exported macros
uri-template-reader: Internal functions

W
weak-register-groups-bind: Internal macros

Jump to:   E   F   M   R   U   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   S   U  
Index Entry  Section

S
Special Variable, uri-decode?: Exported special variables
Special Variable, uri-encode?: Exported special variables

U
uri-decode?: Exported special variables
uri-encode?: Exported special variables

Jump to:   S   U  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   P   S   U  
Index Entry  Section

P
Package, uri-template: The uri-template package

S
System, uri-template: The uri-template system

U
uri-template: The uri-template system
uri-template: The uri-template package

Jump to:   P   S   U