chickadee » uri-match

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

uri-match

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

make-routes routes #!optional (path )procedure

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

uri-match method uri routesprocedure

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

make-uri-matcher routesprocedure

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"

Contents »