Pitance: Template and Snippet Infrastructure

Published on September 13, 2009. beepbeep (6), pitance (3)

The last several months I have been working on an exciting project: Pitance. Pitance stands for Project Infrastructure and Templates Are Now Convenient for Everyone, and is an infrastructure for sharing and managing project templates and snippets. This infrastructure consists of a website, an HTTP/JSON API, and a command line utility.

The project lives at pitance.lethain.com, and is available at your convenience.

Pitance Quick Start

It's meant to be as simple as possible to get started with Pitance. There is undoubtedly some work to be done in that regard, but hopefully it will improve quickly.

First, head over to the website and find a template you're interested in by either searching or browsing. For this example, lets say you're interested in the erlang_couchdb_app template.

Then you can download the template using cURL:

curl http://pitance.lethain.com/api/template/erlang_couchdb_app/ > erlang_couchdb_app.erl

You can grab a specific version of the app as well:

curl http://pitance.lethain.com/api/template/erlang_couchdb_app/1/ > erlang_couchdb_app.erl

Alternatively, you can use the command-line client, which simplifies things slightly. First you'll need to download the must recent version of the client using:

curl http://pitance.lethain.com/download/command-line/ > pitance.py

Then make it executable:

chmod +x pitance.py

Now you can grab templates like:

./pitance.py template erlang_couchdb_app > erlang_couchdb_app.erl
# specific version
./pitance.py template erlang_couchdb_app 1 > erlang_couchdb_app.erl

If you have simplejson installed (or have a version of Python with the json library) then you use pitance.py to create and update templates as well:
```
echo "print 'This is my template'" > test_template.py
./pitance create python_test_template \
    --language python \ 
    --tags "test, useless" \
    --related_templates "erlang_test, ruby_test" \
    --author_email lethain@example.com # this is hidden from users, only visible to admin \
    --author "Will Larson" \
    --desc "This is a test for a Python template. Please ignore this." \
    < test_template.py
```
That is to say, you add the template itself via standard input, and must specify the parameters language, author_email, author and desc. You may optionally specific the parameters tags and related_templates, which take a comma-separated list.
Once you have created a template, you can update it in a similar fashion, with the important caveat that you must load a template with each update, but all other parameters are optional. This is actually a limitation in the command line client rather than the API, which I will hopefully fix soon (basically, it just stalls out waiting for standard input...).
```
./pitance.py update python_test_template --tags "test2, test3" < test_template.py
```
Each update creates a new version of the template, but the previous versions are still available by explicit reference. This makes it possible for multiple individuals to contribute wiki-style to templates, while still making it possible to ensure you get the templates you prefer.

Future Development

I have a great quantity of ideas of how to improve Pitance, and will keep implementing them piece by piece, depending from feedback and if this service seems to be useful to more individuals than just myself.

In no particular order, some of the ideas are:

Tweet updates and creation of templates.
Create variables within templates, to make it easier to customize (although, consistent naming and search & replace accomplishes this already).
The ability to declare template dependencies, to facilitate building multi-file project templates out of several templates (this could be built as a third-party system as well, on top of the existing apis).
Command-line client could use some work.
The some parts of the web-client and searches should make a distinction between projects and versions of projects (i.e. you search for erlang and get responses of erlang_couchdb_app - 1 and erlang_couchdb_app -2. That's kind of silly).
Syntax highlighting for the web pages (sadly, doing the implementation in Erlang has divided me from my longtime love Pygments).

Implementation Stack

The stack is described on the About page, and really deserves a post of its own, but succinctly it is built on BeepBeep, CouchDB and Lucene, facilitated by couchdb-lucene and erlang_couchdb. This is a wonderful stack to work with.