Level up: jsonic revisited

Intro­ducing contracts

To ensure safer run-time behavior of our func­tions, we’ll add contracts. A contract wraps around a func­tion and ensures its input argu­ments and return value meet require­ments that we specify. If the func­tion tries to accept argu­ments or return a value that doesn’t meet these require­ments, the contract raises an error.

Of course, we can write these kind of input & output checks by hand. But contracts have three bene­fits:

For instance, consider our-div, a divi­sion func­tion that allows 0 as a denom argu­ment. Bad input produces a generic error:

We can add a check to denom that raises a more specific error:

But we can do even better with a contract. To add a contract to our func­tion, first we import racket/contract. The define is the same as usual. But we’ll change our provide to use contract-out, which lets us attach a contract to the exported func­tion:

To make the contract itself, we use -> (also known as a contract combi­nator). Each argu­ment to -> is a func­tion that performs a test (also known as a pred­i­cate). The last argu­ment to -> tests the return value, and the other argu­ments test the input argu­ments.

For our-div, we want a contract that tests that num is a number?, denom is not zero?, and the result is also a number?. We write this contract like so (where not/c is a contract combi­nator that inverts the zero? pred­i­cate):

To make the sepa­ra­tion between input and output pred­i­cates more read­able, Rack­e­teers typi­cally use infix nota­tion in a contract. Func­tion calls are idiomat­i­cally written with prefix nota­tion. But we can option­ally surround the func­tion name with . dots . and move it anywhere within the S-expres­sion, and the func­tion call will work the same way. Infix nota­tion lets us relo­cate the -> to a more logical place:  + The dots aren’t iden­ti­fiers. They’re just extra nota­tion that the Racket reader knows how to parse.

Now we can add our contract to our provide:

This time, the input-argu­ment error is raised by the contract:

To show how the return-value contract works, let’s change our func­tion so it returns a string, and call our-div with two valid numer­ical argu­ments:

This time, the error message changes:

Instead of refer­ring to “expected” argu­ments, the error refers to the “promised” return value, and the blame is like­wise shifted to our-div itself (“broke its own contract”).

Curious char­ac­ters might be wondering why our sample code is inside a submodule, rather than at the top level of our source file. The answer is that contracts are always asso­ci­ated with some boundary within the code. A contract is invoked only when the func­tion is used across that boundary. In this case, because the contract is attached within our provide, it only applies across the module boundary of our-submod. Thus, if we move (our-div 42 0) inside our-submod:

The contract won’t be trig­gered, and we’ll get our generic error again:

Adding contracts to our language

Let’s open "reader.rkt" so we can add a contract to read-syntax:

Recall that read-syntax takes two argu­ments: a path to a file and an input port pointing at that file. The path argu­ment can be any data type, so we’ll use the universal contract any/c. We need the port to be of the type port?. At the end, read-syntax returns a syntax object (which we can test with syntax?). So the whole contract looks like this:

As before, we import racket/contract, and change our provide to use contract-out with our new contract:

Now, if we run our test file:

It still works normally:

Which is what we expected. But this is a special situ­a­tion. We already knew that the func­tion was correct.

Most of the time—espe­cially while we’re devel­oping our language—we don’t. So aside from ensuring run-time safety, a contract can be a useful devel­op­ment tool. It lets us plant a flag when we start to write a func­tion. As soon as we get off track, it lets us know. (The other half of this equa­tion is unit testing, which we’ll cover in the next section.)

To that end, it’s wise to write the narrowest possible contracts. That way, there’s less chance of “false posi­tives”—values that meet the contract tests, but that aren’t actu­ally accept­able.

For instance, the port? pred­i­cate returns #t for both input ports and output ports. But the port argu­ment to read-syntax can only be an input port. There­fore, we should use the narrower input-port? pred­i­cate in our contract:

Let’s now open "tokenizer.rkt", so we can add a contract to make-tokenizer:

Like read-syntax, make-tokenizer takes one input port as an argu­ment. As we learned, we can test this with input-port?.

But how about next-token, the return value? next-token is a func­tion. We could use the generic procedure? pred­i­cate, which returns #t for all func­tions.

That’s not wrong. But we can do better.

If we need a contract to test a func­tion, we can make a second contract with -> and nest it inside the main contract. In this case, next-token takes no argu­ments, and returns either eof (which we can test with eof-object?) or a token struc­ture (token-struct?). For simplicity, we encap­su­late these tests in a new jsonic-token? pred­i­cate:

Thus, our contract for next-token looks like this (since we don’t have any input argu­ments, we don’t need infix nota­tion):

And our whole contract for make-tokenizer looks like this:

Putting it all together, we again start by importing racket/contract. We add our defi­n­i­tion for jsonic-token?. And we insert the new contract inside the provide for make-tokenizer using contract-out:

Contract caveats

A con­tract oper­ates at run time. So it nec­es­sar­ily imposes a per­for­mance cost on a program, however small. When we use a contract, we should make sure that the incre­mental safety is worth the incre­mental cost.

For instance, a contract on read-syntax is prob­ably unnec­es­sary. The argu­ments are being passed in by Racket itself. We can trust that they’re correct.

On the other hand, a contract on read-syntax is only called once for every program (because read-syntax itself is only called once). So it’s unlikely to gum up the works, either.

Beyond run-time safety, the best reason to use contracts is that they’re a great debug­ging tool. Those who value their time will likely find that their invest­ment in contracts is quickly repaid by rapidly pinpointing bugs related to incor­rect data types.

We’ll include contracts in the new func­tions we add during this tuto­rial.