Level up: jsonic revis­ited

Now we’ll write an indenter, a func­tion that’s used to auto­mat­i­cally indent source code in DrRacket. Like syntax coloring, writing an indenter is optional.

When we made our get-info func­tion for jsonic, we included a hook for the indenter with the key drracket:indentation. At the time, we hypoth­e­sized a new "jsonic/indenter.rkt" module that would provide an indent-jsonic func­tion. We’ll start that module now, importing br/indent for some helper func­tions we’ll need shortly, and racket/contract too:

Writing a contract

How does our indenting func­tion work? When DrRacket needs to indent some code, it will call our func­tion with a tbox and a posn:

DrRacket expects our indenter to return either an exact-nonnegative-integer? with the total number of spaces to indent the line, or #f if DrRacket should apply its usual S-expres­sion inden­ta­tion rules. In this case, we’ll calcu­late the indent for every line, and never return #f. So our contract for that value is simply exact-nonnegative-integer?.

With this infor­ma­tion, we can write a contract for our indenter. We import racket/contract to get our contract combi­na­tors. Because tbox is an instance of text%, we can test it with the contract combi­nator is-a?/c, if we also import text% from racket/gui/base. The other pred­i­cates for the contract follow from the descrip­tions above:

The twist, however, is that our contract has one manda­tory argu­ment, and one optional argu­ment. So instead of the -> contract combi­nator, we’ll use the ->* variant, which supports optional argu­ments. We just need to move our manda­tory and optional argu­ments into their own paren­the­sized groups, like so:

Then we can move the finished contract into our provide expres­sion using contract-out:

The indenting rules

Our indenter will have four rules:

So if we start with a plain chunk of source like this:

It will be indented like so:

Imple­menting the rules

First let’s estab­lish an indent-width of 2, and set up left-bracket? and right-bracket? as pred­i­cates to use within the body of the main func­tion:

Our indenter is going to operate on a new data type: the char­acter. A Racket char­acter is a numer­ical type repre­senting a Unicode value. Char­ac­ters are the raw ingre­di­ents of any string. A char­acter is written with a #\ prefix. Char­ac­ters can be faster than the equiv­a­lent one-char­acter strings, so certain Racket func­tions use char­ac­ters. For our pred­i­cates, we use member to check whether a char­acter c appears in a list of possi­bil­i­ties.  + Those who have studied Racket’s equality func­tions might know that char­ac­ters can be compared with eqv? rather than the slower equal?. So in this case, we could use memv, which relies on eqv?, rather than member, which uses equal?.

Moving to the inside of indent-jsonic. We can see from the rules that the infor­ma­tion we need to indent a line comes from the current line and the previous line. So we start our indenter by getting those line numbers with the helper func­tions previous-line and line. (These helper func­tions are all imported from br/indent.)

To finish our func­tion, we compute the indent for the current line. Let’s insert the code, then step through each part:

Within the branches of our cond expres­sion, we imple­ment our indenting rules:

Testing our indenter

As usual, we want to make sure our func­tion works before we move on. As we’ve done before, we’ll set up a test submodule to hold our unit tests. (We’ll only make one. More would be wiser.) We’ll use our sample case as the basis of the test:

Once again, we use the #<<HERE ··· HERE delim­iters to create a here string, a conve­nience for using a string as a literal value without having to escape the double-quote marks within. We can paste what­ever we want between the here-string delim­iters and it will be assigned to test-str as a value.

In the last line, we use the testing helper apply-indenter, which takes as argu­ments our indent-jsonic func­tion and our test-str. If we now run "jsonic/indenter.rkt", our test will run and we’ll see the result:

It’s a little hard to see what’s going on. If we change our test to display the result:

The indenting will become obvious:

If we compare this to our intended result, we can confirm that our indenter does what we hoped. But if this is going to become a unit test, we need to find a way to quan­tify the inden­ta­tion of this string so we can verify it auto­mat­i­cally with check-equal?, not with our eyes.

Here’s how we do that:

Instead of display, we’ll pass the result string to string-indents (another helper func­tion from the helpful br/indent) which will list the number of spaces at the begin­ning of each line. We can easily compare this to our expected list of inte­gers repre­senting indents.

By the way, where did we get this list of indents? One way is to use string-indents on the REPL with our indented string, and then paste the resulting list of values into our unit test.

Again, in the real world we’d want to write more unit tests with a wider variety of input strings. But for now, we’ll say that indent-jsonic is complete.

One last bit of house­keeping

To use our indenter in DrRacket, we have to connect it to our get-info func­tion in "main.rkt". We do that by uncom­menting the branch we previ­ously commented out:

Then, as we did in syntax coloring, we have to force a refresh of get-info. If we’re using Racket v6.9 or later, we select Racket → Reload #lang Exten­sions, which reloads our get-info func­tion and our new colorer. If not, we quit and restart DrRacket, which has the same effect. Then we can apply indenting to a jsonic source file by typing ctrl-i (Linux & Windows) or cmd-i (Mac OS).

Indenting caveat

In this example, indenting is a cosmetic conve­nience. Every­thing we’ve done here presumes that white­space is not seman­ti­cally mean­ingful, and thus we can freely indent lines without changing the program result. This is true for jsonic and many other languages.

But not always. Python, for instance, depends on white space to describe the struc­ture of the program. In those cases, an indenter would need to be less casual and more conser­v­a­tive, to ensure that the act of indenting doesn’t change the meaning of the program.