Closing the loop: basic

Having figured out imports, let’s go the other direc­tion and add exports to BASIC. (Again, not some­thing that was ever part of the orig­inal language. Don’t panic.)

How could this work? Let’s suppose we have a BASIC program that defines vari­ables and func­tions (temporarily using basic-demo-3 as the language, just to see how it works):

The result of this program:

Now let’s suppose we want to make the func­tion div and the vari­able x avail­able to other programs. To do this, we add two export state­ments (to the end of the program, but as with import, the loca­tion shouldn’t matter):

This program will still run the same way:

But now, if we import this "sample-exporter.rkt" module into another Racket program using require, we can use div as a func­tion and x as a value:

Let’s also notice what’s not happening when we import "sample-exporter.rkt": though the BASIC program inside is running, its print state­ments don’t produce any results on the REPL.

Means of suppres­sion

To make exports work, we have two tasks:

For the first task, we can run the same play we used for imports. We’ll use the parser to mark our exported names with new parser rule—let’s call it b-export-name. We’ll splice this rule so that the export names end up carrying a syntax prop­erty called 'b-export-name. We’ll use this syntax prop­erty to find the names in our parse tree. Then we can put them inside a provide form at the top level of our module. We’ll also need to convert the b-export state­ment itself into a (void) form.

The second task—suppressing the output of the program—presents a new kind of problem. How do we change the behavior of print state­ments in certain condi­tions?

Let’s zoom out so we can see the bigger picture. Our task is a partic­ular version of a more general problem: how to change the behavior of a module when it’s run directly vs. when it’s imported into another module.

We first encoun­tered this problem in wires. In that case, we needed to set up the language so that it printed certain results after the wire func­tions were defined. To do this, we used the main submodule, a special submodule that Racket only invokes when the module is run directly, but not when it’s imported.

Sounds promising. Can a main submodule help us here? Not quite. The limi­ta­tion of a main submodule is that it’s only invoked after the rest of the module has run. In wires, that worked fine, because we wanted to print some results after certain func­tions were defined in the body of the module.

In BASIC, however, the print state­ments can be mixed anywhere among the func­tion and vari­able defi­n­i­tions in the source. There’s no way for us to rearrange the order of state­ments without changing the way the program works.

Suppose we had the idea to collect the result of every print state­ment into a buffer list of strings, and then use a main submodule to display that list at the end of the program. Not a bad plan, until we try to run this program:

In this case, the main submodule would never run, because the rest of the program never termi­nates. So there would be no output at all. That’s wrong.

Intro­ducing the configure-runtime submodule

What we’re looking for is a submodule that, like the main submodule, only runs when its enclosing module is run directly, and not when it’s imported. But unlike main, we want this submodule to be invoked before the rest of the module, so we can set up print to work a different way.

Fortu­nately, this option exists: it’s called the configure-runtime submodule.

To avoid confu­sion, let’s concede that configure-runtime is a misleading name. Throughout Racket, the term “run time” refers to the main phase of module eval­u­a­tion. So no matter whether a module is imported, or run directly, it always has a run-time eval­u­a­tion phase.

Contrary to this termi­nology, the configure-runtime submodule is only invoked when its enclosing module is run directly. Really, it would’ve been better named configure. But—we’ll live with it.

To use the configure-runtime submodule, we simply add it to the top level of our language module. In our case it’ll look like this:

Although the submodule can do the setup tasks itself, usually it loads another module (like basic/setup) and invokes a setup func­tion (like do-setup!). There’s no magic to the names of the setup module or func­tion. What matters is the configure-runtime name on the submodule.

The configure-runtime submodule has to use a full module decla­ra­tion rather than module+. Why? Because module+ assumes that the surrounding module has been invoked, and builds atop it. Since the configure-runtime submodule runs before the other code, it needs a full module decla­ra­tion so it can run inde­pen­dently.

With that back­ground, let’s get into the code.

Lexer updates

Very simple—we just add our new export keyword to the list of reserved-terms:

Parser updates

We add a new b-export rule to handle the export state­ment, and add b-export to the right side of the b-statement rule.

We also mark the export state­ment argu­ment with a spliced b-export-name rule. In the parse tree, this will be attached to the argu­ment as a syntax prop­erty:

As we did in the b-func rule for func­tions, we’re delib­er­ately using an ID in our b-export-name pattern rather than a b-id. Why? Because other­wise, an export state­ment would trigger the default defi­n­i­tion of an iden­ti­fier. In that case, a program like this wouldn’t raise an error:

Here, the vari­able x would be created with the default value of 0, and that would be the exported value.

Instead, we’d like to mimic the behavior of a Racket program that tries to provide an unde­fined iden­ti­fier:

By using ID in the rule pattern rather than b-id, we can make this happen.

Intro­ducing para­me­ters

Let’s stub out our new "setup.rkt" module that will be invoked from our configure-runtime submodule:

Before we can proceed, we’ll have to get more precise about how to suppress our print state­ments when the module is run directly.

We know that every print state­ment expands into a call to displayln. (See "basic/misc.rkt".) In turn, displayln sends its output to the current-output-port, which is a Racket para­meter that holds a refer­ence to the port where things get printed.  + To use a Unix analogy, current-output-port is like stdout. In fact, current-output-port often points to stdout.

Para­me­ters are a special class of items in Racket that approx­i­mate the role of global vari­ables. They’re used spar­ingly, usually for system-wide settings that would other­wise be diffi­cult to reach.

Unlike global vari­ables, para­me­ters are func­tions. To read the value of a para­meter, we invoke it as a func­tion. To set the value, we pass the new value as an argu­ment.

For example, the error-print-width para­meter controls the maximum width of an error message:

As shown above, we can set para­me­ters imper­a­tively, by passing a value as an argu­ment. But para­me­ters also coop­erate with parameterize, a let-like form that lets us temporarily set a para­meter to a certain value during the eval­u­a­tion of the parameterize body:

parameterize has two bene­fits. First, it remem­bers the orig­inal value of the para­meter, and resets the para­meter to that value after parameterize exits. Second, the effect of the new para­meter value is bounded: it only affects expres­sions invoked, directly or indi­rectly, during the body of the parameterize.

Let’s see an example using displayln. We create ostr, an output port that captures output to a string. Then we use parameterize to temporarily use it as the current-output-port, and call func:

The func within the parameterize has no visible output, because the output of displayln is being redi­rected to ostr. In other words, parameterize affects displayln, even though it’s called from inside func. But after the parameterize, we can call func and it will display text normally. We can also retrieve the stored contents of ostr.

With that in mind, we’ll invert our approach. Rather than suppressing print state­ments only when the module is imported, we’ll suppress all print state­ments by default. When the module is run directly, we’ll use the configure-runtime submodule to make them visible. How?

That gives us enough guid­ance to finish our "setup.rkt" module:

We define basic-output-port as a new para­meter using make-parameter. To make an output port that discards its output, we use open-output-nowhere.

In do-setup!, we imper­a­tively set basic-output-port to be the same as current-output-port.

Expander updates

The key updates are in "expander.rkt". At the top, we import our new "setup.rkt" module so we can use the basic-output-port para­meter. We also extract the EXPORT-NAME syntax objects the same way we did in imports—by calling find-property, this time with the 'b-export-name key:

At the top of our #%module-begin syntax template, we add the configure-runtime submodule that we saw earlier. All it does is import basic/setup and call do-setup!.  + We can’t use a rela­tive path like "setup.rkt" inside the submodule. Why not? Because this submodule will be eval­u­ated within a source file that lives else­where in the filesystem. So we need a full module path.

Below that, we also add a provide form that contains our new list of EXPORT-NAME ... items.

At the bottom of the #%module-begin syntax template, we wrap our main program loop in parameterize, setting the current-output-port to our new basic-output-port para­meter.

Finally, as we did for b-import, we need to convert b-export nodes into (void) expres­sions. So we update "misc.rkt":

Testing our exports

Now we can test our orig­inal "sample-exporter.rkt" module:

If we did every­thing right, when we run this program directly, it will display its output normally:

What a relief. We should also be able to import the module. This time, we expect the 1 2 3 output will be suppressed, and we’ll only see the output from "sample-importer.rkt":

Very nice. Let’s also check that trying to export an unde­fined iden­ti­fier gives us the error we were hoping for:

Though we had to take a slightly scenic route, our exports work the way we hoped.

Fortu­nately, every­thing we learned about the configure-runtime will be useful in the next section, where we repro­gram the REPL.