Moustache

h1. Moustache

<pre> (app ["hi"] {:get "Hello World!"}) </pre>

Moustache is a micro web framework/internal DSL to wire Ring handlers and middlewares.

h2. How micro is it?

Well, there's only one macro you need to know: @app@.

Every other public var is public only because @app@ needs it in its expansion.

h2. Syntax

See "syntax.html":http://moustache.cgrand.net/syntax.html

h2. Walkthrough

http://gist.github.com/109955

h2. The @app@ macro

A @(app ...)@ form returns a Ring application (handler).

There's currently four usages of @app@:

• to wrap a Ring handler,
• to define routes,
• to dispatch on HTTP methods
• and to render plain text.

h3. Wrapping an existing Ring handler

<pre> (app my-handler) ; identity, returns my-handler </pre>

You can simply wrap a handler into middlewares:

<pre> (app middleware1 (middleware2 arg) my-handler) ; equivalent to (-> my-handler (middleware2 arg) middleware1) ; ie (middleware1 (middleware2 my-handler arg)) </pre>

Note that every usage of @app@ supports middleware-wrapping.

h3. Routes

h4. Basics

With Moustache you don't write routes as encoded uri (eg @"/Thank%20you%20Mario/But%20our%20princess%20is%20in%20another%20castle"@), you write vectors of decoded segments (eg @["Thank you Mario" "But our princess is in another castle"]@).

<pre> (app ["foo"] my-handler) ; will route requests to "/foo" to my-handler (app ["foo" ""] my-handler) ; will route requests to "/foo/" to my-handler (app ["foo" "bar"] my-handler) ; will route requests to "/foo/bar" to my-handler (app ["foo" &] my-handler) ; will route requests to "/foo", "/foo/", "/foo/bar" and "/foo/bar/baz/" to my-handler (and will chop "/foo" off from the uri) (app ["foo" name] my-handler) ; will route requests to "/foo/", "/foo/bar" to my-handler and bind @name@ (a local) to the matched segment (eg "" or "bar") (app ["foo" x & xs] my-handler) ; "/foo/bar/baz/bloom" will bind x to bar and xs to ["baz" "bloom"] </pre>

You can catch all URIs with the route <code>[&]</code>. If you don't provide a handler for <code>[&]</code> and there's no handler for a request Moustache sends a 404 (not found) response.

h4. Route validation/destructuring

<pre> (defn integer [s] "returns nil if s does not represent an integer (try (Integer/parseInt s) (catch Exception e))) (app ["order" [id integer]] my-handler) ; for "/order/134" @id@ will be bind to 134 (not "134"), this route will not match "/order/abc". (app ["agenda" [[_ year month day] #"(\d{4})-(\d{2})-(\d{2})"]] {:get [month "-" day "-" year " agenda"]}) </pre>

h4. Fall through

The routes are tried in order until one route matches the request uri and the associated handler does not return nil.

That's why:

<pre> (app ["foo" &] (app ["bar"] handler1) ["foo" "baz"] handler2) </pre>

returns a 404 for /foo/baz: the nested @app@ form returns a 404 for /baz and this 404 bubbles up.

You can prevent such behavior by writing:

<pre> (app ["foo" &] (app ["bar"] handler1 [&] pass) ["foo" "baz"] handler2) </pre>

h3. Method dispatch

<pre> (app :get handler-for-get :post handler-for-post) </pre>

You can add a catch-all using the :any keyword.

If you don't specify a handler for :any, Moustache sends a 405 response (method not allowed).

h3. Shorthands

When the right-hand form of a route or of a method dispatch is a @(app ...)@ form, you can write the form as a vector: <code>(app ["foo" &] (app ["bar"] handler))</code> can be shortened to <code>(app ["foo" &] [["bar"] handler])</code>.

Besides when the right-hand form is a method dispatch without middlewares you can write the form as a map: <code>(app ["foo"] (app :get handler))</code> can be shortened to <code>(app ["foo"] {:get handler})</code>.