Thank you for your comment

Beau­tiful Racket / tuto­rials

Follow the grammar: bf

If you opted for Quick Setup at the outset, you can go no further. This next part relies on Racket’s command-line tools. You’ll need to complete the Full Setup to continue.

Pack­aging our language

Now that we have a taste for bf program­ming, we might want to use our inter­preter more freely. The #lang reader "reader.rkt" boot­strap­ping only works for source files that are stored in the same direc­tory. What a drag. We’d rather be able to invoke our language within a source file anywhere as #lang bf.

To do this, we need to install our code as a package. A package is Racket’s basic unit of instal­lable soft­ware. The #lang nota­tion at the top of a source file coop­er­ates with the package system: when we write #lang name, Racket tries to find name among our installed pack­ages. (Conversely, until we install our language as a package, we have to keep using the #lang reader path form.)

Here’s how we install our project as package:

  1. We create a direc­tory for our package. For now, the name of the direc­tory needs to match what we use in the #lang name form. Since we want to invoke our inter­preter as #lang bf, we’ll call our package direc­tory bf.  + It’s possible to make the package name and the #lang name different. We’ll see how to do this in a later tuto­rial. Create this direc­tory some­where conve­nient. 

  2. We move our three modules—"parser.rkt", "reader.rkt", and "expander.rkt"—into this new bf direc­tory.

  3. When we invoke #lang bf, Racket will look for a "main.rkt" module in the bf direc­tory. In that module, it will expect to find a reader submodule that provides our read-syntax func­tion. If we wanted, we could put our actual read-syntax code there. But it’s just as easy to just use require and provide within the reader submodule:

    main.rkt
    #lang br/quicklang
    (module reader br
      (require "reader.rkt")
      (provide read-syntax)) 
    1
2
3
4
    #lang br/quicklang
(module reader br
  (require "reader.rkt")
  (provide read-syntax))
    copy to clipboard

    We also need to adjust our read-syntax func­tion in "reader.rkt". The module code returned by this func­tion refers to "expander.rkt". This is a rela­tive path string, which won’t be valid once we start making bf source files in other direc­to­ries. Instead, we refer­ence the expander using its new package name, bf/expander (as a module path, it loses its .rkt exten­sion):

    reader.rkt
    #lang br/quicklang
    (require "parser.rkt")

    (define (read-syntax path port)
      (define parse-tree (parse path (make-tokenizer port)))
      (define module-datum `(module bf-mod bf/expander
                              ,parse-tree))
      (datum->syntax #f module-datum))
    (provide read-syntax)

    (require brag/support)
    (define (make-tokenizer port)
      (define (next-token)
        (define bf-lexer
          (lexer
           [(char-set "><-.,+[]") lexeme]
           [any-char (next-token)]))
        (bf-lexer port))
      next-token) 
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
    #lang br/quicklang
(require "parser.rkt")

(define (read-syntax path port)
  (define parse-tree (parse path (make-tokenizer port)))
  (define module-datum `(module bf-mod bf/expander
                          ,parse-tree))
  (datum->syntax #f module-datum))
(provide read-syntax)

(require brag/support)
(define (make-tokenizer port)
  (define (next-token)
    (define bf-lexer
      (lexer
       [(char-set "><-.,+[]") lexeme]
       [any-char (next-token)]))
    (bf-lexer port))  
  next-token)
    copy to clipboard

    By the way, we could change the other module refer­ences in our code to use this new package nota­tion. For instance, in "reader.rkt" we could require bf/parser rather than "parser.rkt". But it’s unnec­es­sary, because those files will remain in the same direc­tory, so they can use local path strings.

  4. Finally, we use Racket’s command-line program raco to install our package. In a terminal window, we’ll move into our new bf direc­tory and do raco pkg install:

    cd path/to/bf
    raco pkg install
    1
2
    > cd path/to/bf
> raco pkg install
    copy to clipboard

    This will trigger a flurry of status messages as Racket updates our instal­la­tion.

  5. If there are no errors, we can go back to DrRacket and test that our package works by writing a #lang bf program:

    #lang bf
    Greatest language ever!
    ++++++++[>++++++++<-]>.
    1
2
3
    #lang bf
Greatest language ever!
++++++++[>++++++++<-]>.
    copy to clipboard
    @
    1
    @
    copy to clipboard

  6. If we ever want to delete the package, we can do

    raco pkg remove bf
    1
    > raco pkg remove bf
    copy to clipboard

  7. If we want to rename the package, we can delete it, rename the direc­tory, update the name of the expander in read-syntax, and then rein­stall it using the proce­dure above.

We waited until the end of our bf project to install it as a package. Could we have done this at the begin­ning? Sure. Once we install a language project as a package, we can still work on the modules inside. These changes are reflected imme­di­ately when we invoke the language, without needing to run raco pkg install again. And we can use the #lang name nota­tion. Thus, the bene­fits of creating a package outweigh the extra house­keeping.

We’ve only scratched the surface of pack­ages. In a later tuto­rial, we’ll see how we can add docu­men­ta­tion and tests to a Racket package, and distribute it to others using Racket’s online package server.

← prev next →