API naming bugs

API naming bugs

[Andy Wingo]

Hi,

A few potential API bugs.

1) functions that take C types normally are named scm_c_*. There are a
few exceptions though:
 - scm_from_locale_symbol[n] -- here's a confusing name, perhaps
scm_c_symbol_from_locale_string is more apt -- but this function will be
used frequently, so there is an advantage to keeping it short; perhaps
scm_c_symbol_from_locale or scm_c_symbol_from_lstring or
scm_c_symbol_from_lchars?
 - scm_frame_begin, unwind_handler, etc -- should change because there
is also a SCM-based scm_frame interface

2) NEWS talks about SCM_FRAME_WIND_EXPLICITELY, but code is (correctly)
EXPLICITLY

Regards,
-- 
Andy Wingo
http://wingolog.org/



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: API naming bugs

[Marius Vollmer]

Andy Wingo <wingo@pobox.com> writes:

> 1) functions that take C types normally are named scm_c_*. There are a
> few exceptions though:

The rule is that scm_c_foo is mostly the same as scm_foo, only with a
different calling convention that is easier for C.  For example, we
have scm_vector_length and scm_c_vector_length.  The former is exactly
'vector-length' and returns the length as a SCM value, while the
latter returns the length as a size_t.

Functions named scm_to_foo and scm_from_foo are concerned with
converting the representation of a value between the SCM and foo
types.  The names are a bit hackish since the scm_ prefix is actually
part of the meaning: "SCM to foo".

The viewpoint of this set of functions is that on one side everything
is represented as SCM and we don't need to say what sub-type of SCM is
actually required or produced.  For example, it simply is scm_to_int,
not scm_number_to_int or scm_exact_integer_to_int or even
scm_exact_integer_that_fits_into_int_to_int ;-).

>  - scm_from_locale_symbol[n] -- here's a confusing name, perhaps
> scm_c_symbol_from_locale_string is more apt

I agree that this is not totally self-describing since there is no
'symbol' type in C.  We silently make the assumption that C-side
symbols would be nul-terminated arrays of characters, just like
strings.

>  - scm_frame_begin, unwind_handler, etc -- should change because there
> is also a SCM-based scm_frame interface

Yeah, that's unfortunate.  we have two things that are termed a
"frame": he things dealt with by scm_frame_begin, etc, and the frames
of a captured stack.  When designing the scm_frame_begin stuff, I
didn't think about those "other" frames, and when I finally noticed
that there is a terminology overlap, ... I refused to think too much
about it since I wanted to use the nice name for my stuff as
well... Hmm.  Ideally, I think the captured stack frames should be
called "stack frames".

Opinions?

> 2) NEWS talks about SCM_FRAME_WIND_EXPLICITELY, but code is (correctly)
> EXPLICITLY

Yep, that's my permanent spelling mistake.  Sometimes I think it is
easier to change the English orthography than to fix my typos.
Thanks!

-- 
GPG: D5D4E405 - 2F9B BCCC 8527 692A 04E3  331E FAF8 226A D5D4 E405


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: API naming bugs

[Neil Jerram]

Marius Vollmer <mvo@zagadka.de> writes:

> Andy Wingo <wingo@pobox.com> writes:
>
>>  - scm_frame_begin, unwind_handler, etc -- should change because there
>> is also a SCM-based scm_frame interface
>
> Yeah, that's unfortunate.  we have two things that are termed a
> "frame": he things dealt with by scm_frame_begin, etc, and the frames
> of a captured stack.  When designing the scm_frame_begin stuff, I
> didn't think about those "other" frames, and when I finally noticed
> that there is a terminology overlap, ... I refused to think too much
> about it since I wanted to use the nice name for my stuff as
> well... Hmm.  Ideally, I think the captured stack frames should be
> called "stack frames".
>
> Opinions?

Ideally, yes, but I think there is already a body of code using the
existing frame- names.  (At least, I know I have such code in
guile-debugging, and I think others do too, because of the occasional
discussions about getting debugging information out of a stack.)

How about renaming the internal scm_frame functions instead, since
AFAIK they haven't been released yet?  Perhaps scm_context_..., or
scm_dynwind_..., or scm_dc_...?

Regards,
        Neil



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: API naming bugs

[Marius Vollmer]

Neil Jerram <neil@ossau.uklinux.net> writes:

> How about renaming the internal scm_frame functions instead, since
> AFAIK they haven't been released yet?

Yep, I'll do that.

> Perhaps scm_context_..., or scm_dynwind_..., or scm_dc_...?

I'm going with scm_dynwind_ since the functions are directly related
to 'dynwind'.

-- 
GPG: D5D4E405 - 2F9B BCCC 8527 692A 04E3  331E FAF8 226A D5D4 E405


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel