Previous: Memory allocation and garbage collection, Up: GH

5.22.13 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] */