uri-match

  1. uri-match
    1. Description
    2. Author
    3. Requirements
    4. Upgrade Notice
    5. Documentation
      1. Routes Format
      2. make-routes
      3. uri-match
      4. make-uri-matcher

Description

A URI path (or route) matching library which provides means for flexible and RESTful route definition.

Author

Moritz Heidkamp

Requirements

Requires the uri-common egg.

Upgrade Notice

Since version 0.5, handler procedures are applied with an additional first argument. See uri-match for an explanation.

Documentation

Routes Format

Route defintions must adhere to the following grammar:

   <routes>           ::= ((<path>  [<action> | <routes>] ...) ...)
   <path>             ::= (/ <fragment-matcher> ...)
   <fragment-matcher> ::= {{regexp}} | {{sre}}
   <action>           ::= (<method> <body>)
   <method>           ::= GET | POST | PUT | DELETE | OPTIONS | HEAD
   <body>             ::= {{atom}} | {{handler-procedure}}

make-routes

[procedure] (make-routes routes #!optional (path ""))

Accepts routes list in the format described under Routes Format and returns them in a format which can be passed to uri-match.

The optional path is mainly used internally but may be given as a global path prefix.

Example:

(make-routes '(((/ "") (GET "this!")
		((/ "bar") (GET "and this!")
		 (POST "also this")))))

uri-match

[procedure] (uri-match method uri routes)

Matches a given HTTP method (which should be given as an upper-case symbol to comply with intarweb) and the uri's path (which must either be an uri-reference with an uri-path or a string representing a path) in routes (which must be a list of the format returned by make-routes) and returns a thunk which, when invoked, returns the body of the first matching route, #f otherwise. If the body is a procedure, it is applied to the possibly found capture groups of the matching route. Additionally, the first argument passed to that procedure is procedure which can be called to continue the matching process (see make-uri-matcher for an example use).

Example:

((uri-match 'GET "/foo/42"
	    (make-routes `(((/ "foo" "(\\d+)")
			    (GET ,(lambda (c n) (format "You got foo number ~A" n))))))))

=> "You got foo number 42"

make-uri-matcher

[procedure] (make-uri-matcher routes)

Accepts a routes list in the format described under Routes Format and returns a procedure of two arguments (method and uri like uri-match) for matching against it.

Example:

(use uri-common)

(define match (make-uri-matcher `(((/ "") (GET "this is the root path!")
				   ((/ "some")
				    ((/ "nested") (GET "I'm nested!")
				     ((/ (submatch (+ num)))
				      (POST ,(lambda (continue n)
					       (if (< (string->number n) 10) 
						   "what a humble number!"
						   (continue)))))
					      
				     ((/ "route" (submatch (+ any)) (submatch (+ any)))
				      (GET ,(lambda (continue x y)
					      (format "I am the ~A and ~A!" x y)))))
				    
				    ((/ (submatch (+ any)) (submatch (+ any)))
				     (POST ,(lambda (continue x y)
					      (format "You've requested ~A" y)))))))))

((match 'GET "/"))
=> "this is the root path!"

((match 'GET (uri-reference "http://localhost/some/nested/route/alpha/omega")))
=> "I am the alpha and omega!"

((match 'POST "/some/nested/2"))
=> "what a humble number!"

((match 'POST "/some/nested/12"))
=> "You've requested 12"