diff --git a/devel/policy/names.text b/devel/policy/names.text index 1c6bbc2f3..e69de29bb 100644 --- a/devel/policy/names.text +++ b/devel/policy/names.text @@ -1,127 +0,0 @@ -[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 :-)