Documentation

scribblings/subtemplate.scrbl

@@ -1,5 +1,6 @@
 #lang scribble/manual
-@require[@for-label[subtemplate
+@require[scriblib/footnote
+         @for-label[subtemplate
                     syntax/parse/experimental/template
                     racket/base]]
 
@@ -10,8 +11,8 @@
 
 @defform*[{(subtemplate template)
            (subtemplate template #:properties (prop ...))}
-         #:contracts
-         ([prop identifier?])]{
+          #:contracts
+          ([prop identifier?])]{
  Like @racket[template], but automatically derives identifiers for any
  @racket[yᵢ …] which is not bound as a syntax pattern variable, based on a
  corresponding @racket[xᵢ …] which is bound as a syntax pattern variable.
@@ -23,8 +24,8 @@
 
 @defform*[{(quasisubtemplate template)
            (quasisubtemplate template #:properties (prop ...))}
-         #:contracts
-         ([prop identifier?])]{
+          #:contracts
+          ([prop identifier?])]{
  Like @racket[quasitemplate], but automatically derives identifiers for any
  @racket[yᵢ …] which is not bound as a syntax pattern variable, based on a
  corresponding @racket[xᵢ …] which is bound as a syntax pattern variable, in
@@ -52,4 +53,56 @@ The @racketmodname[subtemplate/override] module also re-provides
 @racketmodname[stxparse-info/parse/experimental/template], but without
 @racket[template] and @racket[quasitemplate], which are remapped to their
 @racket[sub] equivalents, and without @racket[template/loc] and
-@racket[quasitemplate/loc], which do not have a @racket[sub] equivalent yet.
+@racket[quasitemplate/loc], which do not have a @racket[sub] equivalent yet.
+
+@section{Limitations}
+
+The derived subscripted identifiers have to be syntactically present within
+the template. In particular, if a template metafunction generates a part of a
+template containing @racket[yᵢ], it will work only if @racket[yᵢ] is also
+present in the "main" part of the template (possibly as an argument to the
+template metafunction, or elsewhere). Subscripted identifiers are not searched
+for within unquoted parts of the template.
+
+Currently, template metafunctions defined with
+@racketmodname[stxparse-info/parse/experimental/template] are not compatible
+with those from @racketmodname[syntax/parse/experimental/template], and vice
+versa. There is a pending pull request to make some level of compatibility
+possible, so this problem should hopefully be fixed sometime soon.
+
+More generally, there might still be some incompatibilities between
+@racketmodname[stxparse-info/parse] and @racketmodname[syntax/parse] (aside
+from the fact that @racket[subtemplate] cannot derive @racket[yᵢ] from
+@racket[xᵢ] if @racket[xᵢ] was defined by the ``official''
+@racketmodname[syntax/parse]), please report them to
+@url{https://github.com/jsmaniac/subtemplate/issues}.
+
+The code generated by @racket[subtemplate] is not very optimised, so
+compile-time and run-time performance will not be as good as with
+@racket[syntax] or @racket[template].
+
+Despite the rather extensive test suite, there are probably a few bugs lurking,
+please report them to @url{https://github.com/jsmaniac/subtemplate/issues}.
+
+@subsection{Omitted elements in attributes (via @racket[~optional]}
+
+When some values are missing in the ellipses of a template variable, e.g. via
+@racket[~optional], @racket[subtemplate] combines all the existing bound
+variables it can find with the correct subscript, in order to fill in as many
+elements of the derived variable. For example, if
+@racket[(attribute xᵢ)]@note{For readability reasons, we note @racket['(x y)]
+ instead of @racket[(list #'x #'y)] here.} returns
+@racket['((a #f #f) #f (g h i) #f)], and @racket[(attribute yᵢ)] returns
+@racket['(#f (4 5 6) (7 8 9) #f)], then for a derived @racket[zᵢ … …],
+@racket[(attribute zᵢ)] will contain
+@racket['((a/z xᵢ79/z xᵢ80/z) (4/z 5/z 6/z) (g/z h/z i/z) #f)]. The last
+element is @racket[#f], as @racket[subtemplate] lacks enough information to
+determine how many elements should be present within the list. The
+fully-nested @racket[#f] in @racket['(a #f #f)] are derived, as it is clear at
+that point that there is place for only a single omitted element.
+
+If new pattern variables with the same subscript are introduced after a
+generated variable was used, they should have the same structure (i.e. missing
+sublists in the same positions). Otherwise, the derived variable generated by
+@racket[subtemplate] would not contain the same elements before and after that
+new pattern variable was introduced.