The Implementation of HDB, the _hyperscript debugger
Deniz Akşimşek —
Update : HDB has evolved since this post was written. Though it works mostly the same way, there have been fixes and a UI redesign. Check the _hyperscript repo for the up-to-date code.
The 0.0.6 release of the _hyperscript hypertext UI scripting language introduces HDB, an interactive debugging environment. In this article I discuss how the hyper-flexible hyperscript runtime allowed me to implement the first release of HDB with ease. But first, I will introduce you to what HDB is like:
The (Un)finished Product
breakpoint statement stops execution and launches the HDB UI.
You can set breakpoints conditionally:
Turning the keys
In the hyperscript runtime, (The runtime is an example of a tree walking interpreter.) each command has an
execute() method which either returns the next command to be executed, or a
Promise thereof. The execute method for the breakpoint command creates an HDB environment and assigns it to the global scope (usually
HDB object keeps hold of the current command and context as we step through. (The context is the object holding the local variables for the hyperscript code, and some other things the runtime keeps track of). We call its
There are a few things to unpack here. We call
self.ui() to start the UI, which we’ll get to later. Remember how a command can return the next method to execute as a promise? The break method resolves after the internal event bus receives a
"continue" event, whether by the user pressing “Continue” or simply reaching the end of the debugged code.
The “context switch” is the dirtiest part of it all. Because we can step out of functions, we might finish debugging session with a different context than before. In this case, we just wipe the old context and copy the current context variables over. Honestly, I thought I’d have to do a lot more of this kind of thing.
Speaking of stepping out of functions…
Stepping Over and Out
Firstly, if self.cmd is null, then the previous command was the last one, so we just stop the debug process:
If not, then we do a little dance to execute the current command and get the next one:
We perform a useless check that I forgot to take out (
self.cmd &&). Then, we special-case the
breakpoint command itself and don’t execute it (nested debug sessions don’t end well…), instead finding the subsequent command ourselves with the
runtime.findNext() in hyperscript core. Otherwise, we can execute the current command.
Once we have our command result, we can step onto it:
If we returned from a function, we step out of it (discussed below). Otherwise, if the command returned a Promise, we await the next command, set
cmd to it, notify the event bus and log it with some fancy styles. If the result was synchronous and is a HALT; we stop debugging (as I write this, I’m realizing I should’ve called
continueExec() here). Finally, we commit the kind of code duplication hyperscript is meant to help you avoid, to handle a synchronous result.
To step out, we first get our hands on the context from which we were called:
Turns out _hyperscript function calls already keep hold of the caller context (
callingCommand was added by me though). After we change context, we do something a little odd:
Why do we call
findNext twice? Consider the following hyperscript code:
transition 'color' to darkgray
set name to getName()
log the name
We can’t execute the command to set
name until we have the name, so when
getName() is called, the current command is still set to the
transition. We call
findNext once to find the
set, and again to find the
Finally, we’re done stepping out:
What did I use to make the UI for the hyperscript debugger? Hyperscript, of course!
There are a lot of elements listening to
load or step from hdb.bus, so I consolidated them under
update from .hdb.
#hyperscript-hdb-ui-wrapper- is the element whose Shadow DOM this UI lives in — using shadow DOM to isolate the styling of the panel cost me later on, as you’ll see.
We define some functions.
Now, I wasn’t aware that we had template literals in hyperscript at this point, so that’s for the next release. The
escapeHTML helper might disappoint some:
Unfortunately, hyperscript’s regex syntax isn’t decided yet.
And we have the most broken part of HDB, the prettyPrint function. If you know how to do this better, feel free to send a PR.
Having defined our functions we have a simple toolbar and then the eval panel:
Why do I use weird selectors like
<input/> in me when these elements have good IDs? Because
#eval-expr in hyperscript uses
document.querySelector, which doesn’t reach Shadow DOM.
A panel to show the code being debugged:
Finally, a context panel that shows the local variables.
That loop could definitely be cleaner. You can see the hidden feature where you can click a variable name to log it to the console (useful if you don’t want to rely on my super-buggy pretty printer).
Some CSS later, we’re done with the UI! To avoid CSS interference from the host page, we create a wrapper and put our UI in its shadow DOM:
In just 360 lines, we have a basic debugger. This speaks volumes to the flexibility of the hyperscript runtime, and I hope HDB serves as an example of what’s possible with the hyperscript extension API. Like the rest of hyperscript, it’s in early stages of development — feedback and contributors are always welcome!