2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
9 @chapter GH: A Portable C to Scheme Interface
12 @cindex gh - reference manual
14 This chapter shows how to use the GH interface to call Guile from your
15 application's C code, and to add new Scheme level procedures to Guile
16 whose behaviour is specified by application specific code written in C.
18 Note, however, that the GH interface is now deprecated, and developers
19 are encouraged to switch to using the scm interface instead. Therefore,
20 for each GH feature, this chapter should also document how to achieve
21 the same result using the scm interface.
24 * GH deprecation:: Why the GH interface is now deprecated.
26 * Data types and constants defined by gh::
27 * Starting and controlling the interpreter::
29 * Executing Scheme code::
30 * Defining new Scheme procedures in C::
31 * Converting data between C and Scheme::
33 * Equality predicates::
34 * Memory allocation and garbage collection::
35 * Calling Scheme procedures from C::
36 * Mixing gh and scm APIs::
37 * scm transition summary::
42 @section Why the GH Interface is Now Deprecated
44 Historically, the GH interface was the product of a practical problem
45 and a neat idea. The practical problem was that the interface of the
46 @code{scm_} functions with which Guile itself was written (inherited
47 from Aubrey Jaffer's SCM) was so closely tied to the (rather arcane)
48 details of the internal data representation that it was extremely
49 difficult to write a Guile extension using these functions. The neat
50 idea was to define a high level language extension interface in such a
51 way that other extension language projects, not just Guile, would be
52 able to provide an implementation of that interface; then applications
53 using this interface could be compiled with whichever of the various
54 available implementations they chose. So the GH interface was created,
55 and advertised both as the recommended interface for application
56 developers wishing to use Guile, and as a portable high level interface
57 that could theoretically be implemented by other extension language
60 Time passed, and various things changed. Crucially, an enormous number
61 of improvements were made to the @code{scm_} interface that Guile itself
62 uses in its implementation, with the result that it is now both easy and
63 comfortable to write a Guile extension with this interface. At the same
64 time, the contents of the GH interface were somewhat neglected by the
65 core Guile developers, such that some key operations --- such as smob
66 creation and management --- are simply not possible using GH alone.
67 Finally, the idea of multiple implementations of the GH interface did
68 not really crystallize (apart, I believe, from a short lived
69 implementation by the MzScheme project).
71 For all these reasons, the Guile developers have decided to deprecate
72 the GH interface --- which means that support for GH will be completely
73 removed after the next few releases --- and to focus only on the
74 @code{scm_} interface, with additions to ensure that it is as easy to
75 use in all respects as GH was.
77 It remains an open question whether a deep kind of interface portability
78 would be useful for extension language-based applications, and it may
79 still be an interesting project to attempt to define a corresponding
80 GH-like interface, but the Guile developers no longer plan to try to do
81 this as part of the core Guile project.
84 @node gh preliminaries
85 @section gh preliminaries
87 To use gh, you must have the following toward the beginning of your C
94 When you link, you will have to add at least @code{-lguile} to the list
95 of libraries. If you are using more of Guile than the basic Scheme
96 interpreter, you will have to add more libraries.
100 @node Data types and constants defined by gh
101 @section Data types and constants defined by gh
102 @cindex libguile - data types
104 The following C constants and data types are defined in gh:
106 @code{SCM} is a C data type used to store all Scheme data, no matter what the
107 Scheme type. Values are converted between C data types and the SCM type
108 with utility functions described below (@pxref{Converting data between C
109 and Scheme}). [FIXME: put in references to Jim's essay and so forth.]
111 @defvr Constant SCM_BOOL_T
112 @defvrx Constant SCM_BOOL_F
113 The @emph{Scheme} values returned by many boolean procedures in
116 This can cause confusion because they are different from 0 and 1. In
117 testing a boolean function in libguile programming, you must always make
118 sure that you check the spec: @code{gh_} and @code{scm_} functions will
119 usually return @code{SCM_BOOL_T} and @code{SCM_BOOL_F}, but other C
120 functions usually can be tested against 0 and 1, so programmers' fingers
121 tend to just type @code{if (boolean_function()) @{ ... @}}
124 @defvr Constant SCM_UNSPECIFIED
125 This is a SCM value that is not the same as any legal Scheme value. It
126 is the value that a Scheme function returns when its specification says
127 that its return value is unspecified.
130 @defvr Constant SCM_UNDEFINED
131 This is another SCM value that is not the same as any legal Scheme
132 value. It is the value used to mark variables that do not yet have a
133 value, and it is also used in C to terminate functions with variable
134 numbers of arguments, such as @code{gh_list()}.
138 @node Starting and controlling the interpreter
139 @section Starting and controlling the interpreter
140 @cindex libguile - start interpreter
142 In almost every case, your first @code{gh_} call will be:
144 @deftypefun void gh_enter (int @var{argc}, char *@var{argv}[], void (*@var{main_prog})())
145 Starts up a Scheme interpreter with all the builtin Scheme primitives.
146 @code{gh_enter()} never exits, and the user's code should all be in the
147 @code{@var{main_prog}()} function. @code{argc} and @code{argv} will be
148 passed to @var{main_prog}.
150 @deftypefun void main_prog (int @var{argc}, char *@var{argv}[])
151 This is the user's main program. It will be invoked by
152 @code{gh_enter()} after Guile has been started up.
155 Note that you can use @code{gh_repl} inside @code{gh_enter} (in other
156 words, inside the code for @code{main-prog}) if you want the program to
157 be controlled by a Scheme read-eval-print loop.
160 @cindex read eval print loop -- from the gh_ interface
161 @cindex REPL -- from the gh_ interface
162 A convenience routine which enters the Guile interpreter with the
163 standard Guile read-eval-print loop (@dfn{REPL}) is:
165 @deftypefun void gh_repl (int @var{argc}, char *@var{argv}[])
166 Enters the Scheme interpreter giving control to the Scheme REPL.
167 Arguments are processed as if the Guile program @file{guile} were being
170 Note that @code{gh_repl} should be used @emph{inside} @code{gh_enter},
171 since any Guile interpreter calls are meaningless unless they happen in
172 the context of the interpreter.
174 Also note that when you use @code{gh_repl}, your program will be
175 controlled by Guile's REPL (which is written in Scheme and has many
176 useful features). Use straight C code inside @code{gh_enter} if you
177 want to maintain execution control in your C program.
180 You will typically use @code{gh_enter} and @code{gh_repl} when you
181 want a Guile interpreter enhanced by your own libraries, but otherwise
182 quite normal. For example, to build a Guile--derived program that
183 includes some random number routines @dfn{GSL} (GNU Scientific Library),
184 you would write a C program that looks like this:
187 #include <guile/gh.h>
190 /* random number suite */
191 SCM gw_ran_seed(SCM s)
193 gsl_ran_seed(gh_scm2int(s));
194 return SCM_UNSPECIFIED;
201 x = gh_ulong2scm(gsl_ran_random());
209 x = gh_double2scm(gsl_ran_uniform());
214 return gh_double2scm(gsl_ran_max());
220 /* random number suite */
221 gh_new_procedure("gsl-ran-seed", gw_ran_seed, 1, 0, 0);
222 gh_new_procedure("gsl-ran-random", gw_ran_random, 0, 0, 0);
223 gh_new_procedure("gsl-ran-uniform", gw_ran_uniform, 0, 0, 0);
224 gh_new_procedure("gsl-ran-max", gw_ran_max, 0, 0, 0);
228 main_prog (int argc, char *argv[])
236 main (int argc, char *argv[])
238 gh_enter (argc, argv, main_prog);
242 Then, supposing the C program is in @file{guile-gsl.c}, you could
243 compile it with @kbd{gcc -o guile-gsl guile-gsl.c -lguile -lgsl}.
245 The resulting program @file{guile-gsl} would have new primitive
246 procedures @code{gsl-ran-random}, @code{gsl-ran-gaussian} and so forth.
250 @section Error messages
251 @cindex libguile - error messages
252 @cindex error messages in libguile
254 [FIXME: need to fill this based on Jim's new mechanism]
257 @node Executing Scheme code
258 @section Executing Scheme code
259 @cindex libguile - executing Scheme
260 @cindex executing Scheme
262 Once you have an interpreter running, you can ask it to evaluate Scheme
263 code. There are two calls that implement this:
265 @deftypefun SCM gh_eval_str (char *@var{scheme_code})
266 This asks the interpreter to evaluate a single string of Scheme code,
267 and returns the result of the last expression evaluated.
269 Note that the line of code in @var{scheme_code} must be a well formed
270 Scheme expression. If you have many lines of code before you balance
271 parentheses, you must either concatenate them into one string, or use
272 @code{gh_eval_file()}.
275 @deftypefun SCM gh_eval_file (char *@var{fname})
276 @deftypefunx SCM gh_load (char *@var{fname})
277 @code{gh_eval_file} is completely analogous to @code{gh_eval_str()},
278 except that a whole file is evaluated instead of a string.
279 @code{gh_eval_file} returns @code{SCM_UNSPECIFIED}.
281 @code{gh_load} is identical to @code{gh_eval_file} (it's a macro that
282 calls @code{gh_eval_file} on its argument). It is provided to start
283 making the @code{gh_} interface match the R5RS Scheme procedures
288 @node Defining new Scheme procedures in C
289 @section Defining new Scheme procedures in C
290 @cindex libguile - new procedures
291 @cindex new procedures
292 @cindex procedures, new
293 @cindex new primitives
294 @cindex primitives, new
296 The real interface between C and Scheme comes when you can write new
297 Scheme procedures in C. This is done through the routine
300 @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})
301 @code{gh_new_procedure} defines a new Scheme procedure. Its Scheme name
302 will be @var{proc_name}, it will be implemented by the C function
303 (*@var{fn})(), it will take at least @var{n_required_args} arguments,
304 and at most @var{n_optional_args} extra arguments.
306 When the @var{restp} parameter is 1, the procedure takes a final
307 argument: a list of remaining parameters.
309 @code{gh_new_procedure} returns an SCM value representing the procedure.
311 The C function @var{fn} should have the form
312 @deftypefn {Libguile high} SCM fn (SCM @var{req1}, SCM @var{req2}, ..., SCM @var{opt1}, SCM @var{opt2}, ..., SCM @var{rest_args})
313 The arguments are all passed as SCM values, so the user will have to use
314 the conversion functions to convert to standard C types.
316 Examples of C functions used as new Scheme primitives can be found in
317 the sample programs @code{learn0} and @code{learn1}.
322 @strong{Rationale:} this is the correct way to define new Scheme
323 procedures in C. The ugly mess of arguments is required because of how
324 C handles procedures with variable numbers of arguments.
326 @strong{NB:} what about documentation strings?
329 There are several important considerations to be made when writing the C
330 routine @code{(*fn)()}.
332 First of all the C routine has to return type @code{SCM}.
334 Second, all arguments passed to the C function will be of type
337 Third: the C routine is now subject to Scheme flow control, which means
338 that it could be interrupted at any point, and then reentered. This
339 means that you have to be very careful with operations such as
340 allocating memory, modifying static data @dots{}
342 Fourth: to get around the latter issue, you can use
343 @code{GH_DEFER_INTS} and @code{GH_ALLOW_INTS}.
346 @defmac GH_DEFER_INTS
347 @defmacx GH_ALLOW_INTS
348 These macros disable and re-enable Scheme's flow control. They
352 @c [??? have to do this right; maybe using subsections, or maybe creating a
353 @c section called Flow control issues...]
355 @c [??? Go into exhaustive detail with examples of the various possible
356 @c combinations of required and optional args...]
359 @node Converting data between C and Scheme
360 @section Converting data between C and Scheme
361 @cindex libguile - converting data
362 @cindex data conversion
363 @cindex converting data
365 Guile provides mechanisms to convert data between C and Scheme. This
366 allows new builtin procedures to understand their arguments (which are
367 of type @code{SCM}) and return values of type @code{SCM}.
376 @subsection C to Scheme
378 @deftypefun SCM gh_bool2scm (int @var{x})
379 Returns @code{#f} if @var{x} is zero, @code{#t} otherwise.
382 @deftypefun SCM gh_ulong2scm (unsigned long @var{x})
383 @deftypefunx SCM gh_long2scm (long @var{x})
384 @deftypefunx SCM gh_double2scm (double @var{x})
385 @deftypefunx SCM gh_char2scm (char @var{x})
386 Returns a Scheme object with the value of the C quantity @var{x}.
389 @deftypefun SCM gh_str2scm (char *@var{s}, int @var{len})
390 Returns a new Scheme string with the (not necessarily null-terminated) C
394 @deftypefun SCM gh_str02scm (char *@var{s})
395 Returns a new Scheme string with the null-terminated C string @var{s}
399 @deftypefun SCM gh_set_substr (char *@var{src}, SCM @var{dst}, int @var{start}, int @var{len})
400 Copy @var{len} characters at @var{src} into the @emph{existing} Scheme
401 string @var{dst}, starting at @var{start}. @var{start} is an index into
402 @var{dst}; zero means the beginning of the string.
404 If @var{start} + @var{len} is off the end of @var{dst}, signal an
408 @deftypefun SCM gh_symbol2scm (char *@var{name})
409 Given a null-terminated string @var{name}, return the symbol with that
413 @deftypefun SCM gh_ints2scm (int *@var{dptr}, int @var{n})
414 @deftypefunx SCM gh_doubles2scm (double *@var{dptr}, int @var{n})
415 Make a scheme vector containing the @var{n} ints or doubles at memory
419 @deftypefun SCM gh_chars2byvect (char *@var{dptr}, int @var{n})
420 @deftypefunx SCM gh_shorts2svect (short *@var{dptr}, int @var{n})
421 @deftypefunx SCM gh_longs2ivect (long *@var{dptr}, int @var{n})
422 @deftypefunx SCM gh_ulongs2uvect (ulong *@var{dptr}, int @var{n})
423 @deftypefunx SCM gh_floats2fvect (float *@var{dptr}, int @var{n})
424 @deftypefunx SCM gh_doubles2dvect (double *@var{dptr}, int @var{n})
425 Make a scheme uniform vector containing the @var{n} chars, shorts,
426 longs, unsigned longs, floats or doubles at memory location @var{dptr}.
432 @subsection Scheme to C
434 @deftypefun int gh_scm2bool (SCM @var{obj})
435 @deftypefunx {unsigned long} gh_scm2ulong (SCM @var{obj})
436 @deftypefunx long gh_scm2long (SCM @var{obj})
437 @deftypefunx double gh_scm2double (SCM @var{obj})
438 @deftypefunx int gh_scm2char (SCM @var{obj})
439 These routines convert the Scheme object to the given C type.
442 @deftypefun {char *} gh_scm2newstr (SCM @var{str}, size_t *@var{lenp})
443 Given a Scheme string @var{str}, return a pointer to a new copy of its
444 contents, followed by a null byte. If @var{lenp} is non-null, set
445 @code{*@var{lenp}} to the string's length.
447 This function uses malloc to obtain storage for the copy; the caller is
448 responsible for freeing it.
450 Note that Scheme strings may contain arbitrary data, including null
451 characters. This means that null termination is not a reliable way to
452 determine the length of the returned value. However, the function
453 always copies the complete contents of @var{str}, and sets @var{*lenp}
454 to the true length of the string (when @var{lenp} is non-null).
458 @deftypefun void gh_get_substr (SCM str, char *return_str, int *lenp)
459 Copy @var{len} characters at @var{start} from the Scheme string
460 @var{src} to memory at @var{dst}. @var{start} is an index into
461 @var{src}; zero means the beginning of the string. @var{dst} has
462 already been allocated by the caller.
464 If @var{start} + @var{len} is off the end of @var{src}, signal an
468 @deftypefun {char *} gh_symbol2newstr (SCM @var{sym}, int *@var{lenp})
469 Takes a Scheme symbol and returns a string of the form
470 @code{"'symbol-name"}. If @var{lenp} is non-null, the string's length
471 is returned in @code{*@var{lenp}}.
473 This function uses malloc to obtain storage for the returned string; the
474 caller is responsible for freeing it.
477 @deftypefun {char *} gh_scm2chars (SCM @var{vector}, chars *@var{result})
478 @deftypefunx {short *} gh_scm2shorts (SCM @var{vector}, short *@var{result})
479 @deftypefunx {long *} gh_scm2longs (SCM @var{vector}, long *@var{result})
480 @deftypefunx {float *} gh_scm2floats (SCM @var{vector}, float *@var{result})
481 @deftypefunx {double *} gh_scm2doubles (SCM @var{vector}, double *@var{result})
482 Copy the numbers in @var{vector} to the array pointed to by @var{result}
483 and return it. If @var{result} is NULL, allocate a double array large
486 @var{vector} can be an ordinary vector, a weak vector, or a signed or
487 unsigned uniform vector of the same type as the result array. For
488 chars, @var{vector} can be a string or substring. For floats and
489 doubles, @var{vector} can contain a mix of inexact and integer values.
491 If @var{vector} is of unsigned type and contains values too large to fit
492 in the signed destination array, those values will be wrapped around,
493 that is, data will be copied as if the destination array was unsigned.
497 @node Type predicates
498 @section Type predicates
500 These C functions mirror Scheme's type predicate procedures with one
501 important difference. The C routines return C boolean values (0 and 1)
502 instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}.
504 The Scheme notational convention of putting a @code{?} at the end of
505 predicate procedure names is mirrored in C by placing @code{_p} at the
506 end of the procedure. For example, @code{(pair? ...)} maps to
507 @code{gh_pair_p(...)}.
509 @deftypefun int gh_boolean_p (SCM @var{val})
510 Returns 1 if @var{val} is a boolean, 0 otherwise.
513 @deftypefun int gh_symbol_p (SCM @var{val})
514 Returns 1 if @var{val} is a symbol, 0 otherwise.
517 @deftypefun int gh_char_p (SCM @var{val})
518 Returns 1 if @var{val} is a char, 0 otherwise.
521 @deftypefun int gh_vector_p (SCM @var{val})
522 Returns 1 if @var{val} is a vector, 0 otherwise.
525 @deftypefun int gh_pair_p (SCM @var{val})
526 Returns 1 if @var{val} is a pair, 0 otherwise.
529 @deftypefun int gh_procedure_p (SCM @var{val})
530 Returns 1 if @var{val} is a procedure, 0 otherwise.
533 @deftypefun int gh_list_p (SCM @var{val})
534 Returns 1 if @var{val} is a list, 0 otherwise.
537 @deftypefun int gh_inexact_p (SCM @var{val})
538 Returns 1 if @var{val} is an inexact number, 0 otherwise.
541 @deftypefun int gh_exact_p (SCM @var{val})
542 Returns 1 if @var{val} is an exact number, 0 otherwise.
546 @node Equality predicates
547 @section Equality predicates
549 These C functions mirror Scheme's equality predicate procedures with one
550 important difference. The C routines return C boolean values (0 and 1)
551 instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}.
553 The Scheme notational convention of putting a @code{?} at the end of
554 predicate procedure names is mirrored in C by placing @code{_p} at the
555 end of the procedure. For example, @code{(equal? ...)} maps to
556 @code{gh_equal_p(...)}.
558 @deftypefun int gh_eq_p (SCM x, SCM y)
559 Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
560 @code{eq?} predicate, 0 otherwise.
563 @deftypefun int gh_eqv_p (SCM x, SCM y)
564 Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
565 @code{eqv?} predicate, 0 otherwise.
568 @deftypefun int gh_equal_p (SCM x, SCM y)
569 Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
570 @code{equal?} predicate, 0 otherwise.
573 @deftypefun int gh_string_equal_p (SCM @var{s1}, SCM @var{s2})
574 Returns 1 if the strings @var{s1} and @var{s2} are equal, 0 otherwise.
577 @deftypefun int gh_null_p (SCM @var{l})
578 Returns 1 if @var{l} is an empty list or pair; 0 otherwise.
582 @node Memory allocation and garbage collection
583 @section Memory allocation and garbage collection
585 @c [FIXME: flesh this out with some description of garbage collection in
588 @c @deftypefun SCM gh_mkarray (int size)
589 @c Allocate memory for a Scheme object in a garbage-collector-friendly
594 @node Calling Scheme procedures from C
595 @section Calling Scheme procedures from C
597 Many of the Scheme primitives are available in the @code{gh_}
598 interface; they take and return objects of type SCM, and one could
599 basically use them to write C code that mimics Scheme code.
601 I will list these routines here without much explanation, since what
602 they do is the same as documented in @ref{Standard procedures, R5RS, ,
603 r5rs, R5RS}. But I will point out that when a procedure takes a
604 variable number of arguments (such as @code{gh_list}), you should pass
605 the constant @var{SCM_UNDEFINED} from C to signify the end of the list.
607 @deftypefun SCM gh_define (char *@var{name}, SCM @var{val})
608 Corresponds to the Scheme @code{(define name val)}: it binds a value to
609 the given name (which is a C string). Returns the new object.
612 @heading Pairs and lists
614 @deftypefun SCM gh_cons (SCM @var{a}, SCM @var{b})
615 @deftypefunx SCM gh_list (SCM l0, SCM l1, ... , SCM_UNDEFINED)
616 These correspond to the Scheme @code{(cons a b)} and @code{(list l0 l1
617 ...)} procedures. Note that @code{gh_list()} is a C macro that invokes
621 @deftypefun SCM gh_car (SCM @var{obj})
622 @deftypefunx SCM gh_cdr (SCM @var{obj})
625 @deftypefunx SCM gh_c[ad][ad][ad][ad]r (SCM @var{obj})
626 These correspond to the Scheme @code{(caadar ls)} procedures etc @dots{}
629 @deftypefun SCM gh_set_car_x (SCM @var{pair}, SCM @var{value})
630 Modifies the CAR of @var{pair} to be @var{value}. This is equivalent to
631 the Scheme procedure @code{(set-car! ...)}.
634 @deftypefun SCM gh_set_cdr_x (SCM @var{pair}, SCM @var{value})
635 Modifies the CDR of @var{pair} to be @var{value}. This is equivalent to
636 the Scheme procedure @code{(set-cdr! ...)}.
639 @deftypefun {unsigned long} gh_length (SCM @var{ls})
640 Returns the length of the list.
643 @deftypefun SCM gh_append (SCM @var{args})
644 @deftypefunx SCM gh_append2 (SCM @var{l1}, SCM @var{l2})
645 @deftypefunx SCM gh_append3 (SCM @var{l1}, SCM @var{l2}, @var{l3})
646 @deftypefunx SCM gh_append4 (SCM @var{l1}, SCM @var{l2}, @var{l3}, @var{l4})
647 @code{gh_append()} takes @var{args}, which is a list of lists
648 @code{(list1 list2 ...)}, and returns a list containing all the elements
649 of the individual lists.
651 A typical invocation of @code{gh_append()} to append 5 lists together
654 gh_append(gh_list(l1, l2, l3, l4, l5, SCM_UNDEFINED));
657 The functions @code{gh_append2()}, @code{gh_append2()},
658 @code{gh_append3()} and @code{gh_append4()} are convenience routines to
659 make it easier for C programs to form the list of lists that goes as an
660 argument to @code{gh_append()}.
663 @deftypefun SCM gh_reverse (SCM @var{ls})
664 Returns a new list that has the same elements as @var{ls} but in the
665 reverse order. Note that this is implemented as a macro which calls
666 @code{scm_reverse()}.
669 @deftypefun SCM gh_list_tail (SCM @var{ls}, SCM @var{k})
670 Returns the sublist of @var{ls} with the last @var{k} elements.
673 @deftypefun SCM gh_list_ref (SCM @var{ls}, SCM @var{k})
674 Returns the @var{k}th element of the list @var{ls}.
677 @deftypefun SCM gh_memq (SCM @var{x}, SCM @var{ls})
678 @deftypefunx SCM gh_memv (SCM @var{x}, SCM @var{ls})
679 @deftypefunx SCM gh_member (SCM @var{x}, SCM @var{ls})
680 These functions return the first sublist of @var{ls} whose CAR is
681 @var{x}. They correspond to @code{(memq x ls)}, @code{(memv x ls)} and
682 @code{(member x ls)}, and hence use (respectively) @code{eq?},
683 @code{eqv?} and @code{equal?} to do comparisons.
685 If @var{x} does not appear in @var{ls}, the value @code{SCM_BOOL_F} (not
686 the empty list) is returned.
688 Note that these functions are implemented as macros which call
689 @code{scm_memq()}, @code{scm_memv()} and @code{scm_member()}
693 @deftypefun SCM gh_assq (SCM @var{x}, SCM @var{alist})
694 @deftypefunx SCM gh_assv (SCM @var{x}, SCM @var{alist})
695 @deftypefunx SCM gh_assoc (SCM @var{x}, SCM @var{alist})
696 These functions search an @dfn{association list} (list of pairs)
697 @var{alist} for the first pair whose CAR is @var{x}, and they return
700 If no pair in @var{alist} has @var{x} as its CAR, the value
701 @code{SCM_BOOL_F} (not the empty list) is returned.
703 Note that these functions are implemented as macros which call
704 @code{scm_assq()}, @code{scm_assv()} and @code{scm_assoc()}
711 @c @deftypefun SCM gh_symbol (SCM str, SCM len)
712 @c @deftypefunx SCM gh_tmp_symbol (SCM str, SCM len)
713 @c Takes the given string @var{str} of length @var{len} and returns a
714 @c symbol corresponding to that string.
720 @deftypefun SCM gh_make_vector (SCM @var{n}, SCM @var{fill})
721 @deftypefunx SCM gh_vector (SCM @var{ls})
722 @deftypefunx SCM gh_vector_ref (SCM @var{v}, SCM @var{i})
723 @deftypefunx SCM gh_vector_set (SCM @var{v}, SCM @var{i}, SCM @var{val})
724 @deftypefunx {unsigned long} gh_vector_length (SCM @var{v})
725 @deftypefunx SCM gh_list_to_vector (SCM @var{ls})
726 These correspond to the Scheme @code{(make-vector n fill)},
727 @code{(vector a b c ...)} @code{(vector-ref v i)} @code{(vector-set v i
728 value)} @code{(vector-length v)} @code{(list->vector ls)} procedures.
730 The correspondence is not perfect for @code{gh_vector}: this routine
731 takes a list @var{ls} instead of the individual list elements, thus
732 making it identical to @code{gh_list_to_vector}.
734 There is also a difference in gh_vector_length: the value returned is a
735 C @code{unsigned long} instead of an SCM object.
741 @c @deftypefun SCM gh_make_subr (SCM (*@var{fn})(), int @var{req}, int @var{opt}, int @var{restp}, char *@var{sym})
742 @c Make the C function @var{fn} available to Scheme programs. The function
743 @c will be bound to the symbol @var{sym}. The arguments @var{req},
744 @c @var{opt} and @var{restp} describe @var{fn}'s calling conventions. The
745 @c function must take @var{req} required arguments and may take @var{opt}
746 @c optional arguments. Any optional arguments which are not supplied by
747 @c the caller will be bound to @var{SCM_UNSPECIFIED}. If @var{restp} is
748 @c non-zero, it means that @var{fn} may be called with an arbitrary number
749 @c of arguments, and that any extra arguments supplied by the caller will
750 @c be passed to @var{fn} as a list. The @var{restp} argument is exactly
751 @c like Scheme's @code{(lambda (arg1 arg2 . arglist))} calling convention.
753 @c For example, the procedure @code{read-line}, which takes optional
754 @c @var{port} and @var{handle-delim} arguments, would be declared like so:
757 @c SCM scm_read_line (SCM port, SCM handle_delim);
758 @c gh_make_subr (scm_read_line, 0, 2, 0, "read-line");
761 @c The @var{req} argument to @code{gh_make_subr} is 0 to indicate that
762 @c there are no required arguments, so @code{read-line} may be called
763 @c without any arguments at all. The @var{opt} argument is 2, to indicate
764 @c that both the @var{port} and @var{handle_delim} arguments to
765 @c @code{scm_read_line} are optional, and will be bound to
766 @c @code{SCM_UNSPECIFIED} if the calling program does not supply them.
767 @c Because the @var{restp} argument is 0, this function may not be called
768 @c with more than two arguments.
771 @deftypefun SCM gh_apply (SCM proc, SCM args)
772 Call the Scheme procedure @var{proc}, with the elements of @var{args} as
773 arguments. @var{args} must be a proper list.
776 @deftypefun SCM gh_call0 (SCM proc)
777 @deftypefunx SCM gh_call1 (SCM proc, SCM arg)
778 @deftypefunx SCM gh_call2 (SCM proc, SCM arg1, SCM arg2)
779 @deftypefunx SCM gh_call3 (SCM proc, SCM arg1, SCM arg2, SCM arg3)
780 Call the Scheme procedure @var{proc} with no arguments
781 (@code{gh_call0}), one argument (@code{gh_call1}), and so on. You can
782 get the same effect by wrapping the arguments up into a list, and
783 calling @code{gh_apply}; Guile provides these functions for convenience.
787 @deftypefun SCM gh_catch (SCM key, SCM thunk, SCM handler)
788 @deftypefunx SCM gh_throw (SCM key, SCM args)
789 Corresponds to the Scheme @code{catch} and @code{throw} procedures,
790 which in Guile are provided as primitives.
793 @c [FIXME: must add the I/O section in gscm.h]
795 @deftypefun SCM gh_is_eq (SCM a, SCM b)
796 @deftypefunx SCM gh_is_eqv (SCM a, SCM b)
797 @deftypefunx SCM gh_is_equal (SCM a, SCM b)
798 These correspond to the Scheme @code{eq?}, @code{eqv?} and @code{equal?}
802 @deftypefun int gh_obj_length (SCM @var{obj})
803 Returns the raw object length.
808 For now I just include Tim Pierce's comments from the @file{gh_data.c}
809 file; it should be organized into a documentation of the two functions
813 /* Data lookups between C and Scheme
815 Look up a symbol with a given name, and return the object to which
816 it is bound. gh_lookup examines the Guile top level, and
817 gh_module_lookup checks the module name space specified by the
820 The return value is the Scheme object to which SNAME is bound, or
821 SCM_UNDEFINED if SNAME is not bound in the given context. [FIXME:
822 should this be SCM_UNSPECIFIED? Can a symbol ever legitimately be
823 bound to SCM_UNDEFINED or SCM_UNSPECIFIED? What is the difference?
828 @node Mixing gh and scm APIs
829 @section Mixing gh and scm APIs
832 @node scm transition summary
833 @section Transitioning to the scm Interface
835 The following table summarizes the available information on how to
836 transition from the GH to the scm interface. Where transitioning is not
837 completely straightforward, the table includes a reference to more
838 detailed documentation in the preceding sections.
842 Use @code{#include <libguile.h>} instead of @code{#include
845 @item Compiling and Linking
846 Use @code{guile-config} to pick up the flags required to compile C or
847 C++ code that uses @code{libguile}, like so
850 $(CC) -o prog.o -c prog.c `guile-config compile`
853 If you are using libtool to link your executables, just use
854 @code{-lguile} in your link command. Libtool will expand this into
855 the needed linker options automatically. If you are not using
856 libtool, use the @code{guile-config} program to query the needed
857 options explicitly. A linker command like
860 $(CC) -o prog prog.o `guile-config link`
863 should be all that is needed. To link shared libraries that will be
864 used as Guile Extensions, use libtool to control both the compilation
867 @item The @code{SCM} type
868 No change: the scm interface also uses this type to represent an
869 arbitrary Scheme value.
871 @item @code{SCM_BOOL_F} and @code{SCM_BOOL_T}
874 @item @code{SCM_UNSPECIFIED} and @code{SCM_UNDEFINED}
877 @item @code{gh_enter}
878 Use @code{scm_boot_guile} instead, but note that @code{scm_boot_guile}
879 has a slightly different calling convention from @code{gh_enter}:
880 @code{scm_boot_guile}, and the main program function that you specify
881 for @code{scm_boot_guile} to call, both take an additional @var{closure}
882 parameter. @ref{Guile Initialization Functions} for more details.
885 Use @code{scm_shell} instead.
888 Use @code{scm_init_guile} instead.
890 @item @code{gh_eval_str}
891 Use @code{scm_c_eval_string} instead.
893 @item @code{gh_eval_file} or @code{gh_load}
894 Use @code{scm_c_primitive_load} instead.
896 @item @code{gh_new_procedure}
897 Use @code{scm_c_define_gsubr} instead, but note that the arguments are
898 in a different order: for @code{scm_c_define_gsubr} the C function
899 pointer is the last argument. @ref{A Sample Guile Extension} for an
902 @item @code{gh_defer_ints} and @code{gh_allow_ints}
903 Use @code{SCM_DEFER_INTS} and @code{SCM_ALLOW_INTS} instead. Note that
904 these macros are used without parentheses, as in @code{SCM_DEFER_INTS;}.
906 @item @code{gh_bool2scm}
907 Use @code{SCM_BOOL} instead.
909 @item @code{gh_ulong2scm}
910 Use @code{scm_ulong2num} instead.
912 @item @code{gh_long2scm}
913 Use @code{scm_long2num} instead.
915 @item @code{gh_double2scm}
916 Use @code{scm_make_real} instead.
918 @item @code{gh_char2scm}
919 Use @code{SCM_MAKE_CHAR} instead.
921 @item @code{gh_str2scm}
922 Use @code{scm_mem2string} instead.
924 @item @code{gh_str02scm}
925 Use @code{scm_makfrom0str} instead.
927 @item @code{gh_set_substr}
928 No direct scm equivalent. [FIXME]
930 @item @code{gh_symbol2scm}
931 Use @code{scm_str2symbol} instead. [FIXME: inconsistent naming,
932 should be @code{scm_str02symbol}.]
934 @item @code{gh_ints2scm} and @code{gh_doubles2scm}
935 Use @code{scm_c_ints2scm} and @code{scm_c_doubles2scm} instead.
937 @item @code{gh_chars2byvect} and @code{gh_shorts2svect}
938 Use @code{scm_c_chars2byvect} and @code{scm_c_shorts2svect} instead.
940 @item @code{gh_longs2ivect} and @code{gh_ulongs2uvect}
941 Use @code{scm_c_longs2ivect} and @code{scm_c_ulongs2uvect} instead.
943 @item @code{gh_floats2fvect} and @code{gh_doubles2dvect}
944 Use @code{scm_c_floats2fvect} and @code{scm_c_doubles2dvect} instead.
946 @item @code{gh_scm2bool}
947 Use @code{SCM_NFALSEP} instead.
949 @item @code{gh_scm2int}
950 Replace @code{gh_scm2int (@var{obj})} by
952 scm_num2int (@var{obj}, SCM_ARG1, @var{str})
954 where @var{str} is a C string that describes the context of the call.
956 @item @code{gh_scm2ulong}
957 Replace @code{gh_scm2ulong (@var{obj})} by
959 scm_num2ulong (@var{obj}, SCM_ARG1, @var{str})
961 where @var{str} is a C string that describes the context of the call.
963 @item @code{gh_scm2long}
964 Replace @code{gh_scm2long (@var{obj})} by
966 scm_num2long (@var{obj}, SCM_ARG1, @var{str})
968 where @var{str} is a C string that describes the context of the call.
970 @item @code{gh_scm2double}
971 Replace @code{gh_scm2double (@var{obj})} by
973 scm_num2dbl (@var{obj}, @var{str})
975 where @var{str} is a C string that describes the context of the call.
977 @item @code{gh_scm2char}
978 Use the @code{SCM_CHAR} macro instead, but note that @code{SCM_CHAR}
979 does not check that its argument is actually a character. To check that
980 a @code{SCM} value is a character before using @code{SCM_CHAR} to
981 extract the character value, use the @code{SCM_VALIDATE_CHAR} macro.
983 @item @code{gh_scm2newstr}
984 Instead of @code{gh_scm2newstr (@var{obj}, @var{lenp})} use
985 @code{scm_c_string2str (@var{obj}, @var{str}, @var{lenp})}. With the
986 additional @var{str} argument the user can pass a pre-allocated memory
987 chunk or leave it passing NULL.
989 @item @code{gh_get_substr}
990 Use the @code{scm_c_substring2str (@var{obj}, @var{str}, @var{start},
991 @var{len})} function instead.
993 @item @code{gh_symbol2newstr}
994 Use the @code{scm_c_symbol2str (@var{obj}, @var{str}, @var{lenp})} function
995 instead. With the additional @var{str} argument the user can pass a
996 pre-allocated memory chunk or leave it passing NULL.
998 @item @code{gh_scm2chars}
999 Use @code{scm_c_scm2chars} instead.
1001 @item @code{gh_scm2shorts} and @code{gh_scm2longs}
1002 Use @code{scm_c_shorts2scm} and @code{scm_c_longs2scm} instead.
1004 @item @code{gh_scm2floats} and @code{gh_scm2doubles}
1005 Use @code{scm_c_floats2scm} and @code{scm_c_doubles2scm} instead.
1007 @item @code{gh_boolean_p}
1008 Use the @code{SCM_BOOLP} macro instead, or replace @code{gh_boolean_p
1011 SCM_NFALSEP (scm_boolean_p (@var{obj}))
1014 @item @code{gh_symbol_p}
1015 Use the @code{SCM_SYMBOLP} macro instead, or replace @code{gh_symbol_p
1018 SCM_NFALSEP (scm_symbol_p (@var{obj}))
1021 @item @code{gh_char_p}
1022 Use the @code{SCM_CHARP} macro instead, or replace @code{gh_char_p
1025 SCM_NFALSEP (scm_char_p (@var{obj}))
1028 @item @code{gh_vector_p}
1029 Use the @code{SCM_VECTORP} macro instead, or replace @code{gh_vector_p
1032 SCM_NFALSEP (scm_vector_p (@var{obj}))
1035 @item @code{gh_pair_p}
1036 Use the @code{SCM_CONSP} macro instead, or replace @code{gh_pair_p
1039 SCM_NFALSEP (scm_pair_p (@var{obj}))
1042 @item @code{gh_number_p}
1043 Use the @code{SCM_NUMBERP} macro instead, or replace @code{gh_number_p
1046 SCM_NFALSEP (scm_number_p (@var{obj}))
1049 @item @code{gh_string_p}
1050 Use the @code{SCM_STRINGP} macro instead, or replace @code{gh_string_p
1053 SCM_NFALSEP (scm_string_p (@var{obj}))
1056 @item @code{gh_procedure_p}
1057 Replace @code{gh_procedure_p (@var{obj})} by
1059 SCM_NFALSEP (scm_procedure_p (@var{obj}))
1062 @item @code{gh_list_p}
1063 Replace @code{gh_list_p (@var{obj})} by
1065 SCM_NFALSEP (scm_list_p (@var{obj}))
1068 @item @code{gh_inexact_p}
1069 Use the @code{SCM_INEXACTP} macro instead, or replace @code{gh_inexact_p
1072 SCM_NFALSEP (scm_inexact_p (@var{obj}))
1075 @item @code{gh_exact_p}
1076 Replace @code{gh_exact_p (@var{obj})} by
1078 SCM_NFALSEP (scm_exact_p (@var{obj}))
1081 @item @code{gh_eq_p}
1082 Use the @code{SCM_EQ_P} macro instead, or replace @code{gh_eq_p
1083 (@var{x}, @var{y})} by
1085 SCM_NFALSEP (scm_eq_p (@var{x}, @var{y}))
1088 @item @code{gh_eqv_p}
1089 Replace @code{gh_eqv_p (@var{x}, @var{y})} by
1091 SCM_NFALSEP (scm_eqv_p (@var{x}, @var{y}))
1094 @item @code{gh_equal_p}
1095 Replace @code{gh_equal_p (@var{x}, @var{y})} by
1097 SCM_NFALSEP (scm_equal_p (@var{x}, @var{y}))
1100 @item @code{gh_string_equal_p}
1101 Replace @code{gh_string_equal_p (@var{x}, @var{y})} by
1103 SCM_NFALSEP (scm_string_equal_p (@var{x}, @var{y}))
1106 @item @code{gh_null_p}
1107 Use the @code{SCM_NULLP} macro instead, or replace @code{gh_null_p
1110 SCM_NFALSEP (scm_null_p (@var{obj}))
1113 @item @code{gh_cons}
1114 Use @code{scm_cons} instead.
1116 @item @code{gh_car} and @code{gh_cdr}
1117 Use the @code{SCM_CAR} and @code{SCM_CDR} macros instead.
1119 @item @code{gh_cxxr} and @code{gh_cxxxr}
1120 (Where each x is either @samp{a} or @samp{d}.) Use the corresponding
1121 @code{SCM_CXXR} or @code{SCM_CXXXR} macro instead.
1123 @item @code{gh_set_car_x} and @code{gh_set_cdr_x}
1124 Use @code{scm_set_car_x} and @code{scm_set_cdr_x} instead.
1126 @item @code{gh_list}
1127 Use @code{scm_list_n} instead.
1129 @item @code{gh_length}
1130 Replace @code{gh_length (@var{lst})} by
1132 scm_num2ulong (scm_length (@var{lst}), SCM_ARG1, @var{str})
1134 where @var{str} is a C string that describes the context of the call.
1136 @item @code{gh_append}
1137 Use @code{scm_append} instead.
1139 @item @code{gh_append2}, @code{gh_append3}, @code{gh_append4}
1140 Replace @code{gh_append@var{N} (@var{l1}, @dots{}, @var{lN})} by
1142 scm_append (scm_list_n (@var{l1}, @dots{}, @var{lN}, SCM_UNDEFINED))
1145 @item @code{gh_reverse}
1146 Use @code{scm_reverse} instead.
1148 @item @code{gh_list_tail} and @code{gh_list_ref}
1149 Use @code{scm_list_tail} and @code{scm_list_ref} instead.
1151 @item @code{gh_memq}, @code{gh_memv} and @code{gh_member}
1152 Use @code{scm_memq}, @code{scm_memv} and @code{scm_member} instead.
1154 @item @code{gh_assq}, @code{gh_assv} and @code{gh_assoc}
1155 Use @code{scm_assq}, @code{scm_assv} and @code{scm_assoc} instead.
1157 @item @code{gh_make_vector}
1158 Use @code{scm_make_vector} instead.
1160 @item @code{gh_vector} or @code{gh_list_to_vector}
1161 Use @code{scm_vector} instead.
1163 @item @code{gh_vector_ref} and @code{gh_vector_set_x}
1164 Use @code{scm_vector_ref} and @code{scm_vector_set_x} instead.
1166 @item @code{gh_vector_length}
1167 Use the @code{SCM_VECTOR_LENGTH} macro instead.
1169 @item @code{gh_apply}
1170 Use @code{scm_apply_0} instead.