6.5 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.