Re: gh_ vs. scm_ Interfaces

[Neil Jerram]

>>>>> "Martin" == Martin Grabmueller <address@hidden> writes:

    Martin> Hello all, when trying to integrate Guile into a program
    Martin> recently, I came across the problem of the different Guile
    Martin> APIs once again.  I was trying to stick to the gh_
    Martin> interface, but as you may well know, I didn't come far.
    Martin> Is there any policy for/against one of the APIs yet?

Good question.  And I am particularly interested in the answer at the
moment because of my work on the Guile reference manual.

    Martin> I just checked that both APIs are covered by the draft
    Martin> reference manual, which states:
    [...]

    Martin> I don't get the difference between _programming with_ and
    Martin> _extending_.  What doe these paragraphs mean?

I think that the text is aiming at a distinction between
straightforward "programming" and more advanced "extension", where,
for example,

- programming could be writing a simple set of new primitives and
  registering them with Guile using gh_new_procedure, so that the
  procedures can be used from a Scheme program

- extension could be a new feature - such as C support for
  non-rational real numbers - that requires closer integration with
  the rest of libguile.

Plus there is the suggestion that the gh interface is likely to be
more stable.

But in practice the distinction is not so clear cut, and the true
definitions are probably circular: programming is whatever you can do
with the gh interface, and extension is everything else!  In which
case, best simply to document them as the "simple" and "advanced"
interfaces, and let people use them as they will.

Another consideration ISTR is the idea that the gh interface could be
implemented by a completely different interpreter than Guile, and that
therefore, if you wrote an extension using only the gh interface, you
could plug in any interpreter that implemented the gh interface.
Realistically, I very much doubt that this will ever happen, so I
think that we should drop this angle.

    Martin> It would be very convenient to have access to all those
    Martin> wonderful SCM_VALIDATE_* macros when writing procedures in
    Martin> C, for example, but they are not available via
    Martin> <guile/gh.h>, so I think using them is dicouraged.

Good point.  This is one of the reasons why I use the scm interface
for my extensions.

In summary, I think we have two options.

Option 1 is to drop the attempted distinction between the gh and scm
interfaces, and only retain the gh interface for backwards
compatibility.

Option 2 is to keep the distinction between the two interfaces.  But
this means that we must (i) better define what that distinction is,
and (ii) make the gh interface complete enough to be useful.  Amongst
other things, (ii) needs to take into account, and perhaps provide
equivalents for, the usefulness of macros like SCM_VALIDATE_*, and
other conveniences of the scm interface such as its snarfing support
(SCM_DEFINE etc.).

Regards,
        Neil