Announcing delim-kill.el

A few weeks ago, I had the chance to attend a few courses on Perl and one on giving technical presentations, held by Perl guru and uber-geek Damien Conway. They were fantastic—just like the ones last year—so I should really write a post of its own about them. Strongly recommended.

But for now, this is about one particular thing he said about editing: you need to have a shortcut in your editor that cuts or copies the text between two given characters around cursor, or point in Emacs lingo. This lets you do many frequent editing tasks easily. Say you’re going through a source file and want to move {}-delimited blocks around, or copy the field you’re on in a CSV file, or the current section in a Markdown file (from # to the next #, roughly).

Damian showed this off in Vim. I knew right away that I wanted it in Emacs. There are of course specialized functions for doing things with certain groups of delimiters, such as the ubiquitous sexp-based functions in Emacs, described extensively on the EmacsWiki. But these rely on pre-configured groups of delimiters, and to kill the text, you have to do one extra operation. I liked the idea of having a single function, and thus key binding, to do all of it. And most importantly, it seemed an interesting challenge for my still-developing Emacs and Lisp skills, so I didn’t even do a lot of research before I dug right in and wrote delim-kill.el.

delim-kill.el contains a single convenience function for editing structured data: delim-kill. Given two characters FROM and TO, delim-kill kills the text between the first occurrence of FROM before point and the first occurrence of TO after point. FROM and TO may be identical.

If FROM and TO are not identical, the function preserves the balance between the two characters: For each FROM that is encountered while looking for TO, one additional TO is required; and vice versa. For example, in “{ foo X{bar} baz }”, with X being point and “{” and “}” as delimiters, the text “{ foo {bar} baz }” will be killed, not “{ foo {bar}”.

I had fun writing this. It turned out to be a bit harder than I expected, mainly due to all the corner cases like point being on one of the delimiters—like most programming, really. I wrote plenty of unit tests to be sure to handle these cases. It’s very little code now, but when I first had a working version, it was twice as big. Once I had it working, I could see lots of symmetry between the different cases that I could extract into shared code.

Also, I finally learned the condition-case error handling of Emacs. And being able to pass functions as arguments is just great, coming from my mostly-Java day job.

Try it out if it sounds useful to you, and let me know what you think.

Slightly edited 2010-05-16.

A simple Markdown journal in Emacs

I wanted to get into daily journaling since a long time. Keeping a journal makes it easy to find and go back to all kinds of things you have encountered and thus saves time. But more important is, I believe, that journaling structures your thoughts, like any kind of writing. You need to think clearly about something before you can write it down. Then, the act of writing it down anchors it more deeply in your memory.

Alas, all my previous attempts at journaling failed. Whatever the reason, whether on paper or on the computer, I never felt entirely at home with the solutions I tried. So what’s a hacker to do – write his own solution.

I know that there are already many ways to write a journal in Emacs. Well, here’s another one: simple-journal. It’s tiny and simple, it produces a Markdown format that I love, and having it written myself I feel more inclined to actually use it.

The journal looks like this:

### 2010-01-10

- **18:15** - "XML serializations should be hidden away from
  human view lest small children accidentally see them and become
  frightened." - from the paper *Representing disjunction and
  quantifiers in RDF*, McDermottDou02.pdf.

### 2010-01-17

- **14:45** - Set up a minimal Wicket application with Netbeans (a
  first for me, version 6.8) and Jetty. I want to try out working
  asynchronously with JSON using Wicket. Here are the steps to get the
  application running, serving up an empty page:

  - Start a plain Java SE project in Netbeans.
  - ... 

Being in Markdown, it’s very readable, and can readily be converted to well-formatted HTML. The format is completely hard-coded in the code for the moment. The goal was just to quickly get something simple and small working. Nevertheless, I’m always happy about feedback and ideas.

There’s one item on the TODO list that I’d really like to have, but I’m wondering about how to implement it a somewhat simple and efficient way: showing all entries that have “TODO” in them, or that start with “TODO”. Do I have to go through the buffer to collect them and show them in a temporary buffer? That would be a bit more programming than I feel is appropriate for such a task, and the temp buffer wouldn’t be in sync with the journal. Planet Emacs, ideas? ;-)

Announcing wpmail.el

Hi Planet Emacsen, and thanks Edward!

It was only in June this year that I started to write Emacs Lisp. The first extension I wrote is wpmail.el, which I published on github but didn’t announce as I wasn’t quite happy with it. Since then, I hacked some more on it and it’s in a better shape now, so here’s the obligatory blog post.

From the file header:

An Emacs extension to make posting by e-mail to the wordpress.com blog hosting service http://www.wordpress.com easier. It might work with other wordpress installations, which I have not tried. For more information about posting to wordpress by e-mail see the support page http://support.wordpress.com/post-by-email/.

Documentation is a bit lacking, but here’s the gist: start a new post, possibly from the region or the buffer, with wpmail-new-post or wpmail-new-post-here. Send it with wpmail-send-post when you are done. wpmail will prompt for title and category; it will propose some titles that you can see via M-n, and it auto-completes the categories in wpmail-categories. See the documentation of these functions for details.

You can write your posts in Markdown format http://daringfireball.net/projects/markdown/ if you have markdown-mode http://jblevins.org/projects/markdown-mode/ installed. Set wpmail-markdown-command to your Markdown converter and posts will be converted to HTML when sending them.

I have the feeling that the documentation could be clearer. This is probably due to the fact that while I was writing wpmail.el, my ideas about the best way of using it changed.

Initially, I made it so that the very start of a blog post would be calling wpmail-new-post. It would visit a new file in wpmail-posts-dir and you’d start writing. This requires wpmail to be in charge. Then I realized that it could be less intrusive and added wpmail-new-post-here. It simply turns your current buffer into a blog post by adding a title and the wordpress shortcode directives like “status draft”. Otherwise, it’s up to you what to do with the buffer.

It works pretty well for me now, so I’m not gonna change it around again for myself anytime soon. I’d be happy about suggestions, though!

In the latest version, I also managed to get around two wordpress bugs. One was that <pre><code>, Markdown’s default markup for verbatim blocks, was being garbled. WordPress.com’s support was very helpful and the problem is now fixed. The other is that I remove single line breaks before sending, because while wordpress mostly ignores them (as you should in HTML), it seems to turn some into <br/>.

I hope it’s useful for someone. Let me know if that’s the case!

Announcing md-readme

You can find quite a few Emacs libraries on github these days. I only have one very small project there, wpmail, which I haven’t written about yet because I want to finish the Markdown support first… anyway: something I find really neat on github is the automatic display of the README file in the repository’s root directory, if it exists. Only, as we all know, writing READMEs is tedious and we’d rather spend our time programming. But wait: in the Emacs world, we’re actually writing a README for each project: the library headers. Their content and structure are rather clearly defined, and it’s expected for all Emacs libraries. So I had the idea of generating a nice, Markdown-formatted README.md for github from these headers.

I just pushed the first version of md-readme that does just that. The README that you see on the github page is auto-generated from md-readme.el, with lists, code-block and everything.

The conversion to Markdown is of course pretty simple, but even so it’s pretty cool to see how little code I had to write. Emacs provides everything out of the box. (with-temp-file "README.md" (do-it)) is just elegant.

Now, seeing that we have code that generates a nice README from our Lisp file, it’s natural to have it run automatically so we always have an up-to-date README. Here I was struggling for a while. I had lots of ideas, but none seemed to work out. My current solution is setting a per-directory local variable for each of your ELisp projects that triggers the conversion via an after-save-hook. Code is in the README. The problem with adding the after-save-hook to all modes is that it’s evaluated all the time, for each save. Kinda annoying, even if it’s just a single condition.

Does anyone have a better idea? Do it outside Emacs in a git pre-commit hook?

But even with the current solution it works, and that’s the important part. Please try it, and enjoy your new READMEs.

Testing Wicket ListViews using IVisitor

The standard solution for unit testing Wicket apps is WicketTester. It works fine, but doesn’t offer much for testing ListViews. The assertListView method lets you test the contents of the ListView, but not the UI.

You can always extract the ListView rows into a Panel, of course. But when you don’t want to do that for whatever reason, it’s simple to side-step WicketTester and do the necessary tests yourself, especially since rows that are not in a panel of their own should be pretty simple.

An approach that works well for me is visiting the ListItems using MarkupContainer.visitChildren() and then accessing their components via Component.get(). To focus on the essential part, I’m using a method listView() in my example that gets the ListView from the rendered page. Once we have it, we visit its items.

listView().visitChildren(ListItem.class, new IVisitor<ListItem>()
{
	public Object component(ListItem item)
	{
		Component uri = item.get("uri");
		assertNotNull(uri);
		assertTrue(uri.getClass().isAssignableFrom(ExternalLink.class));
		
		// etc.
		
		// If testing one row is enough, we can stop here.
		return IVisitor.STOP_TRAVERSAL;
	}
});

Once you see it, it’s trivial. WicketTester’s assertComponent() isn’t magic, you can do the same in three lines: get the Component via its path, assert it’s actually present, and assert it’s the right type.

If you want to do further tests on the component’s internals, I find it practical to expose those through package-scoped methods, provided your tests are in the same package than your app.

Finally, something that bit me once: how ListItems work with the list model. Say we have this (just a rough sketch):

class Foo
{
	List bars;
	List<Bar> getBars() { return bars; }
}

// On some page, the model is a CompoundPropertyModel&lt;Foo&gt;.
add(new ListView<Bar>("bars")
{
	protected void populateItem(final ListItem<Bar> item)
	{
		item.add(new WebMarkupContainer("id"));
	}
});

If you get hold of the WebMarkupContainer(“id”), for instance using an IVisitor like I showed above, and you call getDefaultModelObject() on it, what do you get? One might expect a Bar; after all, it’s a ListView<Bar>. Not so – you get a Foo.

ListViews work on the original List instead of a copy. Each ListItem is backed by a ListItemModel, which knows the index of the element it represents, but has no model itself. When the model is looked up, the normal Wicket model chaining happens, so we get to the CompoundPropertyModel. The ListView code of course knows about this and uses the ListItemModel’s index to get the right Bar from the list. But getDefaultModelObject() doesn’t know about this and simply returns the Foo.

If you are in that situation, explicitly ask for the ListItemModel:

((ListItemModel) component.getDefaultModel()).getObject()

should give you a Bar. Of course, if you visit the ListItem itself like in the example above instead of a nested component, you can just call getObject() on it and it does the right thing.