Re: interface reductions

[Dirk Herrmann <dirk at ida dot ing dot tu-bs dot de>]

On 24 May 2000, Mikael Djurfeldt wrote:

> All scm_tc16_* codes should be declared in *.h files.  A lot of the
> scm_tc16_ codes need to be accessible across compilation units.  It is
> better to be consistent than to have to make things public when
> needed.
> 
> Similarly, as many Guile data types as possible should have type
> predicates declared in header files so that applications and Guile C
> modules can use them.
> 
> Therefore, the following declarations should be kept:
> 
> > filesys.h: 
> >   scm_tc16_dir
> >   SCM_DIRP
> > 
> > fluids.h:
> >   scm_tc16_fluid
> >   SCM_FLUIDP
> > 
> > hooks.h:
> >   scm_tc16_hook
> >   SCM_HOOKP
> > 
> > keywords.h:
> >   scm_tc16_keyword
> >   SCM_KEYWORDP

Hmmm... I would have understood your arguments if you would have argued
the other way around, like 'We should provide predicates in header files, 
and these predicates need the scm_tc16_* codes'.  As you put it, it seems
that it is OK for external applications to explicitly use the scm_tc16_*
codes.  This, however, is not a good idea, IMO, since the fact that a type
is a smob should be hidden.  Otherwise, once such a type is implemented in
a different way, using goops for example, all external code has to be
changed.

However, it's probably OK to keep the predicates, and as a consequence,
the scm_tc16_* codes, but I would strongly recommend to deprecate the
explicit use of the scm_tc16_* codes by user code.

> Furthermore, we need to keep in mind that the scm_ interface has two
> roles: 1. implementing Guile, 2. being an interface for applications
> and Guile C modules.  On these grounds, the following macros should be
> kept:
> 
> > fluids.h:
> >   SCM_FLUID_NUM
> >   SCM_FAST_FLUID_REF
> >   SCM_FAST_FLUID_SET_X

These macros rely heavily on the way fluids are implemented, i. e. the
fact that they are kept in a vector and thus have a numeric index.  While
I am not against providing an as-fast-as-possible interface, I question
this if it couples user code closely to an implementation detail.

> > hooks.h:
> >   SCM_HOOK_ARITY
> >   SCM_HOOK_PROCEDURES
> >   SCM_SET_HOOK_PROCEDURES

OK.  Goes along with Bill Schottstaedt's reply.

> >   SCM_HOOK_NAME

This is not actually related to the question of whether this macro
should be deprecated, but:  Does it make sense to have objects with
names?  If we think of a name being an essential part of a hook, then it
is OK to provide functions for accessing it.  But, I don't think that
hooks should have a name.  Otherwise, you could give names to any kind of
scheme object, like cells with names :-)

> > validate.h:
> >   SCM_VALIDATE_NUMBER_COPY
> >   SCM_VALIDATE_BIGINT
> 
> SCM_VALIDATE_NUMBER_COPY was added April 17...  It was added because
> it was needed in an application.  It seems reasonable to support
> validating a numeric argument, don't you think?

Have you looked at SCM_VALIDATE_NUMBER_COPY?  It converts a numeric
argument to a double value.  It's nothing that the name tells you
about.  It does not work with complex values.  The fact that an
application uses it doesn't make it better.  Maybe that application should
have provided it's own special purpose macro, but the way
SCM_VALIDATE_NUMBER_COPY works is broken IMO.  Nothing against a
SCM_VALIDATE_NUMBER, though, or maybe even a SCM_VALIDATE_REAL_COPY.

> Also, the following macros should probably be kept, but maybe under
> better names:
> 
> > filesys.h: 
> >   SCM_OPDIRP
> > 
> > fports.h:
> >   SCM_OPINFPORTP
> >   SCM_OPOUTFPORTP

OK.

> > keywords.h:
> >   SCM_KEYWORDSYM

Again, coupling to the implementation detail that keywords are implemented
as symbols.  I have to admit, though, that I don't have any idea what
keywords are good for anyway, so maybe I should shut up here :-)  (If
anybody could enlighten me about the use of keywords and their advantages 
compared to ordinary symbols, I would be thankful.)

> > numbers.h:
> >   SCM_MAXEXP
> >   SCM_DIGSTOOBIG
> >   SCM_DIGSPERLONG
> >   SCM_BIGUP
> >   SCM_LONGLONGBIGUP
> >   SCM_BIGDN
> >   SCM_BIGLO
> >   SCM_BIGSIGNFLAG
> >   SCM_BIGSIGN
> >   SCM_SETNUMDIGS
> 
> (I didn't look at the details of the BIGNUM macros.  Since we're going
>  to replace the bignums with libgmp, most of these will be irrelevant,
>  but there's no reason why we should remove them now.)

I'm not suggesting to _remove_ these, but rather to allow developers to
detect uses of these by enabling SCM_DEBUG_DEPRECATED.  Since bignums are
to be replaced, we should deprecate these macros ASAP.

That's, btw, what I actually suggested for all those macros:  Not to
_remove_ them now, but deprecate them, at least for external
use.  However, as you see I follow your argument for a number of these
macros, but there are still a lot for which you did not convince me
(yet?).

Best regards
Dirk