Snarfing Macros
===============

The following macros do two different things: when compiled normally, they expand in one way; when processed during snarfing, they cause the guile-snarf program to pick up some initialization code, see Function Snarfing.

The descriptions below use the term `normally' to refer to the case when the code is compiled normally, and `while snarfing' when the code is processed by guile-snarf.

 -- C Macro: SCM_SNARF_INIT (code)

     Normally, SCM_SNARF_INIT expands to nothing; while snarfing, it causes CODE to be included in the initialization action file, followed by a semicolon.

     This is the fundamental macro for snarfing initialization actions. The more specialized macros below use it internally.

 -- C Macro: SCM_DEFINE (c_name, scheme_name, req, opt, var, arglist, docstring)

     Normally, this macro expands into

          static const char s_C_NAME[] = SCHEME_NAME;
          SCM
          C_NAME ARGLIST

     While snarfing, it causes

          scm_c_define_gsubr (s_C_NAME, REQ, OPT, VAR,
                              C_NAME);

     to be added to the initialization actions.  Thus, you can use it to declare a C function named C_NAME that will be made available to Scheme with the name SCHEME_NAME.

     Note that the ARGLIST argument must have parentheses around it.

 -- C Macro: SCM_SYMBOL (c_name, scheme_name)
 -- C Macro: SCM_GLOBAL_SYMBOL (c_name, scheme_name)
     Normally, these macros expand into

          static SCM C_NAME

     or

          SCM C_NAME

     respectively.  While snarfing, they both expand into the initialization code

          C_NAME = scm_permanent_object (scm_from_locale_symbol (SCHEME_NAME));

     Thus, you can use them declare a static or global variable of type SCM that will be initialized to the symbol named SCHEME_NAME.

 -- C Macro: SCM_KEYWORD (c_name, scheme_name)
 -- C Macro: SCM_GLOBAL_KEYWORD (c_name, scheme_name)
     Normally, these macros expand into

          static SCM C_NAME

     or

          SCM C_NAME

     respectively.  While snarfing, they both expand into the initialization code

          C_NAME = scm_permanent_object (scm_c_make_keyword (SCHEME_NAME));

     Thus, you can use them declare a static or global variable of type SCM that will be initialized to the keyword named SCHEME_NAME.

 -- C Macro: SCM_VARIABLE (c_name, scheme_name)
 -- C Macro: SCM_GLOBAL_VARIABLE (c_name, scheme_name)
     These macros are equivalent to SCM_VARIABLE_INIT and SCM_GLOBAL_VARIABLE_INIT, respectively, with a VALUE of SCM_BOOL_F.

 -- C Macro: SCM_VARIABLE_INIT (c_name, scheme_name, value)
 -- C Macro: SCM_GLOBAL_VARIABLE_INIT (c_name, scheme_name, value)

     Normally, these macros expand into

          static SCM C_NAME

     or

          SCM C_NAME

     respectively.  While snarfing, they both expand into the initialization code

          C_NAME = scm_permanent_object (scm_c_define (SCHEME_NAME, VALUE));

     Thus, you can use them declare a static or global C variable of type SCM that will be initialized to the object representing the Scheme variable named SCHEME_NAME in the current module.  The variable will be defined when it doesn't already exist.  It is always set to VALUE.