3.3 Rhombus Objects and Racket Handles🔗ℹ

The rhombus/wrapper library provides support for a common Rhombus library pattern where a Rhombus class wraps a Racket representation. The wrapper class defines methods and properties for a Rhombus-like view on the underlying Racket object. Typically, the Rhombus class includes a handle property that returns the wrapper Racket representation, while a from_handle function creates a Rhombus wrapper object given a Racket representation.

Here’s a sketch of a typical class, which has a private _handle field, a constructor to create a Racket-level object through an imported #{make-fish} function, and a from_handle method that uses an imported #{fish?} function to check whether the handle is acceptable—throwing an exception with wrapper.error if not. Note that the placement of the from_handle function at the end of the Fish class declaration is important for allowing the result annotation :~ Fish.

class Fish(private _handle):

internal _Fish

export:

from_handle

constructor (....):

super(#{make-fish}(....))

property handle: _handle

fun from_handle(handle) :~ Fish:

~who: who

unless #{fish?}(handle)

| wrapper.error(~who: who, ~what: "fish", handle)

_Fish(handle)

Typically, there is no exposed predicate or annotation at the Rhombus layer to recognize acceptable handles, because the relevant Racket-level predicate is explained or implied by documentation in a way that does not create a direct cross reference (and therefore a documentation dependency). The thrown exception is nevertheless an instance of Exn.Fail.Annot to