[plt-scheme] require-for-syntax and syntax/parse

On Sep 14, 2009, at 7:06 PM, Neil Toronto wrote:

> This:
>
>    (require-for-syntax syntax/parse)
>
>    (define-syntax (blah stx)
>      (syntax-parse stx
>        [(_) #''blah]))
>
> gives an error:
>
>    expand: unbound identifier in module (transformer environment)  
> in: syntax-parse
>
> The docs for require-for-syntax say (require-for-syntax syntax/ 
> parse) should expand to (#%require (for-syntax syntax/parse)). But  
> using (#%require (for-syntax syntax/parse)) doesn't give an error in  
> the example above.

'require-for-syntax' is part of #lang mzscheme, not #lang scheme.  
That's probably why it had no effect. It would have caused an unbound  
identifier error, but the error for 'syntax-parse' happened first  
because it was in a macro body.

Try instead, (require (for-syntax syntax/parse)).

> There's a related user-interface problem with the docs. There's no  
> indication of what environment an identifier will be bound in. This  
> is compounded by misleading example code. For example, the docs for  
> syntax/parse have
>
>    (require syntax/parse)
>
> which is great if you're building libraries for creating syntax  
> transformers but wastes your time if you're just using those  
> libraries. This, along with the broken require-for-syntax, cost me a  
> couple of hours recompiling from svn, because I thought my local  
> build was broken. It looked like syntax-parse wasn't bound in any  
> environment when I used it inside define-syntax.

I'll add a note about this. I expect the most helpful thing, though,  
is a set of introductory examples. I'll add that this afternoon. (It's  
been on my queue for a while.)

> Is syntax-parse within define-syntax (like syntax-case within define- 
> syntax) the most common expected use case?

Yes, but not exclusively, since you currently must use (require syntax/ 
parse) to define syntax classes at module level (and that module must  
be required for-syntax for the syntax classes to be used by macros).

> Is it possible to indicate in the docs what environment an  
> identifier will be bound in?

With very few exceptions, "library" modules like syntax/parse export  
all of their bindings at phase 0 (the normal environment). So add 'for- 
syntax' to make them available to macros.

Modules that provide things for-syntax are the exception rather than  
the rule, except for languages modules like 'scheme', which provide  
everything at phase 0 (normal) and phase 1 (for-syntax). I would  
expect individual bindings provided for-syntax to be marked as such in  
the documentation.

Ryan