GNU Info

(guile.info)Calling Scheme procedures from C

---

Next: Mixing gh and scm APIs Prev: Memory allocation and garbage collection Up: Top

---

Enter node , (file) or (file)node

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 Note: R4RS.
  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_EOL 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_listify()'.

 - Function: SCM gh_set_car (SCM OBJ, SCM VAL)
 - Function: SCM gh_set_cdr (SCM OBJ, SCM VAL)
     These correspond to the Scheme `(set-car! ...)' and `(set-cdr!
     ...)' procedures.

 - 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
     taks 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 namespace 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] */