Implementing Ht  DP Teachpacks, Libraries, and Customized Teaching Languages
1 Error Message Composition Guidelines
1.1 General Guidelines
1.2 Message Structure and Form
1.3 Words For Describing Code
1.4 Words For Describing Runtime Behavior
1.5 Prohibited Words
1.6 General Vocabulary Guidelines
1.7 Punctuation
1.8 Supporting Research
2 Error Reporting Functions
check-arg
check-arity
check-proc
check-result
check-list-list
check-color
check-fun-res
natural?
find-non
check-dependencies
tp-error
tp-exn?
number->ord
3 Testing
build-test-engine
builder
display-results
error-handler
exn:  fail:  wish
get-test-engine
reset-tests
run-tests
scheme-test-data
signature-test-info%
generate-report
4 Ht  DP Languages as Libraries
4.1 Ht  DP Beginning Student
4.2 Ht  DP Beginning Student with Abbreviations
4.3 Ht  DP Intermediate Student
4.4 Ht  DP Intermediate Student with Lambda
4.5 Ht  DP Advanced Student
4.6 Pretty Big Text (Legacy Language)
4.7 Pretty Big (Legacy Language)
4.8 posns in Ht  DP Languages
posn
4.9 Image Equality in Ht  DP Languages
image=?
4.10 Primitives in Ht  DP Beginner
define-primitive
provide-primitive
provide-primitives
define-higher-order-primitive
provide-higher-order-primitive
first-order->higher-order
5 Color and Alpha Color Structs
color
alpha-color
6.11

Implementing HtDP Teachpacks, Libraries, and Customized Teaching Languages

DrRacket has two different mechanisms for making available additional functions and functionality to students using the teaching languages.

Under the hood, HtDP Teachpacks and HtDP Libraries are implemented the same way, using normal Racket Modules.

When implementing such an extension for students, pay a special attention to two aspects:
  1. choice of construct: The teaching languages limit the expressive power in comparison to plain Racket. One goal is to teach “design subject to constraints,” and the other one is to help restrict the set of explanations for student errors. With regard to the first, we consider it imperative that new teachpacks and libraries avoid features intended for upper-level students or professionals.

  2. error messages: The error messages from the teaching languages go to great length to never confront students messages that uses vocabulary or phrases outside of the scope of the chosen level. While teachpacks and libraries can be used at all levels, they should ideally restrict the vocabulary in error message to the lowest level language in which they are to be used.

This manual describes library support for authors of HtDP Teachpacks, libraries, and customized teaching languages. Use the HtDP error reporting functions to create error messages that integrate smoothly with those of the teaching languages. Before composing new error messages, we recommend you read the error message composition guidelines that informed the design of the error messages of DrRacket’s teaching languages.

    1 Error Message Composition Guidelines

    2 Error Reporting Functions

    3 Testing

    4 HtDP Languages as Libraries

    5 Color and Alpha Color Structs

1 Error Message Composition Guidelines

This section lists some guidelines for writing good error messages for novices, as informed by our research. Please follow these guidelines when you write code that is intended for beginners, including libraries and teachpacks. It ensures that error messages from your code fits messages from the student languages and from other teachpacks.

1.1 General Guidelines

1.2 Message Structure and Form

1.3 Words For Describing Code

Use only the following vocabulary words to describe code:

function

variable

argument

function body

expression

part

clause

top level

structure name

type name

field name

binding

1.4 Words For Describing Runtime Behavior

Use the following vocabulary words to describe how code runs:

1.5 Prohibited Words

These guidelines use few terms intentionally, emphasizing commonality among concepts rather than technical precision (which most students do not appreciate anyway).

Instead of

Use

procedure, primitive name, primitive operator, predicate, selector, constructor

“function”

s-expression

“expression”

identifier

“argument” or “variable”, depending on the use in the program

defined name

“function” or “variable”

sequence

“at least one (in parentheses)”

function header

“after define”, “after the name”, “after the first argument”, ...

keyword

mention the construct directly by name, such as “expected a variable but found a cond”

built-in

Nothing — avoid this term

macro

Nothing — avoid this term

1.6 General Vocabulary Guidelines

1.7 Punctuation

1.8 Supporting Research

These guidelines arose from a collections of research studies held at the Worcester Polytechnic Institute, Brown University, and Northeastern University. Further experiment details and results are described in:

2 Error Reporting Functions

 (require htdp/error) package: htdp-lib

To provide uniform error messages from teachpacks, this module provides several functions:

procedure

(check-arg name chk expected position given)  void?

  name : (or/c symbol? string?)
  chk : boolean?
  expected : any/c
  position : (or/c (and/c positive? integer?) string?)
  given : any/c
Checks an flat-valued argument to function name. Reports an error for function name telling students what kind of data is expected at the position-th argument and displaying what value was actually given, unless chk is #true.

procedure

(check-arity name [arg#] args)  void?

  name : (or/c symbol? string?)
  arg# : (or/c (and/c positive? integer?) string?) = ?
  args : list?
Checks the arity of a procedure-valued argument to function name. Reports an error for function name telling students that (length args) arguments were provided but arg# were expected, unless (= (length args) arg#) produces #true.

procedure

(check-proc name proc expected arg# arg-err)  void?

  name : (or/c symbol? string?)
  proc : any/c
  expected : natural?
  arg# : (or/c (and/c positive? integer?) string?)
  arg-err : string?
Checks [the properties of] a procedure-valued argument to function name. Reports an error for function name telling students that a procedure was expected at position arg# and that this procedure should be of arity expected, unless the proc is a function and has the expected arity. The string arg-err is used to describe the higher-order argument.

procedure

(check-result name pred? kind returned ...+)  void?

  name : (or/c symbol? string?)
  pred? : (-> any/c boolean?)
  kind : (or/c symbol? string?)
  returned : any/c
Checks the expected result of a procedure-valued argument. If the result satisfies pred?, it is returned. Otherwise, the function reports an error for function name telling students what kind of value is expected and what the returned value is. NOTE: if there is more than one returned value, the function uses the second value. (MF: I forgot why.)

procedure

(check-list-list name chk pred? given)  void?

  name : (or/c symbol? string?)
  chk : (or/c string? false/c)
  pred? : any/c
  given : any/c
Checks a list-of-lists-valued argument to function name. Reports an error for function name if a list-of-lists contains a value of the wrong kind—signaled via a string-valued chk. The given value is the element that went wrong. Rarely used.

procedure

(check-color name arg# given)  void?

  name : (or/c symbol? string?)
  arg# : natural?
  given : any/c
Checks a color-valued argument to function name. Deprecated. Use image-color? instead.

procedure

(check-fun-res f pred? type)  void?

  f : procedure?
  pred? : (-> any/c boolean?)
  type : (or/c symbol? string?)
Creates a callback from f and uses check-result to make sure the result is a piece of data that satisfies pred?, described as type.

procedure

(natural? o)  boolean?

  o : any/c
Determines whether the given value is a natural number.

procedure

(find-non pred? l)  (or/c any/c false/c)

  pred? : (-> any/c boolean?)
  l : list?
Find an element of l for which (pred? l) produces #true; otherwise return #false.

procedure

(check-dependencies name chk fmt arg ...)  void?

  name : (or/c symbol? string?)
  chk : boolean?
  fmt : format-string?
  arg : any/c
Unless chk is #true, it raises an error called name whose message is composed from fmt and the args.

procedure

(tp-error name fmt arg ...)  void?

  name : (or/c symbol? string?)
  fmt : format-string?
  arg : any/c
Signals an exn:fail:contract from fmt and arg for a function called name.

procedure

(tp-exn? o)  boolean?

  o : any/c
Determine whether the given object is a teachpack exception MF: Guillaume seems to have deprecated these structures.

procedure

(number->ord n)  string?

  n : natural?
Convert a position number into a string, e.g., 1 into “first” and so on.

MF: These library and its uses needs to be cleaned up.

3 Testing

 (require htdp/testing) package: htdp-lib

The library re-exports the following identifiers from test-engine/racket-tests

procedure

(build-test-engine)  void?

procedure

(builder)  void?

procedure

(display-results)  void?

procedure

(error-handler)  void?

procedure

(exn:fail:wish)  void?

procedure

(get-test-engine)  void?

procedure

(reset-tests)  void?

procedure

(run-tests)  void?

procedure

(scheme-test-data)  void?

procedure

(signature-test-info%)  void?

procedure

(generate-report)  void?

The same as test.

4 HtDP Languages as Libraries

4.1 HtDP Beginning Student

 (require lang/htdp-beginner) package: htdp-lib

The lang/htdp-beginner module provides the Beginning Student Language; see Beginning Student.

4.2 HtDP Beginning Student with Abbreviations

 (require lang/htdp-beginner-abbr) package: htdp-lib

The lang/htdp-beginner-abbr module provides the Beginning Student with Abbreviations language; see Beginning Student with List Abbreviations.

4.3 HtDP Intermediate Student

 (require lang/htdp-intermediate) package: htdp-lib

The lang/htdp-intermediate module provides the Intermediate Student language; see Intermediate Student.

4.4 HtDP Intermediate Student with Lambda

 (require lang/htdp-intermediate-lambda)
  package: htdp-lib

The lang/htdp-intermediate-lambda module provides the Intermediate Student with Lambda language; see Intermediate Student with Lambda.

4.5 HtDP Advanced Student

 (require lang/htdp-advanced) package: htdp-lib

The lang/htdp-advanced module provides the Advanced Student language; see Advanced Student.

4.6 Pretty Big Text (Legacy Language)

 (require lang/plt-pretty-big-text) package: htdp-lib

The lang/plt-pretty-big-text module is similar to the HtDP Advanced Student language, but with more of Racket’s libraries in legacy form. It provides the bindings of mzscheme, mzlib/etc, mzlib/file, mzlib/list, mzlib/class, mzlib/unit, mzlib/include, mzlib/defmacro, mzlib/pretty, mzlib/string, mzlib/thread, mzlib/math, mzlib/match, mzlib/shared, and lang/posn.

4.7 Pretty Big (Legacy Language)

 (require lang/plt-pretty-big) package: htdp-lib

The lang/plt-pretty-big module extends lang/plt-pretty-big-text with racket/gui/base and lang/imageeq. This language corresponds to the Pretty Big legacy language in DrRacket.

4.8 posns in HtDP Languages

 (require lang/posn) package: htdp-lib

struct

(struct posn (x y)
    #:extra-constructor-name make-posn)
  x : any/c
  y : any/c
The posn structure type that is also provided by lang/htdp-beginner.

4.9 Image Equality in HtDP Languages

 (require lang/imageeq) package: htdp-lib

procedure

(image=? i1 i2)  boolean?

  i1 : (is-a?/c image-snip%)
  i2 : (is-a?/c image-snip%)
The image-comparison operator that is also provided by lang/htdp-beginner.

4.10 Primitives in HtDP Beginner

 (require lang/prim) package: htdp-lib

The lang/prim module several syntactic forms for use by the implementors of teachpacks, when the teachpack is to be used with the Beginner Student Language. In Beginner Student, primitive names (for built-in procedures) are distinguished from other types of expressions, so that they can be syntactically restricted to application positions.

syntax

(define-primitive id proc-id)

Defines id to be a primitive operator whose implementation is proc-id, and that takes no procedures as arguments. Normally, id is exported from the teachpack and proc-id is not.

syntax

(provide-primitive id)

Like define-primitive, but the existing function id is exported as the primitive operator named id. An alternative to define-primitive.

syntax

(provide-primitives id ...)

Multiple-identifier version of provide-primitive.

syntax

(define-higher-order-primitive id proc-id (arg ...))

Defines id to be a primitive operator whose implementation is proc-id. Normally, id is exported from the teachpack and proc-id is not.

For each non-procedure argument, the corresponding arg should be an underscore. For each procedure argument, the corresponding arg should be the usual name of the procedure.

Examples:

(define-higher-order-primitive convert-gui convert-gui/proc (f2c))

syntax

(provide-higher-order-primitive id (arg ...))

Like define-higher-order-primitive, but the existing function id is exported as the primitive operator named id. An alternative to define-higher-order-primitive.

syntax

(first-order->higher-order expression)

If expression is the name of a first-order function (either a primitive or a function defined within Beginner Student), produces the function as a value; otherwise, the form is equivalent to expression.

This form is mainly useful for implementing syntactic forms that, like the application of a higher-order primitive, allow first-order bindings to be used in an expression position.

5 Color and Alpha Color Structs

 (require htdp/color-structs) package: htdp-lib

struct

(struct color (red green blue)
    #:extra-constructor-name make-color)
  red : any/c
  green : any/c
  blue : any/c
This is the color struct that is also exported by htdp/image, but here it is exported via (provide (struct-out color)).

struct

(struct alpha-color (alpha red green blue)
    #:extra-constructor-name make-alpha-color)
  alpha : any/c
  red : any/c
  green : any/c
  blue : any/c
This is the color struct that is also exported by htdp/image, but here it is exported via (provide (struct-out alpha-color)).