Re: Suggestion: new snarf macro set

[Keisuke Nishida <kxn30 at po dot cwru dot edu>]

Dirk Herrmann <dirk@ida.ing.tu-bs.de> writes:

> > Okay, this is my third suggestion of the new snarf macro set:
> 
> I think it's pretty advanced.  But, we should really wait until some 
> major changes have been applied, as Mikael suggested.  Nevertheless, I
> believe that the concept that you have developed will still be applicable
> without a lot of changes, so we can probably use most of it even after the
> changes that Mikael talked of.

Okay, so I can add SCM_DEFINE_CLASS, too :)  That's great.

Anyway, this is a rough draft of the new snarf macros:

------------------------------------------------------------------------
Snarf Macros						-*- outline -*-
Updated: 2000-05-25

* Concept

A snarf macro defines a Scheme object, providing a convenient way to
do so, and concealing internal details.  Instead of using low level
functions like

  static const char *s_scm_foo = "foo";
  scm_make_subr (s_scm_foo, scm_tc7_rpsubr, scm_foo);

one can use a single snarf macro:

  SCM_DEFINE_RELATION (scm_foo, "foo", ...)

* Policy

** Naming

Low level macros have a prefix `SCM_SNARF_'.

User level macros have a prefix `SCM_DEFINE_'.

User level macros that define C variables have a prefix `SCM_DEFINE_C_'.

Those macros that define static versions have an infix `STATIC_'.

Internal macros have a prefix `SCM_I_'.

** Organization

One macro for each concept.  We should provide SCM_DEFINE_HOOK and
SCM_DEFINE_FLUID as well as SCM_DEFINE_PROCEDURE.  A snarf macro should
conceal internal details as much as possible.  Instead of SCM_PROC1,
we should provide SCM_DEFINE_RELATION, SCM_DEFINE_ACCUMULATION, etc.

However, we don't need to provide SCM_DEFINE_INTEGER because it's too
specific.  Instead, we provide a general macro SCM_DEFINE_VARIABLE.

** Docstring

All `SCM_DEFINE_' macros should define docstrings.
`SCM_DEFINE_C_' macros do not necessarily define docstrings.

* Low level macros

SCM_SNARF_DECL - Define the declaration part of a snarf macro.
SCM_SNARF_INIT - Define the initialization part of a snarf macro.
SCM_SNARF_DOCS - Define the docstring part of a snarf macro.
SCM_SNARF_CAST - Cast a C function.

** Snarf macro definition

A snarf macro is defined like this:

  #define SCM_SET(NAME, VALUE, DOCS)      \
    SCM_SNARF_DECL(int NAME)              \
    SCM_SNARF_INIT(NAME = VALUE;)         \
    SCM_SNARF_DOCS("integer", NAME, DOCS)

This macro declares a C variable NAME, initializes it by VALUE, and
associates a docstring DOCS with it.  This macro can be used as follows:

  SCM_SET (foo, 1, "The default value is 1.");

** SCM_SNARF_DECL
** SCM_SNARF_INIT
** SCM_SNARF_DOCS
** SCM_SNARF_CAST

[ should be documented later ]

* User level macros

These macros define Scheme procedures with docstrings:

SCM_DEFINE_PROCEDURE            -> scm_make_gsubr
SCM_DEFINE_PROCEDURE_ALIAS      -> scm_make_gsubr (no function body)
SCM_DEFINE_RELATION             -> scm_make_subr w/ scm_tc7_rpsubr
SCM_DEFINE_ACCUMULATION         -> scm_make_subr w/ scm_tc7_asubr
SCM_DEFINE_GENERIC_PROCEDURE    -> scm_make_gsubr_with_generic
SCM_DEFINE_GENERIC_RELATION     -> scm_make_subr_with_generic w/ scm_tc7_rpsubr
SCM_DEFINE_GENERIC_ACCUMULATION -> scm_make_subr_with_generic w/ scm_tc7_asubr
SCM_DEFINE_GENERIC_ARITHMETIC   -> scm_make_subr_with_generic w/ scm_tc7_cxr

These macros define Scheme macros with docstrings:

SCM_DEFINE_SYNTAX               -> scm_make_synt w/ scm_makacro
SCM_DEFINE_MACRO                -> scm_make_synt w/ scm_makmacro
SCM_DEFINE_MEMOIZING_MACRO      -> scm_make_synt w/ scm_makmmacro

These macros define Scheme variables of general/specific type with docstrings:

SCM_DEFINE_VARIABLE             -> scm_intern0
SCM_DEFINE_HOOK                 -> scm_create_hook
SCM_DEFINE_FLUID                -> scm_make_fluid + @

[ do we need STATIC_ version? ]

These macros merely create Scheme objects (without docstrings):

SCM_DEFINE_SYMBOL               -> SCM_CAR (scm_intern0 (...))
SCM_DEFINE_STATIC_SYMBOL
SCM_DEFINE_KEYWORD              -> SCM_CAR (scm_c_make_keyword (...))
SCM_DEFINE_STATIC_KEYWORD

[ these could be SCM_DEFINE_C_* ? ]

These macros define C level Scheme objects (without docstrings):

SCM_DEFINE_C_VARIABLE
SCM_DEFINE_C_STATIC_VARIABLE
SCM_DEFINE_C_HOOK
SCM_DEFINE_C_STATIC_HOOK

* TODO

** Macros for GOOPS objects

SCM_DEFINE_CLASS
SCM_DEFINE_SLOT_*
SCM_DEFINE_GENERIC
SCM_DEFINE_METHOD
...

** Docstrings for C functions/macros

Macro style or comment style?

** Macros for cross references

** Macros for manual organization (which section? etc.)