Imagine a language: wires

Booting the reader

When we invoke #lang wires, Racket will look for a "main.rkt" module within our wires direc­tory. Within that module, it will expect to find a reader submodule that provides our read-syntax func­tion.

Converting the source file to datums

Because we’re building our language in one module, we’ll put the defi­n­i­tion of read-syntax inside our reader submodule, rather than import it from else­where with require:

The guts of our read-syntax func­tion will be similar to the one we made for stacker. There, we pulled each line from the source file and converted it into a paren­the­sized S-expres­sion, also known as a datum, that looked like (handle ···).

This time, we’ll wrap each line with (wire ···). Then, in the expander, we’ll add a wire macro that expands this form.

Since the logic of read-syntax will be roughly the same as before, let’s take this oppor­tu­nity to learn some neater nota­tion:

The first part of read-syntax will create our list of wire-datums. We make this list with for/list, which loops over its iter­a­tors and eval­u­ates the body each time. Whereas plain for discards the results of these eval­u­a­tions, for/list collects them into a list.  + For more about these and other iter­a­tion expres­sions, see loops.

We iterate over the lines in our input port using in-lines, assigning each line to wire-str, which holds a string of code from the source file. Then we use format-datum to convert this string into a (wire ···) datum. The resulting list of datums is assigned to wire-datums.

Making module code

Once we have our wire-datums from our source file, we need to insert them into code repre­senting a module expres­sion. Recall that the code for our module expres­sion needs to be pack­aged as a syntax object without any bind­ings.

In stacker, we accom­plished this by making a datum using quasi­quote nota­tion and then using datum->syntax to convert it into a syntax object.

This time, we’ll use quasi­syntax nota­tion to do both at the same time. Quasi­syntax works the same way as quasi­quote, but each oper­ator is prefixed with #, and the result of each oper­ator is a syntax object rather than a simple datum:

Simi­larly, if our module code would’ve looked like this as a raw quasi­quoted datum:

We can convert it to quasi­syntax like so:

Which gives us the syntax object we need.

Well, almost. When we use #` (or the ordi­nary #' prefix) to make a syntax object, the lexical context—meaning, the currently avail­able bind­ings—of the surrounding code will auto­mat­i­cally be attached to the new syntax object. Usually, this is what we want: part of Racket’s policy of hygiene is that syntax objects should retain the lexical context from the loca­tion where they were created.

In this case, however, it’s not what we want. Why? Because read-syntax has a special respon­si­bility to return a syntax object without bind­ings. So as the last step, we’ll pass our syntax object to strip-bindings, which removes them.

Our updated read-syntax:

Testing our reader

When we’re working on Racket code in DrRacket, it’s conve­nient to be able to try out quick exam­ples and tests on the REPL. Let’s try testing our read-syntax now, using the test-reader func­tion included in br.

If we use the sample wire code "123 AND g -> ac", we expect to get (wire 123 AND g -> ac), wrapped in a module expres­sion. Let’s see what actu­ally happens:

Whoops—that’s wrong. But the problem is not a defect in our code. Rather, the problem is that our new read-syntax is stashed inside a submodule, where it’s invis­ible to the REPL. So right now, when we say read-syntax on the REPL, we’re actu­ally invoking the read-syntax that’s part of br/quicklang.

How can we get the read-syntax we want? One way is to explic­itly require our submodule on the REPL:

This time, we’ll get the right result:

This works. But it’s cumber­some.

There is a better way: rather than declaring our reader submodule with module, we’ll use module+. As its name suggests, rather than create a fully inde­pen­dent submodule, module+ makes a submodule that picks up all the defi­n­i­tions in the surrounding module. To the outside world, the reader submodule will work the same way.

But inside our module, we can move our read-syntax outside the reader submodule, so it can be avail­able on the REPL. We update the code like so:

Like module, a submodule declared with module+ has a submodule name. But unlike module, it doesn’t have a module path for its initial imports. That’s because it doesn’t need one—it’s already getting its initial imports from the surrounding module.

This time, when we use test-reader on the REPL:

We’ll get the right result, because our new read-syntax is visible to the REPL:

Our reader is complete. BTW, though we could’ve gotten by without using module+, it has a couple other useful features that we’ll rely on as we write the expander.