[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 entity (function, variable or typedef) with global scope which is only intended to be used internally in libguile, it has the prefix scm_i_. String literals with global scope have 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 do not trespass user name space. Keywords with global scope have the prefix scm_k_. Symbols with global scope have 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 check 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. [cmm] I agree, and I changed the relevant text above. the prefix construction rule should probably be: scm[_i]_[type]_[rest] 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? [cmm] I like this. in fact, it's already used in some places. 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 :-)