((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/uri-match" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.") (tags "egg")) (section 2 "uri-match" (toc) (section 3 "Description" (p "A URI path (or route) matching library which provides means for flexible and RESTful route definition.")) (section 3 "Author" (p (int-link "Moritz Heidkamp"))) (section 3 "Requirements" (p "Requires the " (int-link "uri-common") " egg.")) (section 3 "Upgrade Notice" (p "Since version 0.5, handler procedures are applied with an additional first argument. See " (tt "uri-match") " for an explanation.")) (section 3 "Documentation" (section 4 "Routes Format" (p "Route defintions must adhere to the following grammar:") (pre "   <routes>           ::= ((<path>  [<action> | <routes>] ...) ...)\n   <path>             ::= (/ <fragment-matcher> ...)\n   <fragment-matcher> ::= {{regexp}} | {{sre}}\n   <action>           ::= (<method> <body>)\n   <method>           ::= GET | POST | PUT | DELETE | OPTIONS | HEAD\n   <body>             ::= {{atom}} | {{handler-procedure}}")) (section 4 "make-routes" (def (sig (procedure "(make-routes routes #!optional (path \"\"))" (id make-routes))) (p "Accepts " (tt "routes") " list in the format described under " (int-link "#routes-format" "Routes Format") " and returns them in a format which can be passed to " (tt "uri-match") ".") (p "The optional " (tt "path") " is mainly used internally but may be given as a global path prefix.") (p "Example:") (highlight scheme "(make-routes '(((/ \"\") (GET \"this!\")\n\t\t((/ \"bar\") (GET \"and this!\")\n\t\t (POST \"also this\")))))"))) (section 4 "uri-match" (def (sig (procedure "(uri-match method uri routes)" (id uri-match))) (p "Matches a given HTTP " (tt "method") " (which should be given as an upper-case symbol to comply with intarweb) and the " (tt "uri") "'s path (which must either be an " (tt "uri-reference") " with an " (tt "uri-path") " or a string representing a path) in " (tt "routes") " (which must be a list of the format returned by " (tt "make-routes") ") and returns a thunk which, when invoked, returns the body of the first matching route, " (tt "#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 " (tt "make-uri-matcher") " for an example use).") (p "Example:") (highlight scheme "((uri-match 'GET \"/foo/42\"\n\t    (make-routes `(((/ \"foo\" \"(\\\\d+)\")\n\t\t\t    (GET ,(lambda (c n) (format \"You got foo number ~A\" n))))))))\n\n=> \"You got foo number 42\""))) (section 4 "make-uri-matcher" (def (sig (procedure "(make-uri-matcher routes)" (id make-uri-matcher))) (p "Accepts a " (tt "routes") " list in the format described under " (int-link "#routes-format" "Routes Format") " and returns a procedure of two arguments (" (tt "method") " and " (tt "uri") " like " (tt "uri-match") ") for matching against it.") (p "Example:") (highlight scheme "(use uri-common)\n\n(define match (make-uri-matcher `(((/ \"\") (GET \"this is the root path!\")\n\t\t\t\t   ((/ \"some\")\n\t\t\t\t    ((/ \"nested\") (GET \"I'm nested!\")\n\t\t\t\t     ((/ (submatch (+ num)))\n\t\t\t\t      (POST ,(lambda (continue n)\n\t\t\t\t\t       (if (< (string->number n) 10) \n\t\t\t\t\t\t   \"what a humble number!\"\n\t\t\t\t\t\t   (continue)))))\n\t\t\t\t\t      \n\t\t\t\t     ((/ \"route\" (submatch (+ any)) (submatch (+ any)))\n\t\t\t\t      (GET ,(lambda (continue x y)\n\t\t\t\t\t      (format \"I am the ~A and ~A!\" x y)))))\n\t\t\t\t    \n\t\t\t\t    ((/ (submatch (+ any)) (submatch (+ any)))\n\t\t\t\t     (POST ,(lambda (continue x y)\n\t\t\t\t\t      (format \"You've requested ~A\" y)))))))))\n\n((match 'GET \"/\"))\n=> \"this is the root path!\"\n\n((match 'GET (uri-reference \"http://localhost/some/nested/route/alpha/omega\")))\n=> \"I am the alpha and omega!\"\n\n((match 'POST \"/some/nested/2\"))\n=> \"what a humble number!\"\n\n((match 'POST \"/some/nested/12\"))\n=> \"You've requested 12\""))))))