== Glossary of variable names

=== se

Syntactic environment; an alist mapping variable names to aliases.
Generally used when referring to the macro's ''static'' syntactic environment,
also known as its "definition environment".

 ((var . alias) (var . alias) ...)

An {{alias}} may either be a symbol or a pair, where a pair indicates a macro.

=== dse

Same as an [[#se]], but specifically used when referring to a macro's
dynamic syntactic environment, also known as its "use environment".

== macro api

<parameter>macro-environment</parameter>

Alist mapping macro names to their syntactic environments and macro handlers.

 ( (name . (se handler)) ...)

<procedure>(extend-macro-environment name se handler)</procedure>

Associates [[#se]] and {{handler}} with {{name}} in {{##sys#macro-environment}},
overwriting the association if it exists.

<procedure>(copy-macro old new)</procedure>

Copy macro [[#se]] and handler from {{old}} name to {{new}} name in {{#sys#macro-environment}}.  Unused in core.

<procedure>(macro? sym #!optional (senv ##sys#current-environment))</procedure>

True if macro {{sym}} can be found in either {{senv}} or in
{{##sys#macro-environment}}.

<procedure>(extend-se se vars #!optional aliases)</procedure>

Extend syntactic environment [[#se]] by mapping {{vars}} to
corresponding {{aliases}}, or to gensyms if {{aliases}} is not provided.
Returns the new [[#se]].

Reverse mappings from aliases to vars ("real names") are implicitly
recorded in a global, to be used when stripping syntax.

<procedure>(strip-syntax exp)</procedure>

Recursively walk pairs and vectors in {{exp}} and strip all
syntactical information from symbols, returning an expression with
identical structure but all context information removed.  Circular
references are allowed and will be walked only once.

Consults {{##core#macro-alias}}, {{##core#real-name}} and
{{#core#primitive}} to map aliases back to variable names.

<procedure>(macro-alias var se)</procedure>

(''Not exported.'')  Returns a new {{alias}} (gensym) for symbol
{{var}} in syntactic environment [[#se]].

Records a global mapping from {{alias}} to {{var}} (its "real name")
in {{#core#real-name}}, which is used when stripping syntax.

Records a global mapping from {{alias}} to {{var}}'s
existing alias in [[#se]], writing it into {{##core#macro-alias}}.  If {{var}}
has no alias, just associate alias with {{var}} instead.  (FIXME:
explain why, not just what.)

Qualified symbols (like ##sys#bar) and previously renamed module
symbols (like foo#bar) are not aliased, just returned.

<procedure>(expand-0 exp dse cs?)</procedure>

Expand expression {{exp}} once in dynamic syntactic environment
[[#dse]], by looking up the head identifier in [[#dse]] or 
{{##sys#macro-environment}}, then executing the macro
handler.

Returns two values: the (possibly) expanded expression, and a boolean
indicating whether expansion was performed.  ({{exp}} may not be recognized
as a macro, in which case the original expression is returned.)

{{cs?}} is a boolean indicating whether it is permitted to treat the
expression as compiler syntax (i.e., look it up first in
{{##compiler#compiler-syntax}}).  Compiler syntax is expanded
repeatedly until it is not recognized as compiler syntax any longer.
If the hook {{##sys#compiler-syntax-hook}} is set, it is called every
time expansion is successful; its value is discarded.

(Implementation note: expansion of named let is performed here.)

<procedure>(expand exp #!optional (se (##sys#current-environment)) cs?)</procedure>

Macroexpand expression {{exp}} repeatedly using {{##sys#expand-0}} in the
(dynamic) syntactic environment [[#se]] until it cannot be expanded
any further.

{{cs?}} indicates whether to accept compiler syntax; see {{##sys#expand-0}}.

<procedure>(compiler-syntax-hook name result)</procedure>

Hook called after a successful iteration of compiler-syntax expansion
in {{##sys#expand-0}}.  This is only defined when compiling; otherwise
it is #f.  Currently, the default implementation just tracks the number
of expansions for each macro.

<procedure>(module-rename sym prefix)</procedure>

 (##sys#module-rename 'chortle 'foo)
  ;=> 'foo#chortle

<procedure>(alias-global-hook sym assign where)</procedure>

?