3 @chapter GH: A Portable C to Scheme Interface
6 @cindex gh - reference manual
8 This chapter shows how to use the GH interface to call Guile from your
9 application's C code, and to add new Scheme level procedures to Guile
10 whose behaviour is specified by application specific code written in C.
12 Note, however, that the GH interface is now deprecated, and developers
13 are encouraged to switch to using the scm interface instead. Therefore,
14 for each GH feature, this chapter should also document how to achieve
15 the same result using the scm interface.
18 * GH deprecation:: Why the GH interface is now deprecated.
20 * Data types and constants defined by gh::
21 * Starting and controlling the interpreter::
23 * Executing Scheme code::
24 * Defining new Scheme procedures in C::
25 * Converting data between C and Scheme::
27 * Equality predicates::
28 * Memory allocation and garbage collection::
29 * Calling Scheme procedures from C::
30 * Mixing gh and scm APIs::
31 * scm transition summary::
36 @section Why the GH Interface is Now Deprecated
38 Historically, the GH interface was the product of a practical problem
39 and a neat idea. The practical problem was that the interface of the
40 @code{scm_} functions with which Guile itself was written (inherited
41 from Aubrey Jaffer's SCM) was so closely tied to the (rather arcane)
42 details of the internal data representation that it was extremely
43 difficult to write a Guile extension using these functions. The neat
44 idea was to define a high level language extension interface in such a
45 way that other extension language projects, not just Guile, would be
46 able to provide an implementation of that interface; then applications
47 using this interface could be compiled with whichever of the various
48 available implementations they chose. So the GH interface was created,
49 and advertised both as the recommended interface for application
50 developers wishing to use Guile, and as a portable high level interface
51 that could theoretically be implemented by other extension language
54 Time passed, and various things changed. Crucially, an enormous number
55 of improvements were made to the @code{scm_} interface that Guile itself
56 uses in its implementation, with the result that it is now both easy and
57 comfortable to write a Guile extension with this interface. At the same
58 time, the contents of the GH interface were somewhat neglected by the
59 core Guile developers, such that some key operations --- such as smob
60 creation and management --- are simply not possible using GH alone.
61 Finally, the idea of multiple implementations of the GH interface did
62 not really crystallize (apart, I believe, from a short lived
63 implementation by the MzScheme project).
65 For all these reasons, the Guile developers have decided to deprecate
66 the GH interface --- which means that support for GH will be completely
67 removed after the next few releases --- and to focus only on the
68 @code{scm_} interface, with additions to ensure that it is as easy to
69 use in all respects as GH was.
71 It remains an open question whether a deep kind of interface portability
72 would be useful for extension language-based applications, and it may
73 still be an interesting project to attempt to define a corresponding
74 GH-like interface, but the Guile developers no longer plan to try to do
75 this as part of the core Guile project.
78 @node gh preliminaries
79 @section gh preliminaries
81 To use gh, you must have the following toward the beginning of your C
88 When you link, you will have to add at least @code{-lguile} to the list
89 of libraries. If you are using more of Guile than the basic Scheme
90 interpreter, you will have to add more libraries.
94 @node Data types and constants defined by gh
95 @section Data types and constants defined by gh
96 @cindex libguile - data types
98 The following C constants and data types are defined in gh:
100 @code{SCM} is a C data type used to store all Scheme data, no matter what the
101 Scheme type. Values are converted between C data types and the SCM type
102 with utility functions described below (@pxref{Converting data between C
103 and Scheme}). [FIXME: put in references to Jim's essay and so forth.]
105 @defvr Constant SCM_BOOL_T
106 @defvrx Constant SCM_BOOL_F
107 The @emph{Scheme} values returned by many boolean procedures in
110 This can cause confusion because they are different from 0 and 1. In
111 testing a boolean function in libguile programming, you must always make
112 sure that you check the spec: @code{gh_} and @code{scm_} functions will
113 usually return @code{SCM_BOOL_T} and @code{SCM_BOOL_F}, but other C
114 functions usually can be tested against 0 and 1, so programmers' fingers
115 tend to just type @code{if (boolean_function()) @{ ... @}}
118 @defvr Constant SCM_UNSPECIFIED
119 This is a SCM value that is not the same as any legal Scheme value. It
120 is the value that a Scheme function returns when its specification says
121 that its return value is unspecified.
124 @defvr Constant SCM_UNDEFINED
125 This is another SCM value that is not the same as any legal Scheme
126 value. It is the value used to mark variables that do not yet have a
127 value, and it is also used in C to terminate functions with variable
128 numbers of arguments, such as @code{gh_list()}.
132 @node Starting and controlling the interpreter
133 @section Starting and controlling the interpreter
134 @cindex libguile - start interpreter
136 In almost every case, your first @code{gh_} call will be:
138 @deftypefun void gh_enter (int @var{argc}, char *@var{argv}[], void (*@var{main_prog})())
139 Starts up a Scheme interpreter with all the builtin Scheme primitives.
140 @code{gh_enter()} never exits, and the user's code should all be in the
141 @code{@var{main_prog}()} function. @code{argc} and @code{argv} will be
142 passed to @var{main_prog}.
144 @deftypefun void main_prog (int @var{argc}, char *@var{argv}[])
145 This is the user's main program. It will be invoked by
146 @code{gh_enter()} after Guile has been started up.
149 Note that you can use @code{gh_repl} inside @code{gh_enter} (in other
150 words, inside the code for @code{main-prog}) if you want the program to
151 be controlled by a Scheme read-eval-print loop.
154 @cindex read eval print loop -- from the gh_ interface
155 @cindex REPL -- from the gh_ interface
156 A convenience routine which enters the Guile interpreter with the
157 standard Guile read-eval-print loop (@dfn{REPL}) is:
159 @deftypefun void gh_repl (int @var{argc}, char *@var{argv}[])
160 Enters the Scheme interpreter giving control to the Scheme REPL.
161 Arguments are processed as if the Guile program @file{guile} were being
164 Note that @code{gh_repl} should be used @emph{inside} @code{gh_enter},
165 since any Guile interpreter calls are meaningless unless they happen in
166 the context of the interpreter.
168 Also note that when you use @code{gh_repl}, your program will be
169 controlled by Guile's REPL (which is written in Scheme and has many
170 useful features). Use straight C code inside @code{gh_enter} if you
171 want to maintain execution control in your C program.
174 You will typically use @code{gh_enter} and @code{gh_repl} when you
175 want a Guile interpreter enhanced by your own libraries, but otherwise
176 quite normal. For example, to build a Guile--derived program that
177 includes some random number routines @dfn{GSL} (GNU Scientific Library),
178 you would write a C program that looks like this:
181 #include <guile/gh.h>
184 /* random number suite */
185 SCM gw_ran_seed(SCM s)
187 gsl_ran_seed(gh_scm2int(s));
188 return SCM_UNSPECIFIED;
195 x = gh_ulong2scm(gsl_ran_random());
203 x = gh_double2scm(gsl_ran_uniform());
208 return gh_double2scm(gsl_ran_max());
214 /* random number suite */
215 gh_new_procedure("gsl-ran-seed", gw_ran_seed, 1, 0, 0);
216 gh_new_procedure("gsl-ran-random", gw_ran_random, 0, 0, 0);
217 gh_new_procedure("gsl-ran-uniform", gw_ran_uniform, 0, 0, 0);
218 gh_new_procedure("gsl-ran-max", gw_ran_max, 0, 0, 0);
222 main_prog (int argc, char *argv[])
230 main (int argc, char *argv[])
232 gh_enter (argc, argv, main_prog);
236 Then, supposing the C program is in @file{guile-gsl.c}, you could
237 compile it with @kbd{gcc -o guile-gsl guile-gsl.c -lguile -lgsl}.
239 The resulting program @file{guile-gsl} would have new primitive
240 procedures @code{gsl-ran-random}, @code{gsl-ran-gaussian} and so forth.
244 @section Error messages
245 @cindex libguile - error messages
246 @cindex error messages in libguile
248 [FIXME: need to fill this based on Jim's new mechanism]
251 @node Executing Scheme code
252 @section Executing Scheme code
253 @cindex libguile - executing Scheme
254 @cindex executing Scheme
256 Once you have an interpreter running, you can ask it to evaluate Scheme
257 code. There are two calls that implement this:
259 @deftypefun SCM gh_eval_str (char *@var{scheme_code})
260 This asks the interpreter to evaluate a single string of Scheme code,
261 and returns the result of the last expression evaluated.
263 Note that the line of code in @var{scheme_code} must be a well formed
264 Scheme expression. If you have many lines of code before you balance
265 parentheses, you must either concatenate them into one string, or use
266 @code{gh_eval_file()}.
269 @deftypefun SCM gh_eval_file (char *@var{fname})
270 @deftypefunx SCM gh_load (char *@var{fname})
271 @code{gh_eval_file} is completely analogous to @code{gh_eval_str()},
272 except that a whole file is evaluated instead of a string.
273 @code{gh_eval_file} returns @code{SCM_UNSPECIFIED}.
275 @code{gh_load} is identical to @code{gh_eval_file} (it's a macro that
276 calls @code{gh_eval_file} on its argument). It is provided to start
277 making the @code{gh_} interface match the R5RS Scheme procedures
282 @node Defining new Scheme procedures in C
283 @section Defining new Scheme procedures in C
284 @cindex libguile - new procedures
285 @cindex new procedures
286 @cindex procedures, new
287 @cindex new primitives
288 @cindex primitives, new
290 The real interface between C and Scheme comes when you can write new
291 Scheme procedures in C. This is done through the routine
294 @deftypefn {Libguile high} SCM gh_new_procedure (char *@var{proc_name}, SCM (*@var{fn})(), int @var{n_required_args}, int @var{n_optional_args}, int @var{restp})
295 @code{gh_new_procedure} defines a new Scheme procedure. Its Scheme name
296 will be @var{proc_name}, it will be implemented by the C function
297 (*@var{fn})(), it will take at least @var{n_required_args} arguments,
298 and at most @var{n_optional_args} extra arguments.
300 When the @var{restp} parameter is 1, the procedure takes a final
301 argument: a list of remaining parameters.
303 @code{gh_new_procedure} returns an SCM value representing the procedure.
305 The C function @var{fn} should have the form
306 @deftypefn {Libguile high} SCM fn (SCM @var{req1}, SCM @var{req2}, ..., SCM @var{opt1}, SCM @var{opt2}, ..., SCM @var{rest_args})
307 The arguments are all passed as SCM values, so the user will have to use
308 the conversion functions to convert to standard C types.
310 Examples of C functions used as new Scheme primitives can be found in
311 the sample programs @code{learn0} and @code{learn1}.
316 @strong{Rationale:} this is the correct way to define new Scheme
317 procedures in C. The ugly mess of arguments is required because of how
318 C handles procedures with variable numbers of arguments.
320 @strong{Note:} what about documentation strings?
323 There are several important considerations to be made when writing the C
324 routine @code{(*fn)()}.
326 First of all the C routine has to return type @code{SCM}.
328 Second, all arguments passed to the C function will be of type
331 Third: the C routine is now subject to Scheme flow control, which means
332 that it could be interrupted at any point, and then reentered. This
333 means that you have to be very careful with operations such as
334 allocating memory, modifying static data @dots{}
336 Fourth: to get around the latter issue, you can use
337 @code{GH_DEFER_INTS} and @code{GH_ALLOW_INTS}.
340 @defmac GH_DEFER_INTS
341 @defmacx GH_ALLOW_INTS
342 These macros disable and re-enable Scheme's flow control. They
346 @c [??? have to do this right; maybe using subsections, or maybe creating a
347 @c section called Flow control issues...]
349 @c [??? Go into exhaustive detail with examples of the various possible
350 @c combinations of required and optional args...]
353 @node Converting data between C and Scheme
354 @section Converting data between C and Scheme
355 @cindex libguile - converting data
356 @cindex data conversion
357 @cindex converting data
359 Guile provides mechanisms to convert data between C and Scheme. This
360 allows new builtin procedures to understand their arguments (which are
361 of type @code{SCM}) and return values of type @code{SCM}.
370 @subsection C to Scheme
372 @deftypefun SCM gh_bool2scm (int @var{x})
373 Returns @code{#f} if @var{x} is zero, @code{#t} otherwise.
376 @deftypefun SCM gh_ulong2scm (unsigned long @var{x})
377 @deftypefunx SCM gh_long2scm (long @var{x})
378 @deftypefunx SCM gh_double2scm (double @var{x})
379 @deftypefunx SCM gh_char2scm (char @var{x})
380 Returns a Scheme object with the value of the C quantity @var{x}.
383 @deftypefun SCM gh_str2scm (char *@var{s}, int @var{len})
384 Returns a new Scheme string with the (not necessarily null-terminated) C
388 @deftypefun SCM gh_str02scm (char *@var{s})
389 Returns a new Scheme string with the null-terminated C string @var{s}
393 @deftypefun SCM gh_set_substr (char *@var{src}, SCM @var{dst}, int @var{start}, int @var{len})
394 Copy @var{len} characters at @var{src} into the @emph{existing} Scheme
395 string @var{dst}, starting at @var{start}. @var{start} is an index into
396 @var{dst}; zero means the beginning of the string.
398 If @var{start} + @var{len} is off the end of @var{dst}, signal an
402 @deftypefun SCM gh_symbol2scm (char *@var{name})
403 Given a null-terminated string @var{name}, return the symbol with that
407 @deftypefun SCM gh_ints2scm (int *@var{dptr}, int @var{n})
408 @deftypefunx SCM gh_doubles2scm (double *@var{dptr}, int @var{n})
409 Make a scheme vector containing the @var{n} ints or doubles at memory
413 @deftypefun SCM gh_chars2byvect (char *@var{dptr}, int @var{n})
414 @deftypefunx SCM gh_shorts2svect (short *@var{dptr}, int @var{n})
415 @deftypefunx SCM gh_longs2ivect (long *@var{dptr}, int @var{n})
416 @deftypefunx SCM gh_ulongs2uvect (ulong *@var{dptr}, int @var{n})
417 @deftypefunx SCM gh_floats2fvect (float *@var{dptr}, int @var{n})
418 @deftypefunx SCM gh_doubles2dvect (double *@var{dptr}, int @var{n})
419 Make a scheme uniform vector containing the @var{n} chars, shorts,
420 longs, unsigned longs, floats or doubles at memory location @var{dptr}.
426 @subsection Scheme to C
428 @deftypefun int gh_scm2bool (SCM @var{obj})
429 @deftypefunx {unsigned long} gh_scm2ulong (SCM @var{obj})
430 @deftypefunx long gh_scm2long (SCM @var{obj})
431 @deftypefunx double gh_scm2double (SCM @var{obj})
432 @deftypefunx int gh_scm2char (SCM @var{obj})
433 These routines convert the Scheme object to the given C type.
436 @deftypefun char *gh_scm2newstr (SCM @var{str}, int *@var{lenp})
437 Given a Scheme string @var{str}, return a pointer to a new copy of its
438 contents, followed by a null byte. If @var{lenp} is non-null, set
439 @code{*@var{lenp}} to the string's length.
441 This function uses malloc to obtain storage for the copy; the caller is
442 responsible for freeing it.
444 Note that Scheme strings may contain arbitrary data, including null
445 characters. This means that null termination is not a reliable way to
446 determine the length of the returned value. However, the function
447 always copies the complete contents of @var{str}, and sets @var{*lenp}
448 to the true length of the string (when @var{lenp} is non-null).
452 @deftypefun void gh_get_substr (SCM str, char *return_str, int *lenp)
453 Copy @var{len} characters at @var{start} from the Scheme string
454 @var{src} to memory at @var{dst}. @var{start} is an index into
455 @var{src}; zero means the beginning of the string. @var{dst} has
456 already been allocated by the caller.
458 If @var{start} + @var{len} is off the end of @var{src}, signal an
462 @deftypefun char *gh_symbol2newstr (SCM @var{sym}, int *@var{lenp})
463 Takes a Scheme symbol and returns a string of the form
464 @code{"'symbol-name"}. If @var{lenp} is non-null, the string's length
465 is returned in @code{*@var{lenp}}.
467 This function uses malloc to obtain storage for the returned string; the
468 caller is responsible for freeing it.
471 @deftypefun char *gh_scm2chars (SCM @var{vector}, chars *@var{result})
472 @deftypefunx short *gh_scm2shorts (SCM @var{vector}, short *@var{result})
473 @deftypefunx long *gh_scm2longs (SCM @var{vector}, long *@var{result})
474 @deftypefunx float *gh_scm2floats (SCM @var{vector}, float *@var{result})
475 @deftypefunx double *gh_scm2doubles (SCM @var{vector}, double *@var{result})
476 Copy the numbers in @var{vector} to the array pointed to by @var{result}
477 and return it. If @var{result} is NULL, allocate a double array large
480 @var{vector} can be an ordinary vector, a weak vector, or a signed or
481 unsigned uniform vector of the same type as the result array. For
482 chars, @var{vector} can be a string or substring. For floats and
483 doubles, @var{vector} can contain a mix of inexact and integer values.
485 If @var{vector} is of unsigned type and contains values too large to fit
486 in the signed destination array, those values will be wrapped around,
487 that is, data will be copied as if the destination array was unsigned.
491 @node Type predicates
492 @section Type predicates
494 These C functions mirror Scheme's type predicate procedures with one
495 important difference. The C routines return C boolean values (0 and 1)
496 instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}.
498 The Scheme notational convention of putting a @code{?} at the end of
499 predicate procedure names is mirrored in C by placing @code{_p} at the
500 end of the procedure. For example, @code{(pair? ...)} maps to
501 @code{gh_pair_p(...)}.
503 @deftypefun int gh_boolean_p (SCM @var{val})
504 Returns 1 if @var{val} is a boolean, 0 otherwise.
507 @deftypefun int gh_symbol_p (SCM @var{val})
508 Returns 1 if @var{val} is a symbol, 0 otherwise.
511 @deftypefun int gh_char_p (SCM @var{val})
512 Returns 1 if @var{val} is a char, 0 otherwise.
515 @deftypefun int gh_vector_p (SCM @var{val})
516 Returns 1 if @var{val} is a vector, 0 otherwise.
519 @deftypefun int gh_pair_p (SCM @var{val})
520 Returns 1 if @var{val} is a pair, 0 otherwise.
523 @deftypefun int gh_procedure_p (SCM @var{val})
524 Returns 1 if @var{val} is a procedure, 0 otherwise.
527 @deftypefun int gh_list_p (SCM @var{val})
528 Returns 1 if @var{val} is a list, 0 otherwise.
531 @deftypefun int gh_inexact_p (SCM @var{val})
532 Returns 1 if @var{val} is an inexact number, 0 otherwise.
535 @deftypefun int gh_exact_p (SCM @var{val})
536 Returns 1 if @var{val} is an exact number, 0 otherwise.
540 @node Equality predicates
541 @section Equality predicates
543 These C functions mirror Scheme's equality predicate procedures with one
544 important difference. The C routines return C boolean values (0 and 1)
545 instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}.
547 The Scheme notational convention of putting a @code{?} at the end of
548 predicate procedure names is mirrored in C by placing @code{_p} at the
549 end of the procedure. For example, @code{(equal? ...)} maps to
550 @code{gh_equal_p(...)}.
552 @deftypefun int gh_eq_p (SCM x, SCM y)
553 Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
554 @code{eq?} predicate, 0 otherwise.
557 @deftypefun int gh_eqv_p (SCM x, SCM y)
558 Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
559 @code{eqv?} predicate, 0 otherwise.
562 @deftypefun int gh_equal_p (SCM x, SCM y)
563 Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
564 @code{equal?} predicate, 0 otherwise.
567 @deftypefun int gh_string_equal_p (SCM @var{s1}, SCM @var{s2})
568 Returns 1 if the strings @var{s1} and @var{s2} are equal, 0 otherwise.
571 @deftypefun int gh_null_p (SCM @var{l})
572 Returns 1 if @var{l} is an empty list or pair; 0 otherwise.
576 @node Memory allocation and garbage collection
577 @section Memory allocation and garbage collection
579 @c [FIXME: flesh this out with some description of garbage collection in
582 @c @deftypefun SCM gh_mkarray (int size)
583 @c Allocate memory for a Scheme object in a garbage-collector-friendly
588 @node Calling Scheme procedures from C
589 @section Calling Scheme procedures from C
591 Many of the Scheme primitives are available in the @code{gh_}
592 interface; they take and return objects of type SCM, and one could
593 basically use them to write C code that mimics Scheme code.
595 I will list these routines here without much explanation, since what
596 they do is the same as documented in @ref{Standard procedures, R5RS, ,
597 r5rs, R5RS}. But I will point out that when a procedure takes a
598 variable number of arguments (such as @code{gh_list}), you should pass
599 the constant @var{SCM_UNDEFINED} from C to signify the end of the list.
601 @deftypefun SCM gh_define (char *@var{name}, SCM @var{val})
602 Corresponds to the Scheme @code{(define name val)}: it binds a value to
603 the given name (which is a C string). Returns the new object.
606 @heading Pairs and lists
608 @deftypefun SCM gh_cons (SCM @var{a}, SCM @var{b})
609 @deftypefunx SCM gh_list (SCM l0, SCM l1, ... , SCM_UNDEFINED)
610 These correspond to the Scheme @code{(cons a b)} and @code{(list l0 l1
611 ...)} procedures. Note that @code{gh_list()} is a C macro that invokes
612 @code{scm_listify()}.
615 @deftypefun SCM gh_car (SCM @var{obj})
616 @deftypefunx SCM gh_cdr (SCM @var{obj})
619 @deftypefunx SCM gh_c[ad][ad][ad][ad]r (SCM @var{obj})
620 These correspond to the Scheme @code{(caadar ls)} procedures etc @dots{}
623 @deftypefun SCM gh_set_car_x(SCM @var{pair}, SCM @var{value})
624 Modifies the CAR of @var{pair} to be @var{value}. This is equivalent to
625 the Scheme procedure @code{(set-car! ...)}.
628 @deftypefun SCM gh_set_cdr_x(SCM @var{pair}, SCM @var{value})
629 Modifies the CDR of @var{pair} to be @var{value}. This is equivalent to
630 the Scheme procedure @code{(set-cdr! ...)}.
633 @deftypefun {unsigned long} gh_length (SCM @var{ls})
634 Returns the length of the list.
637 @deftypefun SCM gh_append (SCM @var{args})
638 @deftypefunx SCM gh_append2 (SCM @var{l1}, SCM @var{l2})
639 @deftypefunx SCM gh_append3 (SCM @var{l1}, SCM @var{l2}, @var{l3})
640 @deftypefunx SCM gh_append4 (SCM @var{l1}, SCM @var{l2}, @var{l3}, @var{l4})
641 @code{gh_append()} takes @var{args}, which is a list of lists
642 @code{(list1 list2 ...)}, and returns a list containing all the elements
643 of the individual lists.
645 A typical invocation of @code{gh_append()} to append 5 lists together
648 gh_append(gh_list(l1, l2, l3, l4, l5, SCM_UNDEFINED));
651 The functions @code{gh_append2()}, @code{gh_append2()},
652 @code{gh_append3()} and @code{gh_append4()} are convenience routines to
653 make it easier for C programs to form the list of lists that goes as an
654 argument to @code{gh_append()}.
657 @deftypefun SCM gh_reverse (SCM @var{ls})
658 Returns a new list that has the same elements as @var{ls} but in the
659 reverse order. Note that this is implemented as a macro which calls
660 @code{scm_reverse()}.
663 @deftypefun SCM gh_list_tail (SCM @var{ls}, SCM @var{k})
664 Returns the sublist of @var{ls} with the last @var{k} elements.
667 @deftypefun SCM gh_list_ref (SCM @var{ls}, SCM @var{k})
668 Returns the @var{k}th element of the list @var{ls}.
671 @deftypefun SCM gh_memq (SCM @var{x}, SCM @var{ls})
672 @deftypefunx SCM gh_memv (SCM @var{x}, SCM @var{ls})
673 @deftypefunx SCM gh_member (SCM @var{x}, SCM @var{ls})
674 These functions return the first sublist of @var{ls} whose CAR is
675 @var{x}. They correspond to @code{(memq x ls)}, @code{(memv x ls)} and
676 @code{(member x ls)}, and hence use (respectively) @code{eq?},
677 @code{eqv?} and @code{equal?} to do comparisons.
679 If @var{x} does not appear in @var{ls}, the value @code{SCM_BOOL_F} (not
680 the empty list) is returned.
682 Note that these functions are implemented as macros which call
683 @code{scm_memq()}, @code{scm_memv()} and @code{scm_member()}
687 @deftypefun SCM gh_assq (SCM @var{x}, SCM @var{alist})
688 @deftypefunx SCM gh_assv (SCM @var{x}, SCM @var{alist})
689 @deftypefunx SCM gh_assoc (SCM @var{x}, SCM @var{alist})
690 These functions search an @dfn{association list} (list of pairs)
691 @var{alist} for the first pair whose CAR is @var{x}, and they return
694 If no pair in @var{alist} has @var{x} as its CAR, the value
695 @code{SCM_BOOL_F} (not the empty list) is returned.
697 Note that these functions are implemented as macros which call
698 @code{scm_assq()}, @code{scm_assv()} and @code{scm_assoc()}
705 @c @deftypefun SCM gh_symbol (SCM str, SCM len)
706 @c @deftypefunx SCM gh_tmp_symbol (SCM str, SCM len)
707 @c Takes the given string @var{str} of length @var{len} and returns a
708 @c symbol corresponding to that string.
714 @deftypefun SCM gh_make_vector (SCM @var{n}, SCM @var{fill})
715 @deftypefunx SCM gh_vector (SCM @var{ls})
716 @deftypefunx SCM gh_vector_ref (SCM @var{v}, SCM @var{i})
717 @deftypefunx SCM gh_vector_set (SCM @var{v}, SCM @var{i}, SCM @var{val})
718 @deftypefunx {unsigned long} gh_vector_length (SCM @var{v})
719 @deftypefunx SCM gh_list_to_vector (SCM @var{ls})
720 These correspond to the Scheme @code{(make-vector n fill)},
721 @code{(vector a b c ...)} @code{(vector-ref v i)} @code{(vector-set v i
722 value)} @code{(vector-length v)} @code{(list->vector ls)} procedures.
724 The correspondence is not perfect for @code{gh_vector}: this routine
725 takes a list @var{ls} instead of the individual list elements, thus
726 making it identical to @code{gh_list_to_vector}.
728 There is also a difference in gh_vector_length: the value returned is a
729 C @code{unsigned long} instead of an SCM object.
735 @c @deftypefun SCM gh_make_subr (SCM (*@var{fn})(), int @var{req}, int @var{opt}, int @var{restp}, char *@var{sym})
736 @c Make the C function @var{fn} available to Scheme programs. The function
737 @c will be bound to the symbol @var{sym}. The arguments @var{req},
738 @c @var{opt} and @var{restp} describe @var{fn}'s calling conventions. The
739 @c function must take @var{req} required arguments and may take @var{opt}
740 @c optional arguments. Any optional arguments which are not supplied by
741 @c the caller will be bound to @var{SCM_UNSPECIFIED}. If @var{restp} is
742 @c non-zero, it means that @var{fn} may be called with an arbitrary number
743 @c of arguments, and that any extra arguments supplied by the caller will
744 @c be passed to @var{fn} as a list. The @var{restp} argument is exactly
745 @c like Scheme's @code{(lambda (arg1 arg2 . arglist))} calling convention.
747 @c For example, the procedure @code{read-line}, which takes optional
748 @c @var{port} and @var{handle-delim} arguments, would be declared like so:
751 @c SCM scm_read_line (SCM port, SCM handle_delim);
752 @c gh_make_subr (scm_read_line, 0, 2, 0, "read-line");
755 @c The @var{req} argument to @code{gh_make_subr} is 0 to indicate that
756 @c there are no required arguments, so @code{read-line} may be called
757 @c without any arguments at all. The @var{opt} argument is 2, to indicate
758 @c that both the @var{port} and @var{handle_delim} arguments to
759 @c @code{scm_read_line} are optional, and will be bound to
760 @c @code{SCM_UNSPECIFIED} if the calling program does not supply them.
761 @c Because the @var{restp} argument is 0, this function may not be called
762 @c with more than two arguments.
765 @deftypefun SCM gh_apply (SCM proc, SCM args)
766 Call the Scheme procedure @var{proc}, with the elements of @var{args} as
767 arguments. @var{args} must be a proper list.
770 @deftypefun SCM gh_call0 (SCM proc)
771 @deftypefunx SCM gh_call1 (SCM proc, SCM arg)
772 @deftypefunx SCM gh_call2 (SCM proc, SCM arg1, SCM arg2)
773 @deftypefunx SCM gh_call3 (SCM proc, SCM arg1, SCM arg2, SCM arg3)
774 Call the Scheme procedure @var{proc} with no arguments
775 (@code{gh_call0}), one argument (@code{gh_call1}), and so on. You can
776 get the same effect by wrapping the arguments up into a list, and
777 calling @code{gh_apply}; Guile provides these functions for convenience.
781 @deftypefun SCM gh_catch (SCM key, SCM thunk, SCM handler)
782 @deftypefunx SCM gh_throw (SCM key, SCM args)
783 Corresponds to the Scheme @code{catch} and @code{throw} procedures,
784 which in Guile are provided as primitives.
787 @c [FIXME: must add the I/O section in gscm.h]
789 @deftypefun SCM gh_is_eq (SCM a, SCM b)
790 @deftypefunx SCM gh_is_eqv (SCM a, SCM b)
791 @deftypefunx SCM gh_is_equal (SCM a, SCM b)
792 These correspond to the Scheme @code{eq?}, @code{eqv?} and @code{equal?}
796 @deftypefun int gh_obj_length (SCM @var{obj})
797 Returns the raw object length.
802 For now I just include Tim Pierce's comments from the @file{gh_data.c}
803 file; it should be organized into a documentation of the two functions
807 /* Data lookups between C and Scheme
809 Look up a symbol with a given name, and return the object to which
810 it is bound. gh_lookup examines the Guile top level, and
811 gh_module_lookup checks the module name space specified by the
814 The return value is the Scheme object to which SNAME is bound, or
815 SCM_UNDEFINED if SNAME is not bound in the given context. [FIXME:
816 should this be SCM_UNSPECIFIED? Can a symbol ever legitimately be
817 bound to SCM_UNDEFINED or SCM_UNSPECIFIED? What is the difference?
822 @node Mixing gh and scm APIs
823 @section Mixing gh and scm APIs
826 @node scm transition summary
827 @section Transitioning to the scm Interface
829 The following table summarizes the available information on how to
830 transition from the GH to the scm interface. Where transitioning is not
831 completely straightforward, the table includes a reference to more
832 detailed documentation in the preceding sections.
836 Use @code{#include <libguile.h>} instead of @code{#include
839 @item Compiling and Linking
840 Use @code{guile-config} to pick up the flags required to compile C or
841 C++ code that uses @code{libguile}, like so
844 $(CC) -o prog.o -c prog.c `guile-config compile`
847 If you are using libtool to link your executables, just use
848 @code{-lguile} in your link command. Libtool will expand this into
849 the needed linker options automatically. If you are not using
850 libtool, use the @code{guile-config} program to query the needed
851 options explicitly. A linker command like
854 $(CC) -o prog prog.o `guile-config link`
857 should be all that is needed. To link shared libraries that will be
858 used as Guile Extensions, use libtool to control both the compilation
861 @item The @code{SCM} type
862 No change: the scm interface also uses this type to represent an
863 arbitrary Scheme value.
865 @item @code{SCM_BOOL_F} and @code{SCM_BOOL_T}
868 @item @code{SCM_UNSPECIFIED} and @code{SCM_UNDEFINED}
871 @item @code{gh_enter}
872 Use @code{scm_boot_guile} instead, but note that @code{scm_boot_guile}
873 has a slightly different calling convention from @code{gh_enter}:
874 @code{scm_boot_guile}, and the main program function that you specify
875 for @code{scm_boot_guile} to call, both take an additional @var{closure}
876 parameter. @ref{Guile Initialization Functions} for more details.
879 Use @code{scm_shell} instead.
882 Use @code{scm_init_guile} instead.
884 @item @code{gh_eval_str}
885 Use @code{scm_c_eval_string} instead.
887 @item @code{gh_eval_file} or @code{gh_load}
888 Use @code{scm_c_primitive_load} instead.
890 @item @code{gh_new_procedure}
891 Use @code{scm_c_define_gsubr} instead, but note that the arguments are
892 in a different order: for @code{scm_c_define_gsubr} the C function
893 pointer is the last argument. @ref{A Sample Guile Extension} for an
896 @item @code{gh_defer_ints} and @code{gh_allow_ints}
897 Use @code{SCM_DEFER_INTS} and @code{SCM_ALLOW_INTS} instead. Note that
898 these macros are used without parentheses, as in @code{SCM_DEFER_INTS;}.
900 @item @code{gh_bool2scm}
901 Use @code{SCM_BOOL} instead.
903 @item @code{gh_ulong2scm}
904 Use @code{scm_ulong2num} instead.
906 @item @code{gh_long2scm}
907 Use @code{scm_long2num} instead.
909 @item @code{gh_double2scm}
910 Use @code{scm_make_real} instead.
912 @item @code{gh_char2scm}
913 Use @code{SCM_MAKE_CHAR} instead.
915 @item @code{gh_str2scm}
916 Use @code{scm_mem2string} instead.
918 @item @code{gh_str02scm}
919 Use @code{scm_makfrom0str} instead.
921 @item @code{gh_set_substr}
922 No direct scm equivalent. [FIXME]
924 @item @code{gh_symbol2scm}
925 Use @code{scm_str2symbol} instead. [FIXME: inconsistent naming,
926 should be @code{scm_str02symbol}.]
928 @item @code{gh_ints2scm} and @code{gh_doubles2scm}
929 Use @code{scm_c_ints2scm} and @code{scm_c_doubles2scm} instead.
931 @item @code{gh_chars2byvect} and @code{gh_shorts2svect}
932 Use @code{scm_c_chars2byvect} and @code{scm_c_shorts2svect} instead.
934 @item @code{gh_longs2ivect} and @code{gh_ulongs2uvect}
935 Use @code{scm_c_longs2ivect} and @code{scm_c_ulongs2uvect} instead.
937 @item @code{gh_floats2fvect} and @code{gh_doubles2dvect}
938 Use @code{scm_c_floats2fvect} and @code{scm_c_doubles2dvect} instead.
940 @item @code{gh_scm2bool}
941 Use @code{SCM_NFALSEP} instead.
943 @item @code{gh_scm2int}
944 Replace @code{gh_scm2int (@var{obj})} by
946 scm_num2int (@var{obj}, SCM_ARG1, @var{str})
948 where @var{str} is a C string that describes the context of the call.
950 @item @code{gh_scm2ulong}
951 Replace @code{gh_scm2ulong (@var{obj})} by
953 scm_num2ulong (@var{obj}, SCM_ARG1, @var{str})
955 where @var{str} is a C string that describes the context of the call.
957 @item @code{gh_scm2long}
958 Replace @code{gh_scm2long (@var{obj})} by
960 scm_num2long (@var{obj}, SCM_ARG1, @var{str})
962 where @var{str} is a C string that describes the context of the call.
964 @item @code{gh_scm2double}
965 Replace @code{gh_scm2double (@var{obj})} by
967 scm_num2dbl (@var{obj}, @var{str})
969 where @var{str} is a C string that describes the context of the call.
971 @item @code{gh_scm2char}
972 Use the @code{SCM_CHAR} macro instead, but note that @code{SCM_CHAR}
973 does not check that its argument is actually a character. To check that
974 a @code{SCM} value is a character before using @code{SCM_CHAR} to
975 extract the character value, use the @code{SCM_VALIDATE_CHAR} macro.
977 @item @code{gh_scm2newstr}
978 Instead of @code{gh_scm2newstr (@var{obj}, @var{lenp})} use
979 @code{scm_c_string2str (@var{obj}, @var{str}, @var{lenp})}. With the
980 additional @var{str} argument the user can pass a pre-allocated memory
981 chunk or leave it passing NULL.
983 @item @code{gh_get_substr}
984 Use the @code{scm_c_substring2str (@var{obj}, @var{str}, @var{start},
985 @var{len})} function instead.
987 @item @code{gh_symbol2newstr}
988 Use the @code{scm_c_symbol2str (@var{obj}, @var{str}, @var{lenp})} function
989 instead. With the additional @var{str} argument the user can pass a
990 pre-allocated memory chunk or leave it passing NULL.
992 @item @code{gh_scm2chars}
993 Use @code{scm_c_scm2chars} instead.
995 @item @code{gh_scm2shorts} and @code{gh_scm2longs}
996 Use @code{scm_c_shorts2scm} and @code{scm_c_longs2scm} instead.
998 @item @code{gh_scm2floats} and @code{gh_scm2doubles}
999 Use @code{scm_c_floats2scm} and @code{scm_c_doubles2scm} instead.
1001 @item @code{gh_boolean_p}
1002 Use the @code{SCM_BOOLP} macro instead, or replace @code{gh_boolean_p
1005 SCM_NFALSEP (scm_boolean_p (@var{obj}))
1008 @item @code{gh_symbol_p}
1009 Use the @code{SCM_SYMBOLP} macro instead, or replace @code{gh_symbol_p
1012 SCM_NFALSEP (scm_symbol_p (@var{obj}))
1015 @item @code{gh_char_p}
1016 Use the @code{SCM_CHARP} macro instead, or replace @code{gh_char_p
1019 SCM_NFALSEP (scm_char_p (@var{obj}))
1022 @item @code{gh_vector_p}
1023 Use the @code{SCM_VECTORP} macro instead, or replace @code{gh_vector_p
1026 SCM_NFALSEP (scm_vector_p (@var{obj}))
1029 @item @code{gh_pair_p}
1030 Use the @code{SCM_CONSP} macro instead, or replace @code{gh_pair_p
1033 SCM_NFALSEP (scm_pair_p (@var{obj}))
1036 @item @code{gh_number_p}
1037 Use the @code{SCM_NUMBERP} macro instead, or replace @code{gh_number_p
1040 SCM_NFALSEP (scm_number_p (@var{obj}))
1043 @item @code{gh_string_p}
1044 Use the @code{SCM_STRINGP} macro instead, or replace @code{gh_string_p
1047 SCM_NFALSEP (scm_string_p (@var{obj}))
1050 @item @code{gh_procedure_p}
1051 Replace @code{gh_procedure_p (@var{obj})} by
1053 SCM_NFALSEP (scm_procedure_p (@var{obj}))
1056 @item @code{gh_list_p}
1057 Replace @code{gh_list_p (@var{obj})} by
1059 SCM_NFALSEP (scm_list_p (@var{obj}))
1062 @item @code{gh_inexact_p}
1063 Use the @code{SCM_INEXACTP} macro instead, or replace @code{gh_inexact_p
1066 SCM_NFALSEP (scm_inexact_p (@var{obj}))
1069 @item @code{gh_exact_p}
1070 Replace @code{gh_exact_p (@var{obj})} by
1072 SCM_NFALSEP (scm_exact_p (@var{obj}))
1075 @item @code{gh_eq_p}
1076 Use the @code{SCM_EQ_P} macro instead, or replace @code{gh_eq_p
1077 (@var{x}, @var{y})} by
1079 SCM_NFALSEP (scm_eq_p (@var{x}, @var{y}))
1082 @item @code{gh_eqv_p}
1083 Replace @code{gh_eqv_p (@var{x}, @var{y})} by
1085 SCM_NFALSEP (scm_eqv_p (@var{x}, @var{y}))
1088 @item @code{gh_equal_p}
1089 Replace @code{gh_equal_p (@var{x}, @var{y})} by
1091 SCM_NFALSEP (scm_equal_p (@var{x}, @var{y}))
1094 @item @code{gh_string_equal_p}
1095 Replace @code{gh_string_equal_p (@var{x}, @var{y})} by
1097 SCM_NFALSEP (scm_string_equal_p (@var{x}, @var{y}))
1100 @item @code{gh_null_p}
1101 Use the @code{SCM_NULLP} macro instead, or replace @code{gh_null_p
1104 SCM_NFALSEP (scm_null_p (@var{obj}))
1107 @item @code{gh_cons}
1108 Use @code{scm_cons} instead.
1110 @item @code{gh_car} and @code{gh_cdr}
1111 Use the @code{SCM_CAR} and @code{SCM_CDR} macros instead.
1113 @item @code{gh_cxxr} and @code{gh_cxxxr}
1114 (Where each x is either @samp{a} or @samp{d}.) Use the corresponding
1115 @code{SCM_CXXR} or @code{SCM_CXXXR} macro instead.
1117 @item @code{gh_set_car_x} and @code{gh_set_cdr_x}
1118 Use @code{scm_set_car_x} and @code{scm_set_cdr_x} instead.
1120 @item @code{gh_list}
1121 Use @code{scm_listify} instead.
1123 @item @code{gh_length}
1124 Replace @code{gh_length (@var{lst})} by
1126 scm_num2ulong (scm_length (@var{lst}), SCM_ARG1, @var{str})
1128 where @var{str} is a C string that describes the context of the call.
1130 @item @code{gh_append}
1131 Use @code{scm_append} instead.
1133 @item @code{gh_append2}, @code{gh_append3}, @code{gh_append4}
1134 Replace @code{gh_append@var{N} (@var{l1}, @dots{}, @var{lN})} by
1136 scm_append (scm_listify (@var{l1}, @dots{}, @var{lN}, SCM_UNDEFINED))
1139 @item @code{gh_reverse}
1140 Use @code{scm_reverse} instead.
1142 @item @code{gh_list_tail} and @code{gh_list_ref}
1143 Use @code{scm_list_tail} and @code{scm_list_ref} instead.
1145 @item @code{gh_memq}, @code{gh_memv} and @code{gh_member}
1146 Use @code{scm_memq}, @code{scm_memv} and @code{scm_member} instead.
1148 @item @code{gh_assq}, @code{gh_assv} and @code{gh_assoc}
1149 Use @code{scm_assq}, @code{scm_assv} and @code{scm_assoc} instead.
1151 @item @code{gh_make_vector}
1152 Use @code{scm_make_vector} instead.
1154 @item @code{gh_vector} or @code{gh_list_to_vector}
1155 Use @code{scm_vector} instead.
1157 @item @code{gh_vector_ref} and @code{gh_vector_set_x}
1158 Use @code{scm_vector_ref} and @code{scm_vector_set_x} instead.
1160 @item @code{gh_vector_length}
1161 Use the @code{SCM_VECTOR_LENGTH} macro instead.
1163 @item @code{gh_apply}
1164 Use @code{scm_apply} instead, but note that @code{scm_apply} takes an
1165 additional third argument that you should set to @code{SCM_EOL}.