Re: Document top-level pseudo-hygiene

[Mark H Weaver <mhw@netris.org>]

Hi Andy,

"Andy Wingo" <wingo@pobox.com> writes:
> commit 03dfed840b377a72191b6f125c106fdfd9e90a21
> Author: Andy Wingo <wingo@pobox.com>
> Date:   Fri Jan 24 12:34:26 2014 +0100
>
>     Document top-level pseudo-hygiene
>     
>     * doc/ref/api-macros.texi (Hygiene and the Top-Level): Add a section
>       documenting our pseudo-hygienic top-level names.

As I've said before, I strenuously object to these novel semantics that
you've invented.  I believe this would be an ugly wart on Guile that we
would have to support indefinitely, in violation of the standards,
because its existence would encourage people to write code that depends
upon it.

> +If introduced top-level identifiers ``escape'' a module, in whatever
> +way, they then form part of the binary interface (ABI) of a module.  It
> +is unacceptable from an engineering point of view to allow the ABI to
> +change randomly.  (It also poses practical problems in meeting the
> +recompilation conditions of the Lesser GPL license, for such modules.)

I understand the problem you are trying to solve.  Please allow me to
make a counter-proposal:

> +For this reason many people prefer to never use identifier-introducing
> +macros at the top-level, instead making those macros receive the names
> +for their introduced identifiers as part of their arguments, or to
> +construct them programmatically and use @code{datum->syntax}.

Yes, this is exactly what we must teach people to do when an introduced
toplevel identifier would cross a module boundary.  It is the only way
to completely solve the ABI problem.

Your proposal not only violates the standards, but also fails to solve
the ABI problem adequately.  The problem is that if a library author
needs to change any of the macro uses in their library, then the
toplevel identifiers introduced by these macro uses will also change,
and thus break the ABI.

To make this more concrete, consider the example you used in the docs:

  (define-syntax-rule (defconst name val)
    (begin
      (define t val)
      (define-syntax-rule (name) t)))

Now suppose that a library contains the following macro use:

  (defconst supported-srfis '(1 4 13 14 16 23 30 39 46))

Your proposed solution means that the library author cannot add to this
list without unintentionally breaking their ABI.  This is a mistake that
an author might easily make, and your proposal not only does nothing to
solve it, but encourages authors to write code that will lead to this
mistake.

In this case, what the library author really needs is for 't' to have a
name derived from 'name', but ignoring 'val'.  Of course, there's no way
for Guile to read the author's mind.  The author must make this decision
explicitly.

Now, to reduce the danger that a library author might unwittingly make
the mistake you're (rightly) worried about, I suggest that we rig the
compiler to issue a warning whenever an introduced toplevel identifier
crosses a module boundary.

What do you think?

      Mark