Editing page: uri-match - The CHICKEN Scheme wiki

You can edit this page using wiki syntax for markup.

Article contents:

[[tags: egg]]

== uri-match

[[toc:]]

=== Description

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

=== Author

[[Moritz Heidkamp]]

=== Repository

This egg is hosted on the CHICKEN Subversion repository:

[[https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/uri-match|https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/uri-match]]

If you want to check out the source code repository of this egg and
you are not familiar with Subversion, see [[/egg-svn-checkout|this page]].

=== 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 ""))</procedure>

Accepts {{routes}} list in the format described under
[[#routes-format|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:

<enscript highlight=scheme>
(make-routes '(((/ "") (GET "this!")
		((/ "bar") (GET "and this!")
		 (POST "also this")))))
</enscript>

==== uri-match

<procedure>(uri-match method uri routes)</procedure>

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:

<enscript highlight=scheme>
((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"
</enscript>

==== make-uri-matcher

<procedure>(make-uri-matcher routes)</procedure>

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

Example:

<enscript highlight=scheme>
(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"
</enscript>

Description of your changes:

I would like to authenticate

Authentication

Username:Password:

Spam control

What do you get when you add 2 to 12?