On this page:

11.8 Syntax Certificates

+Syntax Certificates in Guide: Racket introduces syntax certificates.

A syntax certificate combines a syntax mark (see Transformer Bindings), a module path index or symbol module name (see Compiled Modules and References), an inspector (see Code Inspectors), and an arbitrary key object. A certificate is attached as either an active certificate or an inactive certificate.

The datum->syntax procedure never transfers an active certificate from one syntax object to another. The syntax-recertify procedure can be used to transfer a certificate from one syntax object to another, but only if the certificate’s key is provided, or if a sufficiently powerful inspector is provided. Thus, a certificate’s inspector serves two roles: it determines the certificate’s power to grant access, and also allows the certificate to be moved arbitrarily by anyone with a more powerful inspector.

The expander generates a certificate when it applies a syntax transformer. The syntax mark in the certificate is fresh, the certificate’s module reference corresponds to the module that defined the transformer binding, the inspector is the inspector for the module’s declaration (see Code Inspectors), and the key object is hidden. (Applying the result of syntax-local-certifier can introduce certificates with other keys.) The certificate’s mark is applied to both the input and output of the syntax transformer, so that it identifies every piece of syntax that was introduced by the transformer (see Transformer Bindings). The expander attaches this certificate to parts of the transformer’s result, depending on the shape and properties of the result:

To avoid accidental transfer for a 'certify-mode property value, the expander always removes any 'certify-mode property on a syntax object that is passed to a syntax transformer.

As the expander attaches a new active certificate to a syntax object, it also removes any inactive certificates attached to any syntax object within the one where the certificate is attached, and it re-attaches the formerly inactive certificates as active certificates along with the new one.

As the expander processes a form, it accumulates active certificates that are attached to enclosing forms as part of the expansion context:

Finally, for the result of expand or local-expand with an empty stop list, certificates are lifted to the outermost result expression, except to the degree that 'certify-mode property values and bindings like begin direct certificates to sub-expressions.

(syntax-recertify new-stx    
  key)  syntax?
  new-stx : syntax?
  old-stx : syntax?
  inspector : inspector?
  key : any/c
Copies certain certificates of old-stx to new-stx: a certificate is copied if its inspector is either inspector or controlled by inspector, or if the certificate’s key is key; otherwise the certificate is not copied. The result is a syntax object like new-stx, but with the copied certificates. (The new-stx object itself is not modified.) Both active certificates and inactive certificates are copied.