Introducing Clem: The Clojure Error Mediator!

[donyorm]

This has been quite a bit of time in the making but I’ve finally got an open-source project I’ve been working on to a demoable stage, so I humbly present to you the Clojure Error Mediator.

Tl;dr: Clem is a project to help make errors easier to understand for new users, and we’d love community help in testing the project (see our gitlab and website).

So what is this thing?

Clem is a tool that integrates with users’ REPLs and helps provide more understandable error messages for new users. Probably most of you know that Clojure’s error messages are…unhelpful at times (how many beginners know that forgetting a quote on a list causes a ClassCastException?). This tool aims to bridge that gap for new users so that they can more quickly an easily get a foothold on the language.

This is accomplished using a REPL plugin/wrapper which reaches out to Clem’s server to get information on the exception, if it exists. This information is automatically printed in the user’s REPL, or if Clem doesn’t have a helpful message for that error, it prints Clojure’s normal message.

How does it work

Clem overrides the exception-caught function of a repl and gathers some information about the exception which it sends to its server. Based on the stack-trace, message, type, and phase of the exception, Clem matches it to existing exceptions and returns a message which it then displays to the user. Everything is written in Clojure(Script) including the website!

Community Involvement

As mentioned above, this project is essentially in a demo state, mainly because there simply aren’t a lot of errors stored on the project at the moment. It needs users to both use the repl interface in order to “prime” the server and also to add helpful messages to the server (and help finding elusive bugs would also be appreciated). I’d love to have the community test out the project by installing the repl integration and add messages to the website. Of course, this is an open source project, so code contributions are always welcome.

Why not use X project instead?

Obviously, Clem is not the only solution to this problem, nor even the only good solution. But we haven’t found another project that targets new users and requires a minimum of installation for the new users. I’ve seen some progress on getting better messages in clojure.core, but that’s a bit of a slow process and we figured we may as well work on something to help in the meantime (and there may be a place for less formal language in something like Clem).

But also, Clem has been in the works for about 2 years now, so X may not have existed when we started. We’re definitely hoping to serve the community and want to collaborate in whatever way is most helpful!

[didibus]

Hey this is awesome, and if I understand correctly it tries to group similar errors and count how often a user had it happen?

Just that will be a great way to guide the core team on if there are specific errors they could improve which would have most impact.

But the idea too that people can then add a better error message from it is great as well.

Nice job.

My only worry now is information leak, if I use this, my errors are posted to this public website correct? So I better be sure I’m using this only on things that don’t need security or privacy.

[donyorm]

Yes it does count the errors, and it would be great if that were a useful tool for the core team!

But yes this does post some information about your exception, so on privacy or security conscious projects that would be a problem. I’ll add a task to allow users to turn off saving the information to our database/posting it publicly, hopefully we can get to that at some point too.

[Stuart_Halloway]

Bravo! Needless to say I think this is a very cool idea.

It is possible to call the server with an error directly, instead of setting up REPL intercept? I would want to opt into this on a per-exception basis.

[PEZ]

This is a fantastic initiative!

@Stuart_Halloway

It is possible to call the server with an error directly, instead of setting up REPL intercept? I would want to opt into this on a per-exception basis.

I’d like this as well. I want to add this to Calva. Today when I evaluate something that causes an exception, say (/ 1 0), the error is printed in the output window, together with a code lens button that offers to print the stack trace.

If I squint I can see one more button there, saying something like Mediate Error.

[donyorm]

@PEZ @Stuart_Halloway You should be able to call the clem-repl-caught function directly however you’d like. The one arity option that just takes an exception probably does what you want. It does prompt for configuration, but I imagine you could just have Calva set that up before hand (config is documented in the ReadMe). I don’t have calling that function directly documented, but let me know if you end up using any features there and I’ll try to treat them as public API.

I will say that this is very much alpha still, especially since the error matching is a bit finicky, but hopeful some more usage will help me fine-tune it.

[Phill]

The most fertile space for contribution will be tardy errors that stem from typical, but not illegal, missteps. A great test case will be

Don't know how to create ISeq from: clojure.core$xxx$fn__xxxx

(Or, am I the only one who falls into that trap?)

[daemianmack]

Very nice!

Consider adding to the README (and this thread?) a screenshot or some other visual representation of Clem in action.

[donyorm]

@Phill, yep! That’s the exact error I’ve been thinking of as I wrote this. So common, yet the message is fairly cryptic.

And thanks for the suggestion @daemianmack, added some to the README (though it unfortunately looks like I can no longer edit the parent post of this thread)