code.h(oe)kje

I've forked off ring.middleware.multipart-params into a new library called ring.middleware.upload-progress

It's a bit rough-and-ready for now, and it uses the session to store the shared state about current uploads, which is probably not the best way to go about it - I'm thinking about introducing a new lower-level mechanism for low-memory shared state based on clojure's STM tools, since this kind of thing is interesting for more than just uploads - but it does work as long as you're not doing anything too fancy (if you're worried, you can use a separate session store just for this info).

For the interested: the code is at github.

I've got some working "upload progress bar" javascript and routing code too, but it's not in this project, so for now, you'll have to roll your own.

I'll get a clojars release done as soon as I'm satisfied this stuff is usable. Probably in the next few days.

I just released a few bits of image code that might be useful to more people. clj-imajine can read, write and scale images. There's also some minimal experimental pdf support. More features will be added when I need them or if someone else sends me a good pull request.

Source code is on github. Leiningen/maven jars are on clojars.

Also, Saul Hazledine got in touch with me to merge our changes of clojure.contrib.sql and make it an official project. It's called clj-sql and differs from clojure.contrib.sql mostly in that it makes it possible to use :keywords-with-dashes as column names (for most operations, at least, so far) and that its support for auto-generated keys is much better, i.e. there is some!

Source code is on github. Leiningen/maven jars are on clojars.

By far the oldest board in this series. Production of these things started in 1985 and slightly modified versions are still being build by Unicomp (the Customizers are the closest to the standard IBM Model M, but always make sure you pick the Buckling Spring versions, see below).

Build quality

I've been using a Model M keyboard for the last couple of years, and in many respects it's the best keyboard I've ever used: it's very sturdy, will last for decades (mine is 15 years old and still working fine) and the key switches are phenomenal.

Layout

This was one of the first keyboards with what's now more or less the standard PC layout and it's probably the reason that that layout became so popular. Probably not remarkable - even boring - these days, but on the whole it's very well thought out and effective. Especially if you map the CAPS Lock key to Control (Unicomp sells models with CAPS and Left-CTRL swapped, but you can swap the keys on any OS and I don't really see the point of looking at a keyboard when you're typing on it).

Buckling Spring switch technology

The switches work via a so called "buckling spring" mechanism, which means every key is set on top of a fairly long spring that "collapses" sideways when you've pressed the key about half way down and activates the mechanical "hammer" attached to the bottom of the spring. You can easily feel when that is about to happen, and once it does you can feel the key "give" and it makes a very satisfying CLICK sound.

On this keyboard you simply can't get fooled about whether you've pressed a key or not: the auditory and tactile feedback is very immediate.

Issues

As you can probably tell, I really like this keyboard, but there a few issues with it that are annoying:

Size

This is a large keyboard, even for a full size standard layout: the MS Natural 4000 has a big wrist rest and a "split" main cluster and it's still only marginally larger than the Model M.

Size is especially important if you're a right handed mouse user. With the num-pad to the right, your mouse is quite a long way away from the main alphanumeric cluster where your hands are when you're typing, which means that you're not always using an optimal position for the mouse, the keyboard or both. You can tell these things were invented before PCs had mice.

There used to be Model M variants that didn't have a numeric key pad, but production of those stopped somewhere in the early '90s. Expect them to be expensive - if you can find one. Ebay US seems to have a few, but once you include shipping, you might want to consider something else if you live in Europe. Clickykeyboards (where that link is to) sells them for fairly reasonable prices, but they don't seem to have them all that often - and you still have to pay shipping from the US.

Finger fatigue

The switches on these keyboards are very good, but also quite heavy: they require noticeably more force than most conventional keyboards. You get used to it, especially since the force is consistent over all keys, but for me, it's just barely on the edge of "too heavy".

Sound

The click sound, while satisfying, can get on your nerves late at night. Not that much of an issue for me, but sometimes you just wish it made a bit less noise. If you have coworkers or family in the same room, I expect they won't like this keyboard much.

Pro: price

On the other hand, second hand full-size Model Ms are cheap and not that hard to get. New ones from Unicomp are also very competitively priced compared to other well-built keyboards with mechanical switches (the basic model is $69), even if you have to ship them across the Atlantic.

Previous episode: In search of a better keyboard - Early history.

Next episode: what now? (not finished, stay tuned).

When you're typing as much as I do, sooner or later you realize that having a good keyboard is important. Years ago I was having issues with wrist-pain and switching keyboards was - for me - a very effective way of almost eliminating the problem.

But this is not about health issues directly. What I found is that the best way to stay healthy while working is to keep irritation to a minumum, and keyboards can do a lot of things that are just plainly annoying:

• Keys in wierd and/or hard to reach places
• Keys in half-size
• Keys that only work most of the time
• Keys that are much harder to press than the others

Looking at that list, there are two main things that can go wrong: keyboard layout and the key switch technology. I'm going to address both throughout this short series.

I'm going to present the main keyboards I've used in chronological order (that is; order that I used them), but I'm ignoring the very early stuff. Some were not that good (Commodore 64), some were horrible (Atari 400, I'm not even sure if I'd call that thing you've got a keyboard) and some were pretty nice (like the Amiga 500). My focus is on keyboards that are still available and useful to today's PC or Mac user.

As an example of frustrating design, I present:

The MS Natural Elite

All in all it's not a bad board; they're cheap and they're fairly pleasant to type on with light-weight keys, but all the navigation keys are in half-size AND in non-standard places (and yet close enough to the standard locations to get really confusing). Get used to pressing INSERT instead of END and fumbling for the cursor keys. Bad, ugly and unnessessary. Also, in my experience, they break after 3 years or so.

The MS Natural 4000

The successor to the Elite that solved most of the issues with the layout, but the modifier keys and especially the space bar were so heavy I found myself slamming my thumbs on them which can't be good.

The extras, like the horrible multimedia "keys" and the vertical "joystick" or whatever that thing is, I won't further address, since I never used them.

Also, it broke down after only a year. Not good at all for a keyboard that cost about 60 euros at the time.

By now I was getting frustrated by key switches, and I wanted something that would actually let me type in a consistent way and KNOW that I was really pressing a key when I thought I was, without me having to slam every one of them into the ground.

Which brings me to the next post: In search of a better keyboard; The IBM Model M.

This is part of the series on SLIME functions. See the introduction for information on what SLIME is.

Just a short post today.

The slime-who-calls function (default binding "C-c C-w c") lists every function that calls the given function (default argument is the symbol under the cursor). You can press ENTER on that list to go to the listed definition. Beats using M-x rgrep for convenience, but - at least with Clojure code - it doesn't catch every call; second-order function calls aren't caught.

For those readers using Clojure, you need a pretty recent version of swank-clojure for this to work - and it seems to also list function definitions with the same name as the argument, which I think isn't correct.

New code!

As I noted in yesterday's post, slime-complete-symbol normally doesn't complete locally bound "variables" (that is, function arguments and let bindings).

I've created a SLIME extension that does a pretty rough scan of the current top-level form and adds all the matching symbols in the form into the list of suggested completions. If you want to check it out, slime-complete-locals is available on github.

A correction

Also, if you missed the update on yesterday's post, make sure you add the right forms to smart-tab-completion-functions-alist - the key in that alist should be the MAJOR mode. So using slime-mode (like I did yesterday) will not work. It must be clojure-mode or whatever the major mode for your lisp editing is.

This is part of the series on SLIME functions. See the introduction for information on what SLIME is.

Today I want to address auto-completion. There are many different Emacs extensions for doing completions, but the basic functionality in SLIME is provided by the function slime-complete-symbol, which takes the symbol under the cursor and expands it, using whatever symbols are reachable at that point in the code^1]. The way I have it set up is a bit tricky, though, so here's how it works:

I really prefer expansions to be bound to the TAB key. But the TAB key is also used to indent code. It's possible to have it "do what I mean", and the easiest method I found for that is to use Smart Tabs (see also the github repo).

Smart tab determines the expansion function to use based on the major mode of the current buffer*. So I've got the following in my configuration:

(require 'smart-tab) ;; make sure smart-tab.el is reachable in your load-path first
(global-smart-tab-mode 1) ;; switch on smart-tab everywhere

(setq smart-tab-completion-functions-alist
      '((emacs-lisp-mode . lisp-complete-symbol)
        (text-mode . dabbrev-completion) ;; this is the "default" emacs expansion function
        (clojure-mode . slime-complete-symbol))) ;; see update below

Now, whenever I press TAB and the cursor is at the end of a symbol, it gets expanded. If I press TAB on any other place, that indents that line.

There's a lot of stuff you can customize with expansions and auto completion, but this will give you the basics quickly and without too much hassle.

1] For Clojure code, at least, this boils down to; every symbol that is defined (or imported etc) in the current name space. This has two consequences:

• It only applies to code that has already been loaded into the program, so you will want to compile stuff pretty much immediately once you've written or modified it.
• It does not expand let bindings or function arguments, since those are lexically scoped and cannot be retrieved from the name space. There is probably a way to fix this, but I haven't looked into the problem that far.

* Update: the smart tab configuration must be keyed off the MAJOR mode. So slime-mode . slime-complete-symbol will not work, since slime-mode isn't a major mode. I replaced it here with clojure-mode.

This is part of the series on SLIME functions. See the introduction for information on what SLIME is.

SLIME has a bunch of different functions that compile code from a file buffer into the running Lisp process.

I'll list a few of them here, and end with why you normally want to use slime-compile-and-load-file instead of any of the other ones.

1. slime-eval-last-expression (default key-binding "C-x C-e") evaluates the expression right before point (the cursor). This is occasionally useful because it's a quick way to evaluate part of a larger expression. For instance, say I've got this code, with | indication the cursor position:

   (defn connection-middleware [handler]
     (fn [request]
       (with-db *db*|
         (handler request))))
   

   When I call slime-eval-last-expression, the message line at the bottom of my Emacs screen shows the value of the var *db*.

2. slime-compile-defun (default key binding: "C-c C-c") evaluates the current definition (from the current cursor position downwards). It doesn't have to be a function definition (at least not for clojure code); all of the common (def...) forms will work. This is useful if you made a quick update to a single definition and want to load it into the current process without loading anything else.

   In other words, given the earlier code and cursor position:

   (defn connection-middleware [handler]
     (fn [request]
       (with-db *db*|
         (handler request))))
   

   Calling slime-compile-defun will evaluate the whole connection-middleware function.

3. slime-compile-region (no default binding) evaluates whatever you've currently selected.
4. slime-compile-and-load-file (default binding: "C-c C-k") compiles and loads the whole file.

   It's the easiest method to compile stuff since you don't need to have your cursor on any particular position, but the main reason to do this instead of, say, slime-compile-defun is that this gives you much more reasonable error messages.

   When you call any of the other compile functions, any errors you get back while compiling or later will not refer to a file and line number. This makes it a lot harder to find the error in your source code (even errors in other parts of the same file may now not refer to the right lines either, if you moved or resized your definition).

   In addition, compile errors will be noted using the standard M-n and M-p key bindings for compiler errors - in this case, using the functions (slime-next-note) and (slime-previous-note) respectively. These will navigate to the given error, and display the particular error on that line the echo buffer.

To recap, unless you want to evaluate a particular value in a source file or you're working in a "scratch" buffer with all kinds of stuff in it, you generally want to compile the whole file as a unit, since it makes the most sense if anything goes wrong.

updates: Corrected the default binding of slime-compile-and-load-file. Thanks to Don Jackson for reporting the mistake.

This is part one of the series on SLIME functions. See the introduction for information on what SLIME is.

Today's function is slime-edit-definition, which has the default key binding of Meta-.

This function is one of the most useful code-navigation tools; with the point at a function call or variable, press Meta-. and Emacs switches to the definition of that variable or function. Once you've got this in your fingers you will use it a lot. And since it uses SLIME instead of etags (for example) it works reliably for any definition that was loaded from a file (I will address this in a future post) and doesn't require any additional tools or configuration.

There's a complement function; slime-pop-find-definition-stack is bound to Meta-, and takes you back to the place you were when you called slime-edit-definition.

I'm starting a series of posts highlighting useful functions in Emacs/SLIME. The idea is to take one function (or a set of related functions) per post. This post is mostly here for reference in future episodes and will explain what SLIME is and why it's interesting.

What SLIME is

If you're a Lisp programmer, chances are you've seen at least some mentions of SLIME or you're already using it. If you're not, you're probably not familiar with it at all.

Basically, SLIME is an interactive Emacs mode for Lisp programming, "interactive" meaning it interacts with a running program (also called an "image" in Lisp jargon) while you're building/modifying it. There are similar modes for other programming languages (Perl, for example has at least two) but as far as I know, the concept of real "interactive" programming seems to be mostly confined to Lisp and Smalltalk and people think you're eccentric if you use it in any other language.

Why interactive modes are cool, or: where I confuse the issue on static vs dynamic. Again.

The static status quo

You're probably familiar with grand IDEs for "static" languages such as Java and C++ (and if not, you're either a hardcore "dynamic" language nerd (good for you!) or you're reading the wrong blog). With typical static languages, the idea is that the compiler will have enough information just from the source text to check variable and argument types, function or method calls, operator application, all available classes etc without running the program. This implies that a sufficiently smart program that isn't the compiler can do the same. What that means (especially for typical Java code) is that the development system will always know the ins and outs of every function call and type you're writing and can almost instantly alert you if you're misspelling a name or using the wrong argument type for a method.

Good IDEs will also use this information to let you rename or restructure functions or classes in your project with automatic updates to all the calls, for example.

The issue with dynamics

All of the above sounds cool. And it is. It just comes at the cost (typically) of having to specify all your variable and argument types, and explicitly importing those types (and the types of each element in a container type, etc) for each source file, which usually means quite a lot of your source text is just made up of type names (classes, for Java). It must be that way, because otherwise the compiler/IDE won't know what you're talking about.

This means that for languages that play loose with typing and just allow you to assign any type to any variable, or worse, redefine whatever you like (including method signatures) while the program is running you can't have any of the goodness that is the "modern IDE".

Or is it? - The revenge of dynamic languages, or: it was there all along! - sort of

The way interactive modes resolve the problem is actually quite straight forward: instead of parsing all the source text, and then making inferences about it, you can keep the program you're modifying running and then ask it what's going on. It's a technically flawed approach, for many reasons, but ("big but" joke removed) it gets the job done most of the time, and more importantly, it lets the programmer (that's you) get on with it.

Basically, what you're doing in this kind of environment is edit one or two functions in the source text, insert the new definitions into the running program and see if it works. Rinse, repeat. While you're doing that, the editor is keeping track of all the available types and functions/methods. That means you get auto-completion, source navigation etc just like a "real IDE", but without much of the hassle.

Some pointers as to what you get and with how much hassle are going to be the topics of this series.

All kinds of Lisps

Although I've used a bunch of different Common Lisp versions in the past that work with SLIME (mostly SBCL), at the moment I'm pretty much exclusively using Clojure, which is not a Common Lisp, but a fairly new addition to the Lisp language family that you can think of as a streamlined "practical" Lisp-1 if you have to. Any source/screen dumps you see on this this topic will be Clojure code unless notes indicate otherwise.

"Meta" (Emacs jargon)

If you're running Emacs on Windows or Linux, Meta is most likely the key that's typically designated "Alt" on your keyboard. On a Mac, it depends on the Emacs build, but it's probably either [alt/option/⌥] or [command/⌘]. Mainly it's just a source of confusion, but since the Emacs documentation refers to it throughout as the "Meta" key and I want to keep the actual episodes a lot shorter than this one, I will do so too in this series.

If you're still curious, the reason it's called "Meta" is that the original Lisp machines had that key. See the glorious "Space Cadet" keyboard! Marvel at its amazing modifier keys!

Using SLIME with Clojure

http://www.assembla.com/wiki/show/clojure/Getting_Started_with_Emacs should get you started if you want to use Emacs/SLIME for the Clojure language. Note that you should install swank-clojure as well if you want to use the nice SLIME stuff discussed in this series (see the 2nd to last paragraph on that page).

If you're stubborn, don't like pre-built packages and/or have your own intricate Emacs configuration like me, figure it out yourself, maybe taking some hints from my personal config.

I don't like Emacs, but I want to have a decent editor for Clojure code

See the Clojure "Getting Started" page at assembla.

Anyway, hope you find this interesting.
Joost.