diff --git a/pkgs/racket-doc/scribblings/reference/module-reflect.scrbl b/pkgs/racket-doc/scribblings/reference/module-reflect.scrbl index c02708f321..3039096463 100644 --- a/pkgs/racket-doc/scribblings/reference/module-reflect.scrbl +++ b/pkgs/racket-doc/scribblings/reference/module-reflect.scrbl @@ -476,6 +476,11 @@ Return @racket[#t] if @racket[compiled-module-code] represents a [fail-thunk (-> any) (lambda () ....)]) (or/c void? any/c)]{ +@margin-note{Because @racket[dynamic-require] is a procedure, giving a plain S-expression for +@racket[mod] the same way as you would for a @racket[require] expression likely won't give you +expected results. What you need instead is something that evaluates to an S-expression; using +@racket[quote] is one way to do it.} + Dynamically @tech{instantiates} the module specified by @racket[mod] in the current namespace's registry at the namespace's @tech{base phase}, if it is not yet @tech{instantiate}d. The current @tech{module @@ -494,6 +499,11 @@ above the @tech{base phase}. (dynamic-require ''a #f) ] +@margin-note{The double quoted @racket[''a] evaluates to the @racket[root-module-path] @racket['a] +(see the grammar for @racket[require]). Using @racket['a] or @racket[a] for @racket[mod] won't work +because the former evaluates to @racket[root-module-path] @racket[a] which fails since the example is +not a module installed in a collection, the latter is an undefined variable.} + When @racket[provided] is a symbol, the value of the module's export with the given name is returned, and still the module is not @tech{visit}ed or made @tech{available} in higher phases. @@ -535,6 +545,31 @@ If @racket[provided] is @|void-const|, then the module is @tech{visit}ed but not @tech{instantiate}d (see @secref["mod-parse"]), and the result is @|void-const|.} +More examples using different @racket[module-path] grammar expressions are given below: + +@examples[#:eval mod-eval + (dynamic-require 'racket/base #f) +] + +@examples[#:eval mod-eval + (dynamic-require (list 'lib "racket/base") #f) +] + +@examples[#:eval mod-eval + (module a racket/base + (module b racket/base + (provide inner-dessert) + (define inner-dessert "tiramisu"))) + (dynamic-require '(submod 'a b) 'inner-dessert) +] + +The last line in the above example could instead have been written as + +@examples[#:eval mod-eval + (dynamic-require ((lambda () (list 'submod ''a 'b))) 'inner-dessert) +] + +which is equivalent. @defproc[(dynamic-require-for-syntax [mod module-path?] [provided (or/c symbol? #f)]