mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-05-13 17:20:21 +02:00
127 lines
4.5 KiB
Text
127 lines
4.5 KiB
Text
[This is currently a collection of information in an unedited state.
|
|
Someone will change this soon.]
|
|
|
|
The C names for Scheme primitives *always* obey a fixed name
|
|
translation scheme:
|
|
|
|
scm_XXX where XXX is translated from the Scheme name, except that
|
|
|
|
- becomes _
|
|
! becomes _x
|
|
? becomes _p
|
|
% becomes sys_
|
|
|
|
If there's a C variant of something provided at the Scheme level (like
|
|
the current scm_internal_dynamic_wind), it has the prefix scm_c_
|
|
instead of scm_.
|
|
|
|
A function named scm_c_FOO serves the same purpose as the function
|
|
named scm_FOO, except that its interface is tailored for use from C,
|
|
while scm_FOO is tailored for use from Scheme, and is probably
|
|
exported as a Scheme primitive.
|
|
|
|
For example, scm_FOO might expect Scheme procedures as arguments,
|
|
while scm_c_FOO might take C function pointers and a passthrough
|
|
value.
|
|
|
|
|
|
If there's a C function with global scope which is only intended to be
|
|
used internally in libguile, it has the prefix scm_i_.
|
|
|
|
String literals with global scope has the prefix scm_s_. (Greg
|
|
introduced the prefix s_scm_ but this has to change to scm_s_ since
|
|
s_scm_ trespasses the user's namespace.)
|
|
|
|
Not correct: Those names have module-local scope and does not trespass
|
|
user name space.
|
|
|
|
Keywords with global scope has the prefix scm_k_.
|
|
|
|
Symbols with global scope has the prefix scm_sym_.
|
|
|
|
Variable bindings with global scope has the prefix scm_var_.
|
|
|
|
Names, in general, have an internal left-to-right order of increasing
|
|
specificity: scm_ is least specific. It is often followed by some
|
|
type, like `stack', and, finally, the operation. Example:
|
|
scm_stack_length.
|
|
|
|
There are exceptions, though:
|
|
|
|
* If a name is already established at the Scheme level, this defines
|
|
the C name through the translation scheme.
|
|
|
|
* According to the rule, we should have `SCM_SMOB_DATA_SET', but we
|
|
instead have `SCM_SET_SMOB_DATA'. Generally, `set' should be placed
|
|
as far left as possible:
|
|
|
|
`port-filename' scm_port_filename
|
|
`set-port-filename!' scm_set_port_filename_x
|
|
|
|
SCM_SMOB_DATA
|
|
SCM_SET_SMOB_DATA
|
|
|
|
* Guile has a lot of history with lots of different strange names.
|
|
Perhaps a major name overhaul can be done at the same time as we go
|
|
through Guile's interfaces to checks soundness and theoretical
|
|
properties such as type safety. We *should* be a bit careful with
|
|
name changes in order not to break existing application code.
|
|
|
|
> Further, I'd love it if macros to create scheme values from C values would
|
|
> be named SCM_MAKE_... more consitently. Currently, we have SCM_MAKICHAR
|
|
> (OK, this one's been made deprecated), SCM_MAKINUM and others.
|
|
|
|
I agree.
|
|
|
|
> Also, some macros are used for symbols or keywords. The best solution
|
|
> would be to use a similar naming scheme for these also.
|
|
>
|
|
> It's good to talk about improving guile's API. A clean, consistent and
|
|
> beautiful api is, in my belief, important for guile's attractivity, and
|
|
> makes learning it easier.
|
|
|
|
Yes!
|
|
|
|
There are still some open points:
|
|
|
|
scm_c_XXX :
|
|
Only used for C-level variants of a scm_XXX schene primitive, or
|
|
rather to be used for everything that is not a scheme primitive?
|
|
|
|
scm_i_XXX :
|
|
Only for internal _functions_ or rather for everything that is
|
|
internal? For example, scm_sym_ is for symbols that may be used by
|
|
users, while scm_i_sym_ is used for guile internally? Otherwise we
|
|
can't distinguish between C variables holding symbols that are part of
|
|
the official API and internally used C variables holding symbols.
|
|
|
|
what about boolean variables/constants? scm_bool_? This would fit nicely
|
|
with the current macro names SCM_BOOL_T and SCM_BOOL_F.
|
|
|
|
what about number variables/constants? scm_num_? There is at least a
|
|
SCM_MAKINUM(0) somewhere...
|
|
|
|
scm_s_, scm_k_, scm_sym_, scm_var_:
|
|
What about macro variants of these? At least, some symbols and
|
|
constants are represented as macros.
|
|
|
|
Macros in general:
|
|
Should internally used macros be called SCM_I_xxx, thus following the
|
|
above scheme?
|
|
|
|
How do scheme-level names translate if there are macros that do the
|
|
same thing? set-car! --> SCM_SETCAR, thus, the '!' is dropped and the
|
|
intermediate '-' is dropped. However, this is not done
|
|
consistently: sometimes intermediate '-' are _not_ dropped.
|
|
|
|
Currently it seem that:
|
|
|
|
- becomes sometimes _ and sometimes nothing
|
|
! becomes nothing
|
|
? becomes P for single-word xxx, _P otherwise
|
|
% becomes I don't know what.
|
|
|
|
|
|
I would prefer if both worlds (functions/variables and macros) were using
|
|
similar schemes as far as possible. (I even dislike the _P/P
|
|
distinction, but I know that I am strange :-)
|