Thank you for your comment

Beau­tiful Racket / tuto­rials

Into the rapids: more basic

Before we add more features to the language, let’s improve our error handling, using what we learned about errors and excep­tions in the first basic tuto­rial.

Every BASIC program consists of numbered lines. So every run-time error arises from a partic­ular line in the program. We’d like to make it easy to report errors in terms of a specific line:

error in line 20: line 6000 not found
error in line 60: next without for
error in line 70: return without gosub
error in line 20: line 6000 not found
error in line 60: next without for
error in line 70: return without gosub
copy to clipboard

Designing better line errors

The func­tions that imple­ment the state­ments in a line are respon­sible for raising a given error (e.g., "next without for"). The wrinkle is that they don’t know anything about what line they’re being called from (e.g., "in line 60"). So the chal­lenge is bringing these two parts together to make one error message.

Where can we get the line number? Our b-line macro has access to NUM, a syntax-pattern vari­able that holds the line number:

basic/line.rkt
#lang br
(require "struct.rkt")
(provide b-line)

(define-macro (b-line NUM STATEMENT ...)
  (with-pattern ([LINE-NUM (prefix-id "line-" #'NUM
                                      #:source #'NUM)])
    (syntax/loc caller-stx
      (define (LINE-NUM) (void) STATEMENT ...))))
#lang br
(require "struct.rkt")
(provide b-line)

(define-macro (b-line NUM STATE­MENT ...)
  (with-pattern ([LINE-NUM (prefix-id "line-" #'NUM
                                      #:source #'NUM)])
    (syntax/loc caller-stx
      (define (LINE-NUM) (void) STATE­MENT ...))))
copy to clipboard

One possible approach: we could pass NUM as an extra argu­ment to each STATEMENT. But that would be a drag, because we’d have to change the inter­face of every func­tion that imple­ments a state­ment to take a line-number argu­ment. Also, because a run-time error can be raised anywhere, we’d have to keep passing around this line-number value within the program just in case it’s needed. In sum: bad idea.

We could also set a global vari­able with the current line number, and then all the state­ment-imple­menting func­tions could read it. Save that for the next edition of JavaScript: The Good Parts.

Here’s a better idea: we’ll construct our line error in two steps, using excep­tions to transmit the pieces:

  1. The func­tion that first raises the error will call a new raise-line-error helper that raises an excep­tion of type line-error, with the specific error message as input:

    (raise-line-error "return without gosub")
    (raise-line-error "return without gosub")
    copy to clipboard

  2. This line-error excep­tion will be caught by the line func­tion at the top of the calling chain using an excep­tion handler. This excep­tion handler will prepend "error in line X" to the orig­inal message. Then it will raise a new error using this new message. That way, we’ll end up with errors in the style we want:

    error in line 70: return without gosub
    error in line 70: return without gosub
    copy to clipboard

That should work pretty well. But let’s also handle one small compli­ca­tion.

Even though every run-time error can be asso­ci­ated with a line in the program, the error may not be discov­ered until control has left the line func­tion.

One example is goto. Suppose we have a goto in our program that points at a nonex­is­tent line:

70 goto 1001001
70 goto 1001001
copy to clipboard

We get the following error:

error in line 70: line 1001001 not found
error in line 70: line 1001001 not found
copy to clipboard

But this error isn’t detected inside the line func­tion. Rather, it’s only detected when run handles the change-line-signal excep­tion from goto and discovers that the line number doesn’t exist. At that point, run raises an error, written in the friendly style:

basic/run.rkt
#lang br
(require "line.rkt" "struct.rkt")
(provide run)

(define (run line-table)
  (define line-vec
    (list->vector (sort (hash-keys line-table) <)))
  (with-handlers ([end-program-signal? (λ (exn-val) (void))])
    (for/fold ([line-idx 0])
              ([i (in-naturals)]
               #:break (>= line-idx (vector-length line-vec)))
      (define line-num (vector-ref line-vec line-idx))
      (define line-func (hash-ref line-table line-num))
      (with-handlers
          ([change-line-signal?
            (λ (cls)
              (define clsv (change-line-signal-val cls))
              (or
               (and (exact-positive-integer? clsv)
                    (vector-member clsv line-vec))
               (error (format "error in line ~a: line ~a not found"
                              line-num clsv))))])
        (line-func)
        (add1 line-idx))))) 
#lang br
(require "line.rkt" "struct.rkt")
(provide run)

(define (run line-table)
  (define line-vec
    (list->vector (sort (hash-keys line-table) <)))
  (with-handlers ([end-program-signal? (λ (exn-val) (void))])
    (for/fold ([line-idx 0])
              ([i (in-natu­rals)]
               #:break (>= line-idx (vector-length line-vec)))
      (define line-num (vector-ref line-vec line-idx))
      (define line-func (hash-ref line-table line-num))
      (with-handlers
          ([change-line-signal?
            (λ (cls)
              (define clsv (change-line-signal-val cls))
              (or
               (and (exact-posi­tive-integer? clsv)
                    (vector-member clsv line-vec))
               (error (format "error in line ~a: line ~a not found"
                              line-num clsv))))])
        (line-func)
        (add1 line-idx)))))
copy to clipboard

But this is a dupli­ca­tion of effort. Rather than handle a line-specific error outside the line func­tion, it would be better policy to centralize the handling of every line error inside the related line func­tion.

We’ll be using excep­tions to handle errors that arise “from below”. But we can handle errors that arise “from above” by adding an optional #:error argu­ment to every line func­tion. Rather than creating its own error, run can pass an error message back to the line func­tion, which can do the rest.  + Perhaps obvi­ously, we can’t use an excep­tion to commu­ni­cate the error message from run, because the line func­tion has already exited.

Imple­menting better line errors

First we add a new line-error struc­ture type to our "struct.rkt". line-error has one field, msg, that will store the specific error message:

basic/struct.rkt
#lang br
(provide (struct-out end-program-signal)
         (struct-out change-line-signal)
         (struct-out line-error))

(struct end-program-signal ())
(struct change-line-signal (val))
(struct line-error (msg))
#lang br
(provide (struct-out end-program-signal)
         (struct-out change-line-signal)
         (struct-out line-error))

(struct end-program-signal ())
(struct change-line-signal (val))
(struct line-error (msg))
copy to clipboard

By the way, in Racket projects, struc­ture types are often stored in their own module so they can be shared easily between other modules in the project.

Then we need to update "line.rkt":

basic/line.rkt
#lang br
(require "struct.rkt")
(provide b-line raise-line-error)

(define-macro (b-line NUM STATEMENT ...)
  (with-pattern ([LINE-NUM (prefix-id "line-" #'NUM
                                      #:source #'NUM)])
    (syntax/loc caller-stx
      (define (LINE-NUM)
        (with-handlers
            ([line-error?
              (λ (le) (handle-line-error NUM le))])
          (void)
          STATEMENT ...)))))

(define (raise-line-error error-msg)
  (raise (line-error error-msg)))

(define (handle-line-error num le)
  (error (format "error in line ~a: ~a"
                 num (line-error-msg le))))
#lang br
(require "struct.rkt")
(provide b-line raise-line-error)

(define-macro (b-line NUM STATE­MENT ...)
  (with-pattern ([LINE-NUM (prefix-id "line-" #'NUM
                                      #:source #'NUM)])
    (syntax/loc caller-stx
      (define (LINE-NUM)
        (with-handlers
            ([line-error?
              (λ (le) (handle-line-error NUM le))])
          (void)
          STATE­MENT ...)))))

(define (raise-line-error error-msg)
  (raise (line-error error-msg)))

(define (handle-line-error num le)
  (error (format "error in line ~a: ~a"
                 num (line-error-msg le))))
copy to clipboard

We add a raise-line-error func­tion that will take an error-msg argu­ment. This is what other func­tions will use to launch a line-error excep­tion. Within the b-line macro, we wrap the body of the line func­tion in with-handlers, which will detect a line-error? excep­tion and pass it to handle-line-error, along with the current line number. In turn, handle-line-error will make the full error message and pass it to error, which will raise a stan­dard error of type exn:fail.

That takes care of errors arising from below. Now let’s handle the ones coming from above, by adding an optional #:error argu­ment to our line-func­tion defi­n­i­tion:

basic/line.rkt
#lang br
(require "struct.rkt")
(provide b-line raise-line-error)

(define-macro (b-line NUM STATEMENT ...)
  (with-pattern ([LINE-NUM (prefix-id "line-" #'NUM
                                      #:source #'NUM)])
    (syntax/loc caller-stx
      (define (LINE-NUM #:error [msg #f])
        (with-handlers
            ([line-error?
              (λ (le) (handle-line-error NUM le))])
          (when msg (raise-line-error msg))
          STATEMENT ...)))))

(define (raise-line-error error-msg)
  (raise (line-error error-msg)))

(define (handle-line-error num le)
  (error (format "error in line ~a: ~a"
                 num (line-error-msg le))))
#lang br
(require "struct.rkt")
(provide b-line raise-line-error)

(define-macro (b-line NUM STATE­MENT ...)
  (with-pattern ([LINE-NUM (prefix-id "line-" #'NUM
                                      #:source #'NUM)])
    (syntax/loc caller-stx
      (define (LINE-NUM #:error [msg #f])
        (with-handlers
            ([line-error?
              (λ (le) (handle-line-error NUM le))])
          (when msg (raise-line-error msg))
          STATE­MENT ...)))))

(define (raise-line-error error-msg)
  (raise (line-error error-msg)))

(define (handle-line-error num le)
  (error (format "error in line ~a: ~a"
                 num (line-error-msg le))))
copy to clipboard

By default, the msg argu­ment is #f. So when the line func­tion is called normally, we won’t get an error. But we replace the (void) with a when that will use raise-line-error to create an error when msg exists.  + We can delete the (void) because when eval­u­ates to (void) if its condi­tion is false.

Finally, we return to "run.rkt" and rephrase the line-not-found error using the new #:error argu­ment:

basic/run.rkt
#lang br
(require "line.rkt" "struct.rkt")
(provide run)

(define (run line-table)
  (define line-vec
    (list->vector (sort (hash-keys line-table) <)))
  (with-handlers ([end-program-signal? (λ (exn-val) (void))])
    (for/fold ([line-idx 0])
              ([i (in-naturals)]
               #:break (>= line-idx (vector-length line-vec)))
      (define line-num (vector-ref line-vec line-idx))
      (define line-func (hash-ref line-table line-num))
      (with-handlers
          ([change-line-signal?
            (λ (cls)
              (define clsv (change-line-signal-val cls))
              (or
               (and (exact-positive-integer? clsv)
                    (vector-member clsv line-vec))
               (line-func #:error (format "line ~a not found" clsv))))])
        (line-func)
        (add1 line-idx))))) 
#lang br
(require "line.rkt" "struct.rkt")
(provide run)

(define (run line-table)
  (define line-vec
    (list->vector (sort (hash-keys line-table) <)))
  (with-handlers ([end-program-signal? (λ (exn-val) (void))])
    (for/fold ([line-idx 0])
              ([i (in-natu­rals)]
               #:break (>= line-idx (vector-length line-vec)))
      (define line-num (vector-ref line-vec line-idx))
      (define line-func (hash-ref line-table line-num))
      (with-handlers
          ([change-line-signal?
            (λ (cls)
              (define clsv (change-line-signal-val cls))
              (or
               (and (exact-posi­tive-integer? clsv)
                    (vector-member clsv line-vec))
               (line-func #:error (format "line ~a not found" clsv))))])
        (line-func)
        (add1 line-idx)))))
copy to clipboard

Testing our new errors

We’ll test raise-line-error when we get into our BASIC state­ments. For now, we can check that goto errors work the way we expect:

#lang basic
70 goto 1001001
℘
70 goto 1001001
copy to clipboard
error in line 70: line 1001001 not found
error in line 70: line 1001001 not found
copy to clipboard

True, this is exactly the same as the error we got before. But it shows that our new control flow is working correctly. The "line X not found" message is being passed from run to line-func, which adds the line number and reports the error.

The finished modules

basic/struct.rkt
#lang br
(provide (struct-out end-program-signal)
         (struct-out change-line-signal)
         (struct-out line-error))

(struct end-program-signal ())
(struct change-line-signal (val))
(struct line-error (msg))
#lang br
(provide (struct-out end-program-signal)
         (struct-out change-line-signal)
         (struct-out line-error))

(struct end-program-signal ())
(struct change-line-signal (val))
(struct line-error (msg))
copy to clipboard
basic/line.rkt
#lang br
(require "struct.rkt")
(provide b-line raise-line-error)

(define-macro (b-line NUM STATEMENT ...)
  (with-pattern ([LINE-NUM (prefix-id "line-" #'NUM
                                      #:source #'NUM)])
    (syntax/loc caller-stx
      (define (LINE-NUM #:error [msg #f])
        (with-handlers
            ([line-error?
              (λ (le) (handle-line-error NUM le))])
          (when msg (raise-line-error msg))
          STATEMENT ...)))))

(define (raise-line-error error-msg)
  (raise (line-error error-msg)))

(define (handle-line-error num le)
  (error (format "error in line ~a: ~a"
                 num (line-error-msg le))))
#lang br
(require "struct.rkt")
(provide b-line raise-line-error)

(define-macro (b-line NUM STATE­MENT ...)
  (with-pattern ([LINE-NUM (prefix-id "line-" #'NUM
                                      #:source #'NUM)])
    (syntax/loc caller-stx
      (define (LINE-NUM #:error [msg #f])
        (with-handlers
            ([line-error?
              (λ (le) (handle-line-error NUM le))])
          (when msg (raise-line-error msg))
          STATE­MENT ...)))))

(define (raise-line-error error-msg)
  (raise (line-error error-msg)))

(define (handle-line-error num le)
  (error (format "error in line ~a: ~a"
                 num (line-error-msg le))))
copy to clipboard
basic/run.rkt
#lang br
(require "line.rkt" "struct.rkt")
(provide run)

(define (run line-table)
  (define line-vec
    (list->vector (sort (hash-keys line-table) <)))
  (with-handlers ([end-program-signal? (λ (exn-val) (void))])
    (for/fold ([line-idx 0])
              ([i (in-naturals)]
               #:break (>= line-idx (vector-length line-vec)))
      (define line-num (vector-ref line-vec line-idx))
      (define line-func (hash-ref line-table line-num))
      (with-handlers
          ([change-line-signal?
            (λ (cls)
              (define clsv (change-line-signal-val cls))
              (or
               (and (exact-positive-integer? clsv)
                    (vector-member clsv line-vec))
               (line-func #:error (format "line ~a not found" clsv))))])
        (line-func)
        (add1 line-idx))))) 
#lang br
(require "line.rkt" "struct.rkt")
(provide run)

(define (run line-table)
  (define line-vec
    (list->vector (sort (hash-keys line-table) <)))
  (with-handlers ([end-program-signal? (λ (exn-val) (void))])
    (for/fold ([line-idx 0])
              ([i (in-natu­rals)]
               #:break (>= line-idx (vector-length line-vec)))
      (define line-num (vector-ref line-vec line-idx))
      (define line-func (hash-ref line-table line-num))
      (with-handlers
          ([change-line-signal?
            (λ (cls)
              (define clsv (change-line-signal-val cls))
              (or
               (and (exact-posi­tive-integer? clsv)
                    (vector-member clsv line-vec))
               (line-func #:error (format "line ~a not found" clsv))))])
        (line-func)
        (add1 line-idx)))))
copy to clipboard
← prev next →