GH: A Portable C to Scheme Interface
====================================

This chapter shows how to use the GH interface to call Guile from your application's C code, and to add new Scheme level procedures to Guile whose behaviour is specified by application specific code written in C.

Note, however, that the GH interface is now deprecated, and developers are encouraged to switch to using the scm interface instead.  Therefore, for each GH feature, this chapter also documents how to achieve the same result using the scm interface.

Why the GH Interface is Now Deprecated
--------------------------------------

Historically, the GH interface was the product of a practical problem and a neat idea.  The practical problem was that the interface of the scm_ functions with which Guile itself was written (inherited from Aubrey Jaffer's SCM) was so closely tied to the (rather arcane) details of the internal data representation that it was extremely difficult to write a Guile extension using these functions.  The neat idea was to define a high level language extension interface in such a way that other extension language projects, not just Guile, would be able to provide an implementation of that interface; then applications using this interface could be compiled with whichever of the various available implementations they chose.  So the GH interface was created, and advertised both as the recommended interface for application developers wishing to use Guile, and as a portable high level interface that could theoretically be implemented by other extension language projects.

Time passed, and various things changed.  Crucially, an enormous number of improvements were made to the scm_ interface that Guile itself uses in its implementation, with the result that it is now both easy and comfortable to write a Guile extension with this interface.  At the same time, the contents of the GH interface were somewhat neglected by the core Guile developers, such that some key operations --- such as smob creation and management --- are simply not possible using GH alone. Finally, the idea of multiple implementations of the GH interface did not really crystallize (apart, I believe, from a short lived implementation by the MzScheme project).

For all these reasons, the Guile developers have decided to deprecate the GH interface --- which means that support for GH will be completely removed after the next few releases --- and to focus only on the scm_ interface, with additions to ensure that it is as easy to use in all respects as GH was.

It remains an open question whether a deep kind of interface portability would be useful for extension language-based applications, and it may still be an interesting project to attempt to define a corresponding GH-like interface, but the Guile developers no longer plan to try to do this as part of the core Guile project.

Transitioning away from GH
--------------------------

The following table summarizes how to transition from the GH to the scm interface.  The replacements that are recommended are not always completely equivalent to the GH functionality that they should replace.  Therefore, you should read the reference documentation of the replacements carefully if you are not yet familiar with them.

Header file
     Use #include <libguile.h> instead of #include <guile/gh.h>.

Compiling and Linking
     Use guile-config to pick up the flags required to compile C or C++ code that uses libguile, like so

          $(CC) -o prog.o -c prog.c `guile-config compile`

     If you are using libtool to link your executables, just use -lguile in your link command.  Libtool will expand this into the needed linker options automatically.  If you are not using libtool, use the guile-config program to query the needed options explicitly.  A linker command like

          $(CC) -o prog prog.o `guile-config link`

     should be all that is needed.  To link shared libraries that will be used as Guile Extensions, use libtool to control both the compilation and the link stage.

The SCM type
     No change: the scm interface also uses this type to represent an arbitrary Scheme value.

SCM_BOOL_F and SCM_BOOL_T
     No change.

SCM_UNSPECIFIED and SCM_UNDEFINED
     No change.

gh_enter
     Use scm_boot_guile instead, but note that scm_boot_guile has a slightly different calling convention from gh_enter: scm_boot_guile, and the main program function that you specify for scm_boot_guile to call, both take an additional CLOSURE parameter.  Guile Initialization Functions for more details.

gh_repl
     Use scm_shell instead.

gh_init
     Use scm_init_guile instead.

gh_catch
     Use scm_internal_catch instead.

gh_eval_str
     Use scm_c_eval_string instead.

gh_eval_str_with_catch
     Use scm_c_eval_string together with scm_internal_catch instead.

gh_eval_str_with_standard_handler
     Use scm_c_eval_string together with scm_internal_catch and scm_handle_by_message_no_exit instead.

gh_eval_str_with_stack_saving_handler
     Use scm_c_eval_string together with scm_internal_stack_catch and scm_handle_by_message_no_exit instead.

gh_eval_file or gh_load
     Use scm_c_primitive_load instead.

gh_eval_file_with_catch
     Use scm_c_primitive_load together with scm_internal_catch instead.

gh_eval_file_with_standard_handler
     Use scm_c_primitive_load together with scm_internal_catch and scm_handle_by_message_no_exit instead.

gh_new_procedure
gh_new_procedure0_0
gh_new_procedure0_1
gh_new_procedure0_2
gh_new_procedure1_0
gh_new_procedure1_1
gh_new_procedure1_2
gh_new_procedure2_0
gh_new_procedure2_1
gh_new_procedure2_2
gh_new_procedure3_0
gh_new_procedure4_0
gh_new_procedure5_0
     Use scm_c_define_gsubr instead, but note that the arguments are in a different order: for scm_c_define_gsubr the C function pointer is the last argument.  A Sample Guile Extension for an example.

gh_defer_ints and gh_allow_ints
     Use SCM_CRITICAL_SECTION_START and SCM_CRITICAL_SECTION_END instead.  Note that these macros are used without parentheses, as in SCM_DEFER_INTS;.

gh_bool2scm
     Use scm_from_bool instead.

gh_int2scm
     Use scm_from_int instead.

gh_ulong2scm
     Use scm_from_ulong instead.

gh_long2scm
     Use scm_from_long instead.

gh_double2scm
     Use scm_make_real instead.

gh_char2scm
     Use SCM_MAKE_CHAR instead.

gh_str2scm
     Use scm_from_locale_stringn instead.

gh_str02scm
     Use scm_from_locale_string instead.

gh_set_substr
     Use scm_string_copy_x.

gh_symbol2scm
     Use scm_from_locale_symbol instead.

gh_ints2scm
gh_doubles2scm
gh_chars2byvect
gh_shorts2svect
gh_longs2ivect
gh_ulongs2uvect
gh_floats2fvect
gh_doubles2dvect
     Use the uniform numeric vector function, see Uniform Numeric Vectors.

gh_scm2bool
     Use scm_is_true or scm_to_bool instead.

gh_scm2int
     Use scm_to_int instead.

gh_scm2ulong
     Use scm_to_ulong instead.

gh_scm2long
     Use scm_to_long instead.

gh_scm2double
     Use scm_to_double instead.

gh_scm2char
     Use scm_to_char instead.

gh_scm2newstr
     Use scm_to_locale_string or similar instead.

gh_get_substr
     Use scm_c_substring together with scm_to_locale_string or similar instead.

gh_symbol2newstr
     Use scm_symbol_to_string together with scm_to_locale_string or similar instead.

gh_scm2chars
     Use scm_from_locale_string (or similar) or the uniform numeric vector functions (see Uniform Numeric Vectors) instead.

gh_scm2shorts
gh_scm2longs
gh_scm2floats
gh_scm2doubles
     Use the uniform numeric vector function, see Uniform Numeric Vectors.

gh_boolean_p
     Use scm_is_bool instead.

gh_symbol_p
     Use scm_is_symbol instead.

gh_char_p
     Replace gh_char_p (OBJ) with

          scm_is_true (scm_char_p (OBJ))

gh_vector_p
     Replace gh_vector_p (OBJ) with

          scm_is_true (scm_vector_p (OBJ))

gh_pair_p
     Replace gh_pair_p (OBJ) with

          scm_is_true (scm_pair_p (OBJ))

gh_number_p
     Use scm_is_number instead.

gh_string_p
     Use scm_is_string instead.

gh_procedure_p
     Replace gh_procedure_p (OBJ) by

          scm_is_true (scm_procedure_p (OBJ))

gh_list_p
     Replace gh_list_p (OBJ) with

          scm_is_true (scm_list_p (OBJ))

gh_inexact_p
     Replace gh_inexact_p (OBJ) with

          scm_is_true (scm_inexact_p (OBJ))

gh_exact_p
     Replace gh_exact_p (OBJ) with

          scm_is_true (scm_exact_p (OBJ))

gh_eq_p
     Use scm_is_eq instead.

gh_eqv_p
     Replace gh_eqv_p (X, Y) with

          scm_is_true (scm_eqv_p (X, Y))

gh_equal_p
     Replace gh_equal_p (X, Y) with

          scm_is_true (scm_equal_p (X, Y))

gh_string_equal_p
     Replace gh_string_equal_p (X, Y) with

          scm_is_true (scm_string_equal_p (X, Y))

gh_null_p
     Use scm_is_null instead.

gh_not
     Use scm_not instead.

gh_make_string
     Use scm_make_string instead.

gh_string_length
     Use scm_string_length instead.

gh_string_ref
     Use scm_string_ref instead.

gh_string_set_x
     Use scm_string_set_x instead.

gh_substring
     Use scm_substring instead.

gh_string_append
     Use scm_string_append instead.

gh_cons
     Use scm_cons instead.

gh_car and gh_cdr
     Use scm_car and scm_cdr instead.

gh_cxxr and gh_cxxxr
     (Where each x is either a or d.)  Use the corresponding scm_cxxr or scm_cxxxr function instead.

gh_set_car_x and gh_set_cdr_x
     Use scm_set_car_x and scm_set_cdr_x instead.

gh_list
     Use scm_list_n instead.

gh_length
     Replace gh_length (LST) with

          scm_to_size_t (scm_length (LST))

gh_append
     Use scm_append instead.

gh_append2, gh_append3, gh_append4
     Replace gh_appendN (L1, ..., LN) by

          scm_append (scm_list_n (L1, ..., LN, SCM_UNDEFINED))

gh_reverse
     Use scm_reverse instead.

gh_list_tail and gh_list_ref
     Use scm_list_tail and scm_list_ref instead.

gh_memq, gh_memv and gh_member
     Use scm_memq, scm_memv and scm_member instead.

gh_assq, gh_assv and gh_assoc
     Use scm_assq, scm_assv and scm_assoc instead.

gh_make_vector
     Use scm_make_vector instead.

gh_vector or gh_list_to_vector
     Use scm_vector instead.

gh_vector_ref and gh_vector_set_x
     Use scm_vector_ref and scm_vector_set_x instead.

gh_vector_length
     Use scm_c_vector_length instead.

gh_uniform_vector_length
     Use scm_c_uniform_vector_length instead.

gh_uniform_vector_ref
     Use scm_c_uniform_vector_ref instead.

gh_vector_to_list
     Use scm_vector_to_list instead.

gh_apply
     Use scm_apply_0 instead.

gh_call0
gh_call1
gh_call2
gh_call3
     Use scm_call_0, scm_call_1, etc instead.

gh_display
gh_write
gh_newline
     Use scm_display (obj, scm_current_output_port ()) instead, etc.

gh_lookup
     Use scm_variable_ref (scm_c_lookup (name)) instead.

gh_module_lookup
     Use scm_variable_ref (scm_c_module_lookup (module, name)) instead.

GH preliminaries
----------------

To use gh, you must have the following toward the beginning of your C source:

     #include <guile/gh.h>

When you link, you will have to add at least -lguile to the list of libraries.  If you are using more of Guile than the basic Scheme interpreter, you will have to add more libraries.

Data types and constants defined by GH
--------------------------------------

The following C constants and data types are defined in gh:

SCM is a C data type used to store all Scheme data, no matter what the Scheme type.  Values are converted between C data types and the SCM type with utility functions described below (see Converting data between C and Scheme).  [FIXME: put in references to Jim's essay and so forth.]

 -- Constant: SCM_BOOL_T
 -- Constant: SCM_BOOL_F
     The Scheme values returned by many boolean procedures in libguile.

     This can cause confusion because they are different from 0 and 1.  In testing a boolean function in libguile programming, you must always make sure that you check the spec: gh_ and scm_ functions will usually return SCM_BOOL_T and SCM_BOOL_F, but other C functions usually can be tested against 0 and 1, so programmers' fingers tend to just type if (boolean_function()) { ... }

 -- Constant: SCM_UNSPECIFIED
     This is a SCM value that is not the same as any legal Scheme value.  It is the value that a Scheme function returns when its specification says that its return value is unspecified.

 -- Constant: SCM_UNDEFINED
     This is another SCM value that is not the same as any legal Scheme value.  It is the value used to mark variables that do not yet have a value, and it is also used in C to terminate functions with variable numbers of arguments, such as gh_list().

Starting and controlling the interpreter
----------------------------------------

In almost every case, your first gh_ call will be:

 -- Function: void gh_enter (int ARGC, char *ARGV[], void (*MAIN_PROG)())
     Starts up a Scheme interpreter with all the builtin Scheme primitives. gh_enter() never exits, and the user's code should all be in the MAIN_PROG() function.  argc and argv will be passed to MAIN_PROG.

      -- Function: void main_prog (int ARGC, char *ARGV[])
          This is the user's main program.  It will be invoked by gh_enter() after Guile has been started up.

     Note that you can use gh_repl inside gh_enter (in other words, inside the code for main-prog) if you want the program to be controlled by a Scheme read-eval-print loop.

A convenience routine which enters the Guile interpreter with the standard Guile read-eval-print loop (REPL) is:

 -- Function: void gh_repl (int ARGC, char *ARGV[])
     Enters the Scheme interpreter giving control to the Scheme REPL. Arguments are processed as if the Guile program guile were being invoked.

     Note that gh_repl should be used inside gh_enter, since any Guile interpreter calls are meaningless unless they happen in the context of the interpreter.

     Also note that when you use gh_repl, your program will be controlled by Guile's REPL (which is written in Scheme and has many useful features).  Use straight C code inside gh_enter if you want to maintain execution control in your C program.

You will typically use gh_enter and gh_repl when you want a Guile interpreter enhanced by your own libraries, but otherwise quite normal.  For example, to build a Guile--derived program that includes some random number routines GSL (GNU Scientific Library), you would write a C program that looks like this:

     #include <guile/gh.h>
     #include <gsl_ran.h>

     /* random number suite */
     SCM gw_ran_seed(SCM s)
     {
       gsl_ran_seed(gh_scm2int(s));
       return SCM_UNSPECIFIED;
     }

     SCM gw_ran_random()
     {
       SCM x;

       x = gh_ulong2scm(gsl_ran_random());
       return x;
     }

     SCM gw_ran_uniform()
     {
       SCM x;

       x = gh_double2scm(gsl_ran_uniform());
       return x;
     }
     SCM gw_ran_max()
     {
       return gh_double2scm(gsl_ran_max());
     }

     void
     init_gsl()
     {
       /* random number suite */
       gh_new_procedure("gsl-ran-seed", gw_ran_seed, 1, 0, 0);
       gh_new_procedure("gsl-ran-random", gw_ran_random, 0, 0, 0);
       gh_new_procedure("gsl-ran-uniform", gw_ran_uniform, 0, 0, 0);
       gh_new_procedure("gsl-ran-max", gw_ran_max, 0, 0, 0);
     }

     void
     main_prog (int argc, char *argv[])
     {
       init_gsl();

       gh_repl(argc, argv);
     }

     int
     main (int argc, char *argv[])
     {
       gh_enter (argc, argv, main_prog);
     }

Then, supposing the C program is in guile-gsl.c, you could compile it with gcc -o guile-gsl guile-gsl.c -lguile -lgsl.

The resulting program guile-gsl would have new primitive procedures gsl-ran-random, gsl-ran-gaussian and so forth.

Error messages
--------------

[FIXME: need to fill this based on Jim's new mechanism]

Executing Scheme code
---------------------

Once you have an interpreter running, you can ask it to evaluate Scheme code.  There are two calls that implement this:

 -- Function: SCM gh_eval_str (char *SCHEME_CODE)
     This asks the interpreter to evaluate a single string of Scheme code, and returns the result of the last expression evaluated.

     Note that the line of code in SCHEME_CODE must be a well formed Scheme expression.  If you have many lines of code before you balance parentheses, you must either concatenate them into one string, or use gh_eval_file().

 -- Function: SCM gh_eval_file (char *FNAME)
 -- Function: SCM gh_load (char *FNAME)
     gh_eval_file is completely analogous to gh_eval_str(), except that a whole file is evaluated instead of a string. gh_eval_file returns SCM_UNSPECIFIED.

     gh_load is identical to gh_eval_file (it's a macro that calls gh_eval_file on its argument).  It is provided to start making the gh_ interface match the R5RS Scheme procedures closely.

Defining new Scheme procedures in C
-----------------------------------

The real interface between C and Scheme comes when you can write new Scheme procedures in C.  This is done through the routine

 -- Libguile high: SCM gh_new_procedure (char *PROC_NAME, SCM (*FN)(), int N_REQUIRED_ARGS, int N_OPTIONAL_ARGS, int RESTP)
     gh_new_procedure defines a new Scheme procedure.  Its Scheme name will be PROC_NAME, it will be implemented by the C function (*FN)(), it will take at least N_REQUIRED_ARGS arguments, and at most N_OPTIONAL_ARGS extra arguments.

     When the RESTP parameter is 1, the procedure takes a final argument: a list of remaining parameters.

     gh_new_procedure returns an SCM value representing the procedure.

     The C function FN should have the form
      -- Libguile high: SCM fn (SCM REQ1, SCM REQ2, ..., SCM OPT1, SCM OPT2, ..., SCM REST_ARGS)
          The arguments are all passed as SCM values, so the user will have to use the conversion functions to convert to standard C types.

          Examples of C functions used as new Scheme primitives can be found in the sample programs learn0 and learn1.

Rationale: this is the correct way to define new Scheme procedures in C.  The ugly mess of arguments is required because of how C handles procedures with variable numbers of arguments.

NB: what about documentation strings?

There are several important considerations to be made when writing the C routine (*fn)().

First of all the C routine has to return type SCM.

Second, all arguments passed to the C function will be of type SCM.

Third: the C routine is now subject to Scheme flow control, which means that it could be interrupted at any point, and then reentered.  This means that you have to be very careful with operations such as allocating memory, modifying static data ...

Fourth: to get around the latter issue, you can use GH_DEFER_INTS and GH_ALLOW_INTS.

 -- Macro: GH_DEFER_INTS
 -- Macro: GH_ALLOW_INTS
     These macros disable and re-enable Scheme's flow control.  They

Converting data between C and Scheme
------------------------------------

Guile provides mechanisms to convert data between C and Scheme.  This allows new builtin procedures to understand their arguments (which are of type SCM) and return values of type SCM.

C to Scheme
...........

 -- Function: SCM gh_bool2scm (int X)
     Returns #f if X is zero, #t otherwise.

 -- Function: SCM gh_ulong2scm (unsigned long X)
 -- Function: SCM gh_long2scm (long X)
 -- Function: SCM gh_double2scm (double X)
 -- Function: SCM gh_char2scm (char X)
     Returns a Scheme object with the value of the C quantity X.

 -- Function: SCM gh_str2scm (char *S, int LEN)
     Returns a new Scheme string with the (not necessarily null-terminated) C array S data.

 -- Function: SCM gh_str02scm (char *S)
     Returns a new Scheme string with the null-terminated C string S data.

 -- Function: SCM gh_set_substr (char *SRC, SCM DST, int START, int LEN)
     Copy LEN characters at SRC into the existing Scheme string DST, starting at START.  START is an index into DST; zero means the beginning of the string.

     If START + LEN is off the end of DST, signal an out-of-range error.

 -- Function: SCM gh_symbol2scm (char *NAME)
     Given a null-terminated string NAME, return the symbol with that name.

 -- Function: SCM gh_ints2scm (int *DPTR, int N)
 -- Function: SCM gh_doubles2scm (double *DPTR, int N)
     Make a scheme vector containing the N ints or doubles at memory location DPTR.

 -- Function: SCM gh_chars2byvect (char *DPTR, int N)
 -- Function: SCM gh_shorts2svect (short *DPTR, int N)
 -- Function: SCM gh_longs2ivect (long *DPTR, int N)
 -- Function: SCM gh_ulongs2uvect (ulong *DPTR, int N)
 -- Function: SCM gh_floats2fvect (float *DPTR, int N)
 -- Function: SCM gh_doubles2dvect (double *DPTR, int N)
     Make a scheme uniform vector containing the N chars, shorts, longs, unsigned longs, floats or doubles at memory location DPTR.

Scheme to C
...........

 -- Function: int gh_scm2bool (SCM OBJ)
 -- Function: unsigned long gh_scm2ulong (SCM OBJ)
 -- Function: long gh_scm2long (SCM OBJ)
 -- Function: double gh_scm2double (SCM OBJ)
 -- Function: int gh_scm2char (SCM OBJ)
     These routines convert the Scheme object to the given C type.

 -- Function: char * gh_scm2newstr (SCM STR, size_t *LENP)
     Given a Scheme string STR, return a pointer to a new copy of its contents, followed by a null byte.  If LENP is non-null, set *LENP to the string's length.

     This function uses malloc to obtain storage for the copy; the caller is responsible for freeing it.

     Note that Scheme strings may contain arbitrary data, including null characters.  This means that null termination is not a reliable way to determine the length of the returned value.  However, the function always copies the complete contents of STR, and sets *LENP to the true length of the string (when LENP is non-null).

 -- Function: void gh_get_substr (SCM str, char *return_str, int *lenp)
     Copy LEN characters at START from the Scheme string SRC to memory at DST.  START is an index into SRC; zero means the beginning of the string.  DST has already been allocated by the caller.

     If START + LEN is off the end of SRC, signal an out-of-range error.

 -- Function: char * gh_symbol2newstr (SCM SYM, int *LENP)
     Takes a Scheme symbol and returns a string of the form "'symbol-name".  If LENP is non-null, the string's length is returned in *LENP.

     This function uses malloc to obtain storage for the returned string; the caller is responsible for freeing it.

 -- Function: char * gh_scm2chars (SCM VECTOR, chars *RESULT)
 -- Function: short * gh_scm2shorts (SCM VECTOR, short *RESULT)
 -- Function: long * gh_scm2longs (SCM VECTOR, long *RESULT)
 -- Function: float * gh_scm2floats (SCM VECTOR, float *RESULT)
 -- Function: double * gh_scm2doubles (SCM VECTOR, double *RESULT)
     Copy the numbers in VECTOR to the array pointed to by RESULT and return it.  If RESULT is NULL, allocate a double array large enough.

     VECTOR can be an ordinary vector, a weak vector, or a signed or unsigned uniform vector of the same type as the result array.  For chars, VECTOR can be a string or substring.  For floats and doubles, VECTOR can contain a mix of inexact and integer values.

     If VECTOR is of unsigned type and contains values too large to fit in the signed destination array, those values will be wrapped around, that is, data will be copied as if the destination array was unsigned.

Type predicates
---------------

These C functions mirror Scheme's type predicate procedures with one important difference.  The C routines return C boolean values (0 and 1) instead of SCM_BOOL_T and SCM_BOOL_F.

The Scheme notational convention of putting a ? at the end of predicate procedure names is mirrored in C by placing _p at the end of the procedure.  For example, (pair? ...) maps to gh_pair_p(...).

 -- Function: int gh_boolean_p (SCM VAL)
     Returns 1 if VAL is a boolean, 0 otherwise.

 -- Function: int gh_symbol_p (SCM VAL)
     Returns 1 if VAL is a symbol, 0 otherwise.

 -- Function: int gh_char_p (SCM VAL)
     Returns 1 if VAL is a char, 0 otherwise.

 -- Function: int gh_vector_p (SCM VAL)
     Returns 1 if VAL is a vector, 0 otherwise.

 -- Function: int gh_pair_p (SCM VAL)
     Returns 1 if VAL is a pair, 0 otherwise.

 -- Function: int gh_procedure_p (SCM VAL)
     Returns 1 if VAL is a procedure, 0 otherwise.

 -- Function: int gh_list_p (SCM VAL)
     Returns 1 if VAL is a list, 0 otherwise.

 -- Function: int gh_inexact_p (SCM VAL)
     Returns 1 if VAL is an inexact number, 0 otherwise.

 -- Function: int gh_exact_p (SCM VAL)
     Returns 1 if VAL is an exact number, 0 otherwise.

Equality predicates
-------------------

These C functions mirror Scheme's equality predicate procedures with one important difference.  The C routines return C boolean values (0 and 1) instead of SCM_BOOL_T and SCM_BOOL_F.

The Scheme notational convention of putting a ? at the end of predicate procedure names is mirrored in C by placing _p at the end of the procedure.  For example, (equal? ...) maps to gh_equal_p(...).

 -- Function: int gh_eq_p (SCM x, SCM y)
     Returns 1 if X and Y are equal in the sense of Scheme's eq? predicate, 0 otherwise.

 -- Function: int gh_eqv_p (SCM x, SCM y)
     Returns 1 if X and Y are equal in the sense of Scheme's eqv? predicate, 0 otherwise.

 -- Function: int gh_equal_p (SCM x, SCM y)
     Returns 1 if X and Y are equal in the sense of Scheme's equal? predicate, 0 otherwise.

 -- Function: int gh_string_equal_p (SCM S1, SCM S2)
     Returns 1 if the strings S1 and S2 are equal, 0 otherwise.

 -- Function: int gh_null_p (SCM L)
     Returns 1 if L is an empty list or pair; 0 otherwise.

Memory allocation and garbage collection
----------------------------------------

Calling Scheme procedures from C
--------------------------------

Many of the Scheme primitives are available in the gh_ interface; they take and return objects of type SCM, and one could basically use them to write C code that mimics Scheme code.

I will list these routines here without much explanation, since what they do is the same as documented in R5RS.  But I will point out that when a procedure takes a variable number of arguments (such as gh_list), you should pass the constant SCM_UNDEFINED from C to signify the end of the list.

 -- Function: SCM gh_define (char *NAME, SCM VAL)
     Corresponds to the Scheme (define name val): it binds a value to the given name (which is a C string).  Returns the new object.

Pairs and lists
===============

 -- Function: SCM gh_cons (SCM A, SCM B)
 -- Function: SCM gh_list (SCM l0, SCM l1, ... , SCM_UNDEFINED)
     These correspond to the Scheme (cons a b) and (list l0 l1 ...) procedures.  Note that gh_list() is a C macro that invokes scm_list_n().

 -- Function: SCM gh_car (SCM OBJ)
 -- Function: SCM gh_cdr (SCM OBJ)
     ...

 -- Function: SCM gh_c[ad][ad][ad][ad]r (SCM OBJ)
     These correspond to the Scheme (caadar ls) procedures etc ...

 -- Function: SCM gh_set_car_x (SCM PAIR, SCM VALUE)
     Modifies the CAR of PAIR to be VALUE.  This is equivalent to the Scheme procedure (set-car! ...).

 -- Function: SCM gh_set_cdr_x (SCM PAIR, SCM VALUE)
     Modifies the CDR of PAIR to be VALUE.  This is equivalent to the Scheme procedure (set-cdr! ...).

 -- Function: unsigned long gh_length (SCM LS)
     Returns the length of the list.

 -- Function: SCM gh_append (SCM ARGS)
 -- Function: SCM gh_append2 (SCM L1, SCM L2)
 -- Function: SCM gh_append3 (SCM L1, SCM L2, L3)
 -- Function: SCM gh_append4 (SCM L1, SCM L2, L3, L4)
     gh_append() takes ARGS, which is a list of lists (list1 list2 ...), and returns a list containing all the elements of the individual lists.

     A typical invocation of gh_append() to append 5 lists together would be

            gh_append(gh_list(l1, l2, l3, l4, l5, SCM_UNDEFINED));

     The functions gh_append2(), gh_append2(), gh_append3() and gh_append4() are convenience routines to make it easier for C programs to form the list of lists that goes as an argument to gh_append().

 -- Function: SCM gh_reverse (SCM LS)
     Returns a new list that has the same elements as LS but in the reverse order.  Note that this is implemented as a macro which calls scm_reverse().

 -- Function: SCM gh_list_tail (SCM LS, SCM K)
     Returns the sublist of LS with the last K elements.

 -- Function: SCM gh_list_ref (SCM LS, SCM K)
     Returns the Kth element of the list LS.

 -- Function: SCM gh_memq (SCM X, SCM LS)
 -- Function: SCM gh_memv (SCM X, SCM LS)
 -- Function: SCM gh_member (SCM X, SCM LS)
     These functions return the first sublist of LS whose CAR is X.  They correspond to (memq x ls), (memv x ls) and (member x ls), and hence use (respectively) eq?, eqv? and equal? to do comparisons.

     If X does not appear in LS, the value SCM_BOOL_F (not the empty list) is returned.

     Note that these functions are implemented as macros which call scm_memq(), scm_memv() and scm_member() respectively.

 -- Function: SCM gh_assq (SCM X, SCM ALIST)
 -- Function: SCM gh_assv (SCM X, SCM ALIST)
 -- Function: SCM gh_assoc (SCM X, SCM ALIST)
     These functions search an association list (list of pairs) ALIST for the first pair whose CAR is X, and they return that pair.

     If no pair in ALIST has X as its CAR, the value SCM_BOOL_F (not the empty list) is returned.

     Note that these functions are implemented as macros which call scm_assq(), scm_assv() and scm_assoc() respectively.

Symbols
=======

Vectors
=======

 -- Function: SCM gh_make_vector (SCM N, SCM FILL)
 -- Function: SCM gh_vector (SCM LS)
 -- Function: SCM gh_vector_ref (SCM V, SCM I)
 -- Function: SCM gh_vector_set (SCM V, SCM I, SCM VAL)
 -- Function: unsigned long gh_vector_length (SCM V)
 -- Function: SCM gh_list_to_vector (SCM LS)
     These correspond to the Scheme (make-vector n fill), (vector a b c ...) (vector-ref v i) (vector-set v i value) (vector-length v) (list->vector ls) procedures.

     The correspondence is not perfect for gh_vector: this routine takes a list LS instead of the individual list elements, thus making it identical to gh_list_to_vector.

     There is also a difference in gh_vector_length: the value returned is a C unsigned long instead of an SCM object.

Procedures
==========

 -- Function: SCM gh_apply (SCM proc, SCM args)
     Call the Scheme procedure PROC, with the elements of ARGS as arguments.  ARGS must be a proper list.

 -- Function: SCM gh_call0 (SCM proc)
 -- Function: SCM gh_call1 (SCM proc, SCM arg)
 -- Function: SCM gh_call2 (SCM proc, SCM arg1, SCM arg2)
 -- Function: SCM gh_call3 (SCM proc, SCM arg1, SCM arg2, SCM arg3)
     Call the Scheme procedure PROC with no arguments (gh_call0), one argument (gh_call1), and so on.  You can get the same effect by wrapping the arguments up into a list, and calling gh_apply; Guile provides these functions for convenience.

 -- Function: SCM gh_catch (SCM key, SCM thunk, SCM handler)
 -- Function: SCM gh_throw (SCM key, SCM args)
     Corresponds to the Scheme catch and throw procedures, which in Guile are provided as primitives.

 -- Function: SCM gh_is_eq (SCM a, SCM b)
 -- Function: SCM gh_is_eqv (SCM a, SCM b)
 -- Function: SCM gh_is_equal (SCM a, SCM b)
     These correspond to the Scheme eq?, eqv? and equal? predicates.

 -- Function: int gh_obj_length (SCM OBJ)
     Returns the raw object length.

Data lookup
===========

For now I just include Tim Pierce's comments from the gh_data.c file; it should be organized into a documentation of the two functions here.

     /* Data lookups between C and Scheme

        Look up a symbol with a given name, and return the object to which
        it is bound.  gh_lookup examines the Guile top level, and
        gh_module_lookup checks the module name space specified by the
        `vec' argument.

        The return value is the Scheme object to which SNAME is bound, or
        SCM_UNDEFINED if SNAME is not bound in the given context. [FIXME:
        should this be SCM_UNSPECIFIED?  Can a symbol ever legitimately be
        bound to SCM_UNDEFINED or SCM_UNSPECIFIED?  What is the difference?
        -twp] */