(guile.info.gz) Calling Scheme procedures from C
Info Catalog
(guile.info.gz) Memory allocation and garbage collection
(guile.info.gz) GH
(guile.info.gz) Mixing gh and scm APIs
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 (r5rs)Standard
procedures. 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_listify()'.
-- 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] */
Info Catalog
(guile.info.gz) Memory allocation and garbage collection
(guile.info.gz) GH
(guile.info.gz) Mixing gh and scm APIs
automatically generated byinfo2html