-[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 :-)
HCoop / bpt / guile.git / commitdiff