Importing & exporting

Bind­ings can be defined in one module and shared with another. The defining module is exporting bind­ings; the other module is importing them. In prac­tice, an importing or exporting module is usually a self-contained source file. But every­thing here applies equally to submod­ules, which can share bind­ings the same way.

It’s conven­tional to think about importing & exporting in terms of bind­ings rather than vari­ables. Why? Because a vari­able = an iden­ti­fier + a binding. While it’s often true that a binding travels with its orig­inal iden­ti­fier, it’s not manda­tory—as we will see below, the iden­ti­fier can be altered along the way (though the binding will not be).

Exporting

By default, all bind­ings defined in a module are private to that module. To make a binding avail­able to other modules, use provide:

Though provide can be used anywhere within a module, Rack­e­teers often consol­i­date them at the top, to summa­rize the public inter­face of the module:

To export every binding newly defined within a module, use the short­hand all-defined-out:

Any bind­ings avail­able in the module can be exported, not just those that are defined there. For instance, bind­ings that are already avail­able through the current #lang can also be exported:

These bind­ings, however, are not included in all-defined-out. To export bind­ings that have been imported from a certain module, list them indi­vid­u­ally, or use all-from-out to export all of them:

To make the external name of a binding different from its internal name, use provide with rename-out:

A prac­tical use of rename-out is to chain together #%module-begin macros in a language. In this example from bf, the iden­ti­fier #%module-begin is used twice: within the module it refers to the #%module-begin macro from br/quicklang; outside the module, it will refer to bf-module-begin:

Importing

Every module gets its initial set of bind­ings from its expander. In a module expres­sion, the expander is desig­nated explic­itly. In a source file, the #lang line spec­i­fies a reader, which converts the source file into a module expres­sion with an expander desig­na­tion (see the #lang line for more about this conver­sion):

Beyond that, bind­ings can be imported from other modules with require:

Bind­ings can be imported from submod­ules by using submod, which uses a path-like spec­i­fi­ca­tion:

Phases

The eval­u­a­tion of a module occurs in a series of sepa­rate phases. Conse­quently, each phase gets its own sepa­rate round of importing & exporting. Bind­ings that are imported during a certain phase are not auto­mat­i­cally visible in other phases.

Though the behavior is sensible, it can lead to seem­ingly myste­rious errors—espe­cially when writing macros, which natu­rally straddle phase 1 (where the macro is compiled) and phase 0 (where the macro is run).

For instance, this macro returns code that relies on nand, a func­tion imported from racket/bool:

This works because an ordi­nary require, as seen here, imports bind­ings at phase 0. The macro refers to nand within the syntax object it returns. Though the macro is compiled during phase 1, its syntax object isn’t eval­u­ated until phase 0. So this refer­ence to nand works.

This macro, however, fails with a nand: undefined error:

This time, the macro also tries to use nand outside the syntax object. This refer­ence to nand will be eval­u­ated during phase 1, when the macro is compiled. But racket/bool isn’t avail­able in phase 1—only phase 0. Hence the error.

This problem can be cured with for-syntax, which explic­itly imports a module at phase 1, where it can be visible to macros:

And just to come full circle: if the phase-0 require for racket/bool is removed, the nand inside the macro (at phase 1) will still print, but back in phase 0, an unbound-iden­ti­fier error will arise:

Further