More Contributing (2009-04-12)

[James Reeves]

Hi folks,

The last contributing thread worked quite well, so here's another.
These are tasks I've planned to do, but if anyone wants to have a go
at some of them before I get around to it I'd be glad to have some
help.

Like last time, the tasks are arranged in order of increasing
difficulty. If you feel like having a go at one of these, please post
a reply so that two people aren't working on the same thing at once.
And if you happen to think up any features that Compojure should
support, please feel free to make feature suggestions as well.

1. Create a content-type function that adds 'Content-Type' header.
Should be in the compojure.http.helpers namespace. Refer to the
redirect-to function and the set-cookies function for inspiration.

2. The following functions in compojure.http.request should be changed
so that they don't recalculate the parameters (or cookies) if they
already exist as keys in the request map:
* get-query-params
* get-form-params
* get-multipart-params
* get-cookies

3. The compojure.http.response/update-response function should set a
content-type of "text/html" when passed a string, unless a content-
type has already been set.

4. form-to is currently a macro, but it could be a function if we
altered the syntax from:

(form-to [POST "/login"] ...)

To:

(form-to [:post "/login"] ...)

This would be a minor breaking change, but it's probably not a good
idea to overuse macros when a function can provide similar syntax.

5. Write a function similar to clojure.core/memoize for caching
function output, but the ability to expire . It should have an option
to limit the amount of stored outputs to a supplied maximum, and
expire cached outputs after a supplied expiry limit.

6. Write code to generate HTML API documentation for Compojure that
looks something like the following:

<ul class="namespaces">
<li><a href="[namespace]">[namespace]</a></li>
<ul>
<li><a href="[function1]">[function1]</a></li>
<li><a href="[function2]">[function2]</a></li>
</li>
<li>...</li>
</ul>

<a name="[namespace]"/>
<h2>[namespace]<h2>
<div class="function">
<h3>[function1]</h3>
<pre class="usage">([function1] [arg1] [arg2] ...)</pre>
<div class="doc">[doc-string]</div>
<pre class="src">[source-code]</div>
</div>

<h3>[function2]</h3>
...

You might be able to adapt an existing library for generating API
documentation. Basically I'm aiming for something very simple and
straightforward which we can apply whatever CSS or JS we want
afterward, but has no inherent style built in. The clojure.contrib.gen-
html-doc is interesting, but I'm not a fan of the inline javascript or
CSS.

7. Split out the part of compojure.http.routes/routes that merges
routes together into its own function, routes*. This means you can
combine routes together with routes* without automatically getting
sessions, cookies and parameters.

8. Write a session storage type for :file in compojure.http.session.
Use the definition for :memory sessions as an example.

- James

[Brian Carper]

I tried your number 6: http://briancarper.net/clojure/compojure-doc.clj

Example output (uses a minimalist stylesheet just so I could read it):
http://briancarper.net/clojure/compojure-doc.html

It should be easy enough to alter and style however you want. A few
notes...

a. The compojure.ns-utils/immigrate function wreaks havoc with
clojure.contrib.repl-utils/get-source (it becomes unable to find any
source for anything), so I skip the files which call it.

b. I think my script may have messed up on a few vars due to name
conflicts. Someone clever could possibly figure out how to sandbox
each lib to avoid these conflicts. The name conflicts were:

compojure.str-utils/blank? and compojure.validation/blank?
compojure.http.servlet/update-response and compojure.http.response/
update-response
compojure.server.grizzly and compojure.server.jetty (lots of stuff, as
you'd imagine)

c. compojure/validation/predicates doesn't define the namespace
compojure.validation.predicates, which causes some confusion in the
script, but I think it catches the vars in there anyways.

d. I ran this with the Compojure source tree on the CLASSPATH. A jar
didn't work so well.

Maybe you can turn that into something useful.

--Brian

[James Reeves]

On Apr 13, 8:57 am, Brian Carper <briancar...@gmail.com> wrote:
> I tried your number 6:http://briancarper.net/clojure/compojure-doc.clj
>
> Example output (uses a minimalist stylesheet just so I could read it):http://briancarper.net/clojure/compojure-doc.html
>
> It should be easy enough to alter and style however you want.  A few
> notes...

I've downloaded compojure-doc and I've been playing around with it.
Some very good work! Thanks a lot for writing it.

> a. The compojure.ns-utils/immigrate function wreaks havoc with
> clojure.contrib.repl-utils/get-source (it becomes unable to find any
> source for anything), so I skip the files which call it.

That's sensible. I don't think the API should cover those namespaces,
as they're just shortcuts.

> b. I think my script may have messed up on a few vars due to name
> conflicts.  Someone clever could possibly figure out how to sandbox
> each lib to avoid these conflicts.  The name conflicts were:

You use 'use' then 'require' if 'use' fails. Why not just use
'require' from the start? That should solve any namespace problems,
and it seemed to work okay when I tried it.

> compojure.str-utils/blank? and compojure.validation/blank?
> compojure.http.servlet/update-response and compojure.http.response/
> update-response
> compojure.server.grizzly and compojure.server.jetty (lots of stuff, as
> you'd imagine)

Aside from the compojure.server namespaces, the update-response and
blank? conflicts are interesting. I'll have to rename one of the
update-response functions, and I'll probably remove
compojure.validation/blank?.

> c. compojure/validation/predicates doesn't define the namespace
> compojure.validation.predicates, which causes some confusion in the
> script, but I think it catches the vars in there anyways.

I need to revisit compojure.validation some time in the near future
and tidy it up a little.

> d. I ran this with the Compojure source tree on the CLASSPATH.  A jar
> didn't work so well.
>
> Maybe you can turn that into something useful.

It looks just what I need. By next weekend, I should have a
rudimentary website for Compojure up. The API docs are probably the
most important thing to get in place. After they're up, I'll start
writing some tutorials and explanation of Compojure's design.

Again, thanks for writing this.

- James

[Sean Devlin]

Check out the following thread in the Clojure group. It's about
adding an HTML generation utility to contrib:

http://groups.google.com/group/clojure/browse_thread/thread/eed3ae0fad5eab79

This might be work worth standardizing on.

[Brian Carper]

On Apr 13, 3:51 pm, James Reeves <weavejes...@googlemail.com> wrote:
>
> You use 'use' then 'require' if 'use' fails. Why not just use
> 'require' from the start? That should solve any namespace problems,
> and it seemed to work okay when I tried it.

If require works that'd be ideal. It wasn't working for me, but may
have been due to something screwy in my environment.

>
> It looks just what I need. By next weekend, I should have a
> rudimentary website for Compojure up. The API docs are probably the
> most important thing to get in place. After they're up, I'll start
> writing some tutorials and explanation of Compojure's design.
>
> Again, thanks for writing this.
>
> - James

Great, looking forward to seeing the site. I've been trying to do a
bit of cheerleading for Compojure on my site and elsewhere, it'll be
nice to have a URL to point to other than github.