refine and document Racket-Rhombus interoperability

Author: mflatt

rhombus-lib/info.rkt

@@ -17,4 +17,4 @@
 (define license '(Apache-2.0 OR MIT))
 
 ;; keep in sync with runtime version at "rhombus/private/amalgam/version.rkt"
-(define version "0.33")
+(define version "0.34")

rhombus-lib/rhombus/dot.rkt

@@ -0,0 +1,15 @@
+#lang racket/base
+(require (submod "private/amalgam.rkt" dot))
+
+(provide dynamic-dot-ref
+         dynamic-dot-set!)
+
+(define (dynamic-dot-ref obj name)
+  (unless (symbol? name)
+    (raise-argument-error 'dynamic-dot-ref "Symbol" name))
+  (dot-lookup-by-name obj name))
+
+(define (dynamic-dot-set! obj name val)
+  (unless (symbol? name)
+    (raise-argument-error 'dynamic-dot-set! "Symbol" name))
+  (dot-assign-by-name obj name val))

rhombus-lib/rhombus/parse.rkt

@@ -1,5 +1,11 @@
 #lang racket/base
+(require (rename-in (submod "private/amalgam.rkt" parse)
+                    [rhombus-expression parse:rhombus-expression]))
 
-(require (submod "private/amalgam.rkt" parse))
+(provide rhombus-expression
+         rhombus-top)
 
-(provide (all-from-out (submod "private/amalgam.rkt" parse)))
+(define-syntax-rule (rhombus-expression e)
+  ;; an expression may expand to `(begin (quote-syntax statinfo) expr)`,
+  ;; so make sure that's not spliced in a definition context
+  (let () (parse:rhombus-expression e)))

rhombus-lib/rhombus/private/amalgam-src.rkt

@@ -120,3 +120,6 @@
 (module+ evt
   (bounce "amalgam/evt.rkt")
   (bounce "amalgam/evt.rhm"))
+
+(module+ dot
+  (bounce (submod "amalgam/dot.rkt" for-external)))

rhombus-lib/rhombus/private/amalgam/dot.rkt

@@ -47,6 +47,10 @@
             parse-dot-expr
             parse-dot-repet)))
 
+(module+ for-external
+  (provide dot-lookup-by-name
+           dot-assign-by-name))
+
 (begin-for-syntax
   (property dot-provider (handler))
 

rhombus-lib/rhombus/private/amalgam/version.rkt

@@ -3,4 +3,4 @@
 (provide version)
 
 ;; keep in sync with package version at "../../../info.rkt"
-(define version "0.33")
+(define version "0.34")

rhombus-scribble-lib/rhombus/scribble/private/typeset-example.rkt

@@ -3,7 +3,8 @@
                      syntax/parse/pre)
          racket/string
          racket/syntax-srcloc
-         rhombus/parse
+         (only-in rhombus/parse
+                  rhombus-expression)
          racket/sandbox
          file/convertible
          racket/port

rhombus/rhombus/scribblings/info.rkt

@@ -1,6 +1,7 @@
 #lang info
 
 (define scribblings '(("rhombus.scrbl" (multi-page) (language))
-                      ("reference/rhombus-reference.scrbl" (multi-page) (language))))
+                      ("reference/rhombus-reference.scrbl" (multi-page) (language))
+                      ("rhombus-racket/rhombus-racket.scrbl" (multi-page) (interop))))
 
 (define test-omit-paths 'all)

rhombus/rhombus/scribblings/rhombus-racket/data.scrbl

@@ -0,0 +1,77 @@
+#lang rhombus/scribble/manual
+@(import:
+    "racket_names.rkt" open
+    meta_label:
+      rhombus open)
+
+@(def rhombus_doc = ModulePath'lib("rhombus/scribblings/reference/rhombus-reference.scrbl")')
+@(def racket_doc = ModulePath'lib("scribblings/reference/reference.scrbl")')
+
+@title(~tag: "data"){Common Run-Time Representations}
+
+Rhombus and Racket share the same or related representations for many
+basic forms of data:
+
+@itemlist(
+
+ @item{Booleans are the same.}
+
+ @item{Numbers are the same, including @tech(~doc: rhombus_doc){fixnums}
+ and @tech(~doc: rhombus_doc){flonums}.}
+
+ @item{Characters, strings, and byte strings are the same. Beware,
+ however, that Racket strings are mutable by default, which satisfies
+ Rhombus's @rhombus(ReadableString, ~annot) but not
+ @rhombus(String, ~annot).}
+
+ @item{Symbols and keywords. A keyword is written in shrubbery notation
+ for Rhombus with a @litchar{~} prefix, and it is written in S-expression
+ notation with a @litchar{#:} prefix, but the representation does not
+ include that prefix.}
+
+ @item{Functions, including functions with keyword arguments are the
+ same. Note that a Racket keyword with non-alphabetic characters can be
+ written in rhombus using @litchar("#{")…@litchar("}") notation, as in
+ @rhombus(work(#{#:fast?}: #true)).}
+
+ @item{Pairs are the same. Racket @tech(~doc: racket_doc){lists} are
+ Rhombus @tech(~doc: rhombus_doc){pair lists}, Rhombus
+ @tech(~doc: rhombus_doc){lists} correspond to
+ @racketmod_racket_treelist, and Rhombus @tech(~doc: rhombus_doc){mutable
+  lists} correspond to @racketmod_racket_mutable_treelist.}
+
+ @item{Racket @tech(~doc: racket_doc){vectors} and Rhombus
+ @tech(~doc: rhombus_doc){arrays} are the same, and boxes are the same in
+ both.}
+
+ @item{Racket @tech(~doc: racket_doc){hash tables} and Rhombus
+ @tech(~doc: rhombus_doc){maps} are the same. Rhombus
+ @tech(~doc: rhombus_doc){sets} are unrelated to any Racket data
+ structure, although the implementation internally uses Racket hash
+ tables.}
+
+ @item{Racket @tech(~doc: racket_doc){sequences} and Rhombus
+ @tech(~doc: rhombus_doc){sequences} are the same.}
+
+ @item{The void value and end-of-file object are the same.}
+
+ @item{Rhombus and Racket syntax objects are the same. A Rhombus syntax
+ object encodes shrubbery structure within an S-expression syntax object
+ as described in
+ @secref(~doc: ModulePath'lib("shrubbery/scribblings/shrubbery.scrbl")', "parsed-rep").}
+
+)
+
+In many other cases, the Rhombus representation of an entity is a
+wrapper on a Racket representation. For example, a Rhombus
+@rhombus(Thread, ~class) object wraps a Racket thread object. In those
+case, a common convention within Rhombus is to provide access to the
+Racket representation through a @rhombus(handle) property, and sometimes
+a @rhombus(from_handle) function is provided to construct a Rhombus
+object wrapper for a suitable Racket value.
+
+Rhombus wrappers enable a dynamic @rhombus(.) operation to find methods
+and properties. Although dynamic @rhombus(.) works on some kinds of
+Racket values without a wrapper, such as strings and lists, it relies on
+built-in support by the @rhombus(.) operator. Rhombus has no safe and
+composable way to extend that built-in set.

rhombus/rhombus/scribblings/rhombus-racket/dot.scrbl

@@ -0,0 +1,29 @@
+#lang scribble/manual
+@(require (for-label rhombus/dot
+                     racket/base
+                     racket/contract/base
+                     rhombus/parse))
+
+@title{Dynamic Dot from Racket}
+
+@defmodule[rhombus/dot]
+
+The Rhombus dot operator can be used via @racket[rhombus-expression],
+but the @racketmodname[rhombus/dot] module provides a simpler and more
+convenient interface for dynamic access of object fields, methods, and
+properties.
+
+@defproc[(dynamic-dot-ref [obj any/c] [name symbol?]) any/c]{
+
+ Accesses a field, method, or property @racket[name] from @racket[obj].
+ An exception is raised if no such member exists in @racket[obj].
+
+}
+
+@defproc[(dynamic-dot-set! [obj any/c] [name symbol?] [val any/c]) any/c]{
+
+ Modifies @racket[obj] to set the field or property @racket[name] in
+ @racket[obj] to @racket[val]. An exception is raised if no such mutable
+ member exists in @racket[obj].
+
+}

rhombus/rhombus/scribblings/rhombus-racket/module.scrbl

@@ -0,0 +1,72 @@
+#lang rhombus/scribble/manual
+@(import:
+    "racket_names.rkt" open
+    meta_label:
+      rhombus open
+      rhombus/meta:
+        expose:
+          expr_meta
+          defn_meta
+          decl_meta)
+
+@title(~tag: "module"){Modules and Exports}
+
+Rhombus and Racket modules exist in the same module system with the same
+filesystem- and collection-based paths, so a Rhombus module can
+@rhombus(import) a Racket module, and a Racket module can
+@racket_require a Rhombus module.
+
+@itemlist(
+
+ @item{Relative-path module references and Rhombus @rhombus(file, ~impo)
+ or Racket @racket_file paths work the same, where a @filepath{.rhm} or
+ @filepath{.rkt} file suffix can be used in either language.}
+
+ @item{A module name in Rhombus without quotes, such as
+ @rhombusmodname(rhombus/random), implicitly gets a @filepath{.rhm}
+ suffix or refers to a @filepath{main.rhm} file (when there is no
+ @litchar{/}), while a similar Racket module name like
+ @racketmod_racket_math implicitly gets a @filepath{.rkt} suffix or
+ refers to a @filepath{main.rkt} file.
+
+ To refer to a collection-based @filepath{.rkt} file from Rhombus, use
+ the @rhombus(lib, ~impo) form, as in @rhombus(lib("racket/math.rkt")).
+ To refer to a collection-based @filepath{.rhm} file from Racket, use the
+ @racket_lib form as in @racketmod_rhombus_random.}
+
+)
+
+While importing bindings from one language into the other is relatively
+straightforward, not all imported bindings can be used directly:
+
+@itemlist(
+
+ @item{A Racket binding can be used in a Rhombus expression if it
+ corresponds to a non-macro definition or if it is an identifier macro
+ that can be used alone as an expression.}
+
+ @item{A Racket binding for a syntactic form (i.e., a macro) cannot be
+ used directly in a Rhombus expression. Even though a use of the
+ syntactic form in Racket looks like a function call, the Rhombus
+ function call form does not (necessarily) expand to a Racket
+ form with a function-call shape.
+
+ Using a Racket syntactic form from Rhombus requires a Rhombus macro
+ that expands to the Racket form. See @secref("racket-expr") for more
+ information.}
+
+ @item{A Rhombus binding can be used in a Racket expression if it
+ corresponds to a @rhombus(fun, ~defn) definition or a
+ @rhombus(def, ~defn) form where the binding is just an identifier or
+ parenthesized identifiers @rhombus(values, ~bind). Other @rhombus(def)
+ binding forms may work, but there is no guarantee, so do not rely on
+ current behavior. Note that many Rhombus binding forms define
+ identifiers that can be used as expressions, but they are implemented as
+ syntactic forms; notably, the constructor bound by a
+ @rhombus(class, ~defn) definition is not like a @rhombus(fun) binding.
+
+ To use a Rhombus binding form Racket in general, use
+ @racket_rhombus_expression from @racketmod_rhombus_parse.}
+
+
+)

rhombus/rhombus/scribblings/rhombus-racket/parse.scrbl

@@ -0,0 +1,33 @@
+#lang scribble/manual
+@(require (for-label rhombus/parse
+                     racket/base))
+
+@title{Rhombus Expressions in Racket}
+
+@defmodule[rhombus/parse]
+
+Rhombus shrubbery forms can be written in S-expressions using the
+encoding described in @secref[#:doc '(lib "shrubbery/scribblings/shrubbery.scrbl") "parsed-rep"].
+The @racket[rhombus-expression] and @racket[rhombus-top] forms treat an encoding
+as a Rhombus expression or a module-level Rhombus sequence, respectively.
+
+The forms use Rhombus bindings that are @racket[require]d into the
+enclosing context. Binding does not matter for structural tokens like
+@racket[group] or @racket[op], but they matter for S-expression
+identifiers that represent shrubbery identifiers and operations.
+
+@defform[(rhombus-expression shrubbery)]{
+
+ Parses @racket[shrubbery] as a Rhombus expression for a Racket
+ expression context. The @racket[shrubbery] form should represent a
+ group, meaning that it should be a list-shaped S-expression that starts
+ with the identifier @racket[group].
+
+}
+
+@defform[(rhombus-top shrubbery)]{
+
+ Parses @racket[shrubbery] as a Rhombus module-body sequence for a
+ Racket module context. The @racket[shrubbery] form should be a
+ list-shaped S-expression that starts with the identifier @racket[multi].
+}

rhombus/rhombus/scribblings/rhombus-racket/racket-expr.scrbl

@@ -0,0 +1,47 @@
+#lang rhombus/scribble/manual
+@(import:
+    "racket_names.rkt" open
+    meta_label:
+      rhombus open
+      rhombus/meta:
+        expose:
+          expr_meta
+          defn_meta
+          decl_meta
+          expr)
+
+@title(~tag: "racket-expr"){Racket Expressions from Rhombus}
+
+Using a Racket syntactic form from Rhombus requires a Rhombus macro that
+expands to the Racket form. A Rhombus macro can build a use of a Racket
+syntactic form using @rhombus(expr_meta.pack_s_exp),
+@rhombus(defn_meta.pack_s_exp), or @rhombus(decl_meta.pack_s_exp). Use
+@rhombus(expr_meta.pack_expr) to pack a Rhombus expression for use
+within a packed S-expression form.
+
+For example, the following @rhombus(shared) macro expands to a use of the
+Racket @racket_shared form, which specifically recognizes uses of the
+Racket @racket_cons function.
+
+@examples(
+  ~defn:
+    import:
+      rhombus/meta open
+      lib("racket/base.rkt").cons
+      lib("racket/shared.rkt").shared as rkt_shared
+  ~defn:
+    expr.macro 'shared ($(id :: Identifier) = $rhs ...,
+                        ...):
+                  $body
+                  ...':
+      expr_meta.pack_s_exp(['rkt_shared',
+                            [[id, expr_meta.pack_expr('$rhs ...')],
+                             ...],
+                            expr_meta.pack_expr('block:
+                                                   $body
+                                                   ...')])
+  ~repl:
+    shared (x = cons(1, y),
+            y = cons(2, x)):
+      x.rest.rest.rest.first
+)

rhombus/rhombus/scribblings/rhombus-racket/racket_names.rkt

@@ -0,0 +1,31 @@
+#lang at-exp racket/base
+(require scribble/manual
+         (for-label racket/base
+                    rhombus/parse
+                    racket/shared))
+
+(provide racket_require
+         racket_lib
+         racket_file
+         racketmod_racket_math
+         racketmod_rhombus_random
+         racketmod_rhombus_parse
+         racketmod_racket_treelist
+         racketmod_racket_mutable_treelist
+         racket_rhombus_expression
+         racket_shared
+         racket_cons)
+
+(define racket_require @racket[require])
+(define racket_lib @racket[lib])
+(define racket_file @racket[file])
+
+(define racketmod_racket_math @racketmodname[racket/math])
+(define racketmod_rhombus_random @racketmodname[(lib "rhombus/random.rhm")])
+(define racketmod_rhombus_parse @racketmodname[rhombus/parse])
+(define racketmod_racket_treelist @racketmodname[racket/treelist])
+(define racketmod_racket_mutable_treelist @racketmodname[racket/mutable-treelist])
+
+(define racket_rhombus_expression @racket[rhombus-expression])
+(define racket_shared @racket[shared])
+(define racket_cons @racket[cons])