README

1 Introduction

This is incremental eval a handy utility for watching your code evaluate in many Lisps! That’s the plan anyway but at the moment I’ve only implemented very limited support for Emacs Lisp.

What is incremental evaluation? It’s exactly what it says on the box: eval things step by step. Lisp evaluation is quite simple, unless you encounter conditional branching, a macro or a special form you can simply keep going forwards down lists until you can’t anymore, then go backwards up list, grab the symbolic expression which follows the point and evaluate it. You can replace the symbolic expression you just evaluated with the result you just got. If you keep doing this (and handle special forms etc. with their special rules) then you’ll eventually evaluate the whole expression.

This package allows you to watch this left to right bottom to top evaluation happening! Simply invoke incremental-eval with the point either:

• inside an symbolic expression
• after an symbolic expression
• with a region highlighting an symbolic expression

It’ll pick up the relevant region to operate on and make it read-only. Then you can hit n, p or q to evaluate the next symbolic expression, go backwards in the history of evaluations or quit, restoring the original state.

With a universal argument the evaluation will start from the fully evaluated form. You can then hit p to go backwards and watch it all happen in reverse.

2 Planned Features

If you have ideas for new features, then feel free to update this README and make a pull request.

2.1 TODO Incremental Eval of Functions

The idea here is to ask for values for each of the parameters for a function from users and then evaluate the body of the function incrementally with the parameters bound to the supplied values. This would allow you to quickly see how your functions work without needing to update them whatever REPL/environment you’re working with.

I think that something like replacing the function with a let form should work, but it relies on the implementation of let support being incremental.

2.2 DONE Start From the Bottom

• CLOSING NOTE [2017-06-18 Sun 10:18]
  Also added with this feature is the “done” property on Incremental Eval overlays. This is used to determine when evaluation is complete and stop the engine from going further.

With a universal argument it should start from the fully evaluated form and work it’s way backwards.

2.3 DONE Timed Playback

• CLOSING NOTE [2017-06-18 Sun 10:41]
  Added with run-at-time and stops running when done. It remembers the current overlay so that it can move to it if the user was silly and clicked somewhere else while it was executing. As a result you can’t have more than one going at a time (could have one per buffer with some more work) and it’s not thread safe.

The idea here is to basically keep going forward with a delay between each evaluation.

3 Missing Stuff

3.0.1 TODO Detect Macros (Emacs Lisp)

Determining whether a form is a macro is not implemented for Emacs Lisp

3.0.2 TODO Detect Conditionals (Emacs Lisp)

Determining whether a form is a conditional is not implemented for Emacs Lisp

3.0.3 TODO Handle Lexical Environments

Handle lexical environments so that evaluation of forms within let is correct.

3.0.4 TODO Handle Conditionals

Handle conditional evaluation so that the form is substituted with the correct branch where relevant.

3.0.5 TODO Support Other Lisps

Support for other lisps is missing (feel free to add it!) :) I’d like to have support for at least Clojure and Common Lisp before submitting this to ELPA

4 Known Issues

• [X] history does not work (i.e. hitting p will currently cause an error or do nothing)
• [X] when the form is evaluated to it’s simplest form, the overlay occupies a region of zero size and can’t be “quitted” without first undoing to make it longer first