Node:Calling Scheme procedures from C, Next:, Previous:Memory allocation and garbage collection, Up:GH


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

SCM gh_define (char *name, SCM val) Function
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

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

SCM gh_car (SCM obj) Function
SCM gh_cdr (SCM obj) Function
...
SCM gh_c[ad][ad][ad][ad]r (SCM obj) Function
These correspond to the Scheme (caadar ls) procedures etc ...

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

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

unsigned long gh_length (SCM ls) Function
Returns the length of the list.

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) Function
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().

SCM gh_reverse (SCM ls) Function
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().

SCM gh_list_tail (SCM ls, SCM k) Function
Returns the sublist of ls with the last k elements.

SCM gh_list_ref (SCM ls, SCM k) Function
Returns the kth element of the list ls.

SCM gh_memq (SCM x, SCM ls) Function
SCM gh_memv (SCM x, SCM ls) Function
SCM gh_member (SCM x, SCM ls) Function
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.

SCM gh_assq (SCM x, SCM alist) Function
SCM gh_assv (SCM x, SCM alist) Function
SCM gh_assoc (SCM x, SCM alist) Function
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

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) Function
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

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

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) Function
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.

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

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) Function
These correspond to the Scheme eq?, eqv? and equal? predicates.

int gh_obj_length (SCM obj) Function
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] */