Re: (PR11207) Macroprocessor discussion -- current safe-to-implement proposal

[Serguei Makarov <smakarov at redhat dot com>]

This is the proposal I intend to implement in the next little
while (unless anyone has any last-second comments or objections).
It is designed to do about 80% of what we ideally want the
macroprocessor to do; the other 20% requires a fairly powerful engine,
which could conceivably be developed later and adapted to use the same
syntax as the current proposal.

Basics
- Token based preprocessor is housed in parse.cxx.
- The parser filters its input through the preprocessor before analysing it.
- Docstrings cannot be manipulated or generated with macros; any
  functionality for this is delayed until a later point. (We will
  either develop a separate text-based mechanism, some kind of
  super-general-uber-engine, or just procrastinate on the issue
  forever.)

Definition Syntax
- one-line macro definition @define foo(...) ...body...
- multiline macro definition @define foo(...) %( ...body... %)
  - %( %) brackets inside the body (e.g. for stap conditionals) must balance
- optional, for later: heredoc-type macros @define foo(...) <<HERE
  - macro body then continues until we find a line that says 'HERE'
    (or whatever we put, e.g. 'END')

Invocation Syntax
- @macro_name(param,param,...).
  - ( ) brackets inside the parameters must balance, so we can pass in
    complex expressions such as @foo(function(a,b,c)) and have it do
    the right thing.
- Unknown macros are passed to the parser without being expanded or
  causing an error. This enables us to continue using constructs such
  as @cast(...) transparently -- they are simply ignored.

Cross-Tapset Inclusion of Macros
- Deferred until later (macro definitions will start out local to one
  file), but promising options include:
  - Create a file, say, tapset/foo.stpm or tapset/macros/foo.stpm,
    which defines a macro 'foo' (must be same name as the file) that
    we want to be available globally.
  - Create a file, say, tapset/common.stpm. The preprocessor uses the
    macro definitions from this file in *every* other file it parses.
  - Wait for the special-rainbows-and-unicorns statically scoped
    engine to solve the problem for us.