commit e572113b0ca8f3c46e2107d9b22a53884b86d8c7
parent a2c817c7cd76ca551214682f6751ac039c65173a
Author: Georges Dupéron <georges.duperon@gmail.com>
Date: Tue, 9 May 2017 19:52:42 +0200
Missing bits in the docs.
Diffstat:
1 file changed, 30 insertions(+), 7 deletions(-)
diff --git a/scribblings/polysemy.scrbl b/scribblings/polysemy.scrbl
@@ -17,14 +17,31 @@ This module allows defining polysemic identifiers which can act as a
@tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{match expander},
as a @tech[#:doc '(lib "scribblings/guide/guide.scrbl")]{macro}, as an
@tech[#:doc '(lib "scribblings/guide/guide.scrbl")]{identifier macro}, as a
-@racket[set!] subform, and as a collection of
-
+@racket[set!] subform, and as a collection of function overloads.
+
+The following meanings are special:
+
+@itemlist[
+ @item{The value for the @racket[normal-macro] meaning is used when the
+ identifier appears as the first element of a macro application (i.e. when it
+ is used as a as a @tech[#:doc '(lib "scribblings/guide/guide.scrbl")]{
+ macro}).}
+ @item{The value for the @racket[identifier-macro] meaning is used when the
+ identifier appears on its own as an expression (i.e. when it is used as an
+ @tech[#:doc '(lib "scribblings/guide/guide.scrbl")]{identifier macro}).}
+ @item{The value for the @racket[match-expander] meaning is used when the
+ identifier is used as a match template}
+ @item{The value for the @racket['set!-macro] meaning is used when the
+ identifier is appears as the second element of a @racket[set!] form.}
+ @item{Other "core" meanings may be added later, and third-party libraries can
+ define their own meanings.}]
In all the forms below, the @racket[_meaning] should be a simple identifier.
-Note that is lexical context is not taken into account (i.e. it is used as a
-symbol), and therefore every @racket[_meaning] should be globally unique.
-Later versions may add a notion of hygiene to meanings (allowing these
-meanings themselves to be renamed, to circumvent conflicts).
+Note that is lexical context is not taken into account (i.e. the comparison is
+based on the equality of symbols, not based on @racket[free-identifier=?]),
+and therefore every @racket[_meaning] should be globally unique. Later
+versions may add a notion of hygiene to meanings (allowing these meanings
+themselves to be renamed, to circumvent conflicts).
@defform[#:kind "require transformer"
(poly-only-in module [maybe-rename meaning ...] ...)
@@ -78,7 +95,13 @@ meanings themselves to be renamed, to circumvent conflicts).
Defines @racket[id] as a literal with the given @racket[meaning]. The
@racket[syntax-class] is automatically defined to recognise the given
@racket[meaning] of @racket[id], even if @racket[id] was renamed and its
- different meanings split out and recombined into different identifiers.}
+ different meanings split out and recombined into different identifiers.
+
+ This can be used to define "tokens" for macros, which bear a special meaning
+ for some macros, but might have a different meaning for another third-party
+ macro. If both rely on @racketmodname[polysemy], then they can use the same
+ default name, without the risk of the identifiers conflicting. Furthermore, it
+ is possible to rename the two meanings separately.}
@defform[(define-poly-case (name [arg₀ pred?] argᵢ ...) . body)]{
Note that the syntax for this form will be changed in the future when support
