Commit | Line | Data |
---|---|---|
2da09c3f MV |
1 | @c -*-texinfo-*- |
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. | |
6 | ||
a0e07ba4 NJ |
7 | @page |
8 | @node GH | |
9 | @chapter GH: A Portable C to Scheme Interface | |
10 | @cindex libguile - gh | |
11 | @cindex gh | |
12 | @cindex gh - reference manual | |
13 | ||
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. | |
17 | ||
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. | |
22 | ||
23 | @menu | |
24 | * GH deprecation:: Why the GH interface is now deprecated. | |
25 | * gh preliminaries:: | |
26 | * Data types and constants defined by gh:: | |
27 | * Starting and controlling the interpreter:: | |
28 | * Error messages:: | |
29 | * Executing Scheme code:: | |
30 | * Defining new Scheme procedures in C:: | |
31 | * Converting data between C and Scheme:: | |
32 | * Type predicates:: | |
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:: | |
38 | @end menu | |
39 | ||
40 | ||
41 | @node GH deprecation | |
42 | @section Why the GH Interface is Now Deprecated | |
43 | ||
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 | |
58 | projects. | |
59 | ||
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). | |
70 | ||
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. | |
76 | ||
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. | |
82 | ||
83 | ||
84 | @node gh preliminaries | |
85 | @section gh preliminaries | |
86 | ||
87 | To use gh, you must have the following toward the beginning of your C | |
88 | source: | |
89 | @smallexample | |
90 | #include <guile/gh.h> | |
91 | @end smallexample | |
92 | @cindex gh - headers | |
93 | ||
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. | |
97 | @cindex gh - linking | |
98 | ||
99 | ||
100 | @node Data types and constants defined by gh | |
101 | @section Data types and constants defined by gh | |
102 | @cindex libguile - data types | |
103 | ||
104 | The following C constants and data types are defined in gh: | |
105 | ||
395b0a34 | 106 | @code{SCM} is a C data type used to store all Scheme data, no matter what the |
a0e07ba4 NJ |
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.] | |
a0e07ba4 NJ |
110 | |
111 | @defvr Constant SCM_BOOL_T | |
112 | @defvrx Constant SCM_BOOL_F | |
113 | The @emph{Scheme} values returned by many boolean procedures in | |
114 | libguile. | |
115 | ||
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()) @{ ... @}} | |
122 | @end defvr | |
123 | ||
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. | |
128 | @end defvr | |
129 | ||
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()}. | |
135 | @end defvr | |
136 | ||
137 | ||
138 | @node Starting and controlling the interpreter | |
139 | @section Starting and controlling the interpreter | |
140 | @cindex libguile - start interpreter | |
141 | ||
142 | In almost every case, your first @code{gh_} call will be: | |
143 | ||
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}. | |
149 | ||
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. | |
153 | @end deftypefun | |
154 | ||
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 | |
85a9b4ed | 157 | be controlled by a Scheme read-eval-print loop. |
a0e07ba4 NJ |
158 | @end deftypefun |
159 | ||
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: | |
164 | ||
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 | |
168 | invoked. | |
169 | ||
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. | |
173 | ||
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. | |
178 | @end deftypefun | |
179 | ||
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: | |
185 | ||
186 | @smallexample | |
187 | #include <guile/gh.h> | |
188 | #include <gsl_ran.h> | |
189 | ||
190 | /* random number suite */ | |
191 | SCM gw_ran_seed(SCM s) | |
192 | @{ | |
193 | gsl_ran_seed(gh_scm2int(s)); | |
194 | return SCM_UNSPECIFIED; | |
195 | @} | |
196 | ||
197 | SCM gw_ran_random() | |
198 | @{ | |
199 | SCM x; | |
200 | ||
201 | x = gh_ulong2scm(gsl_ran_random()); | |
202 | return x; | |
203 | @} | |
204 | ||
205 | SCM gw_ran_uniform() | |
206 | @{ | |
207 | SCM x; | |
208 | ||
209 | x = gh_double2scm(gsl_ran_uniform()); | |
210 | return x; | |
211 | @} | |
212 | SCM gw_ran_max() | |
213 | @{ | |
214 | return gh_double2scm(gsl_ran_max()); | |
215 | @} | |
216 | ||
217 | void | |
218 | init_gsl() | |
219 | @{ | |
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); | |
225 | @} | |
226 | ||
227 | void | |
228 | main_prog (int argc, char *argv[]) | |
229 | @{ | |
230 | init_gsl(); | |
231 | ||
232 | gh_repl(argc, argv); | |
233 | @} | |
234 | ||
235 | int | |
236 | main (int argc, char *argv[]) | |
237 | @{ | |
238 | gh_enter (argc, argv, main_prog); | |
239 | @} | |
240 | @end smallexample | |
241 | ||
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}. | |
244 | ||
245 | The resulting program @file{guile-gsl} would have new primitive | |
246 | procedures @code{gsl-ran-random}, @code{gsl-ran-gaussian} and so forth. | |
247 | ||
248 | ||
249 | @node Error messages | |
250 | @section Error messages | |
251 | @cindex libguile - error messages | |
252 | @cindex error messages in libguile | |
253 | ||
254 | [FIXME: need to fill this based on Jim's new mechanism] | |
255 | ||
256 | ||
257 | @node Executing Scheme code | |
258 | @section Executing Scheme code | |
259 | @cindex libguile - executing Scheme | |
260 | @cindex executing Scheme | |
261 | ||
262 | Once you have an interpreter running, you can ask it to evaluate Scheme | |
263 | code. There are two calls that implement this: | |
264 | ||
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. | |
268 | ||
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()}. | |
273 | @end deftypefun | |
274 | ||
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}. | |
280 | ||
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 | |
284 | closely. | |
285 | @end deftypefun | |
286 | ||
287 | ||
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 | |
295 | ||
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 | |
298 | ||
299 | ||
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. | |
305 | ||
306 | When the @var{restp} parameter is 1, the procedure takes a final | |
307 | argument: a list of remaining parameters. | |
308 | ||
309 | @code{gh_new_procedure} returns an SCM value representing the procedure. | |
310 | ||
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. | |
315 | ||
316 | Examples of C functions used as new Scheme primitives can be found in | |
317 | the sample programs @code{learn0} and @code{learn1}. | |
318 | @end deftypefn | |
319 | ||
320 | @end deftypefn | |
321 | ||
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. | |
325 | ||
e05b02b6 | 326 | @strong{NB:} what about documentation strings? |
a0e07ba4 NJ |
327 | |
328 | @cartouche | |
329 | There are several important considerations to be made when writing the C | |
330 | routine @code{(*fn)()}. | |
331 | ||
332 | First of all the C routine has to return type @code{SCM}. | |
333 | ||
85a9b4ed | 334 | Second, all arguments passed to the C function will be of type |
a0e07ba4 NJ |
335 | @code{SCM}. |
336 | ||
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{} | |
341 | ||
342 | Fourth: to get around the latter issue, you can use | |
343 | @code{GH_DEFER_INTS} and @code{GH_ALLOW_INTS}. | |
344 | @end cartouche | |
345 | ||
346 | @defmac GH_DEFER_INTS | |
347 | @defmacx GH_ALLOW_INTS | |
85a9b4ed | 348 | These macros disable and re-enable Scheme's flow control. They |
a0e07ba4 NJ |
349 | @end defmac |
350 | ||
351 | ||
352 | @c [??? have to do this right; maybe using subsections, or maybe creating a | |
353 | @c section called Flow control issues...] | |
354 | ||
355 | @c [??? Go into exhaustive detail with examples of the various possible | |
356 | @c combinations of required and optional args...] | |
357 | ||
358 | ||
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 | |
364 | ||
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}. | |
368 | ||
369 | ||
370 | @menu | |
371 | * C to Scheme:: | |
372 | * Scheme to C:: | |
373 | @end menu | |
374 | ||
375 | @node C to Scheme | |
376 | @subsection C to Scheme | |
377 | ||
378 | @deftypefun SCM gh_bool2scm (int @var{x}) | |
379 | Returns @code{#f} if @var{x} is zero, @code{#t} otherwise. | |
380 | @end deftypefun | |
381 | ||
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}. | |
387 | @end deftypefun | |
388 | ||
389 | @deftypefun SCM gh_str2scm (char *@var{s}, int @var{len}) | |
390 | Returns a new Scheme string with the (not necessarily null-terminated) C | |
391 | array @var{s} data. | |
392 | @end deftypefun | |
393 | ||
394 | @deftypefun SCM gh_str02scm (char *@var{s}) | |
395 | Returns a new Scheme string with the null-terminated C string @var{s} | |
396 | data. | |
397 | @end deftypefun | |
398 | ||
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. | |
403 | ||
404 | If @var{start} + @var{len} is off the end of @var{dst}, signal an | |
405 | out-of-range error. | |
406 | @end deftypefun | |
407 | ||
408 | @deftypefun SCM gh_symbol2scm (char *@var{name}) | |
409 | Given a null-terminated string @var{name}, return the symbol with that | |
410 | name. | |
411 | @end deftypefun | |
412 | ||
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 | |
416 | location @var{dptr}. | |
417 | @end deftypefun | |
418 | ||
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}. | |
427 | @end deftypefun | |
428 | ||
429 | ||
430 | ||
431 | @node Scheme to C | |
432 | @subsection Scheme to C | |
433 | ||
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. | |
440 | @end deftypefun | |
441 | ||
fe2a94df | 442 | @deftypefun {char *} gh_scm2newstr (SCM @var{str}, size_t *@var{lenp}) |
a0e07ba4 NJ |
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. | |
446 | ||
447 | This function uses malloc to obtain storage for the copy; the caller is | |
448 | responsible for freeing it. | |
449 | ||
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). | |
455 | @end deftypefun | |
456 | ||
457 | ||
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. | |
463 | ||
464 | If @var{start} + @var{len} is off the end of @var{src}, signal an | |
465 | out-of-range error. | |
466 | @end deftypefun | |
467 | ||
fe2a94df | 468 | @deftypefun {char *} gh_symbol2newstr (SCM @var{sym}, int *@var{lenp}) |
a0e07ba4 NJ |
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}}. | |
472 | ||
473 | This function uses malloc to obtain storage for the returned string; the | |
474 | caller is responsible for freeing it. | |
475 | @end deftypefun | |
476 | ||
fe2a94df KR |
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}) | |
a0e07ba4 NJ |
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 | |
484 | enough. | |
485 | ||
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. | |
490 | ||
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. | |
494 | @end deftypefun | |
495 | ||
496 | ||
497 | @node Type predicates | |
498 | @section Type predicates | |
499 | ||
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}. | |
503 | ||
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(...)}. | |
508 | ||
509 | @deftypefun int gh_boolean_p (SCM @var{val}) | |
510 | Returns 1 if @var{val} is a boolean, 0 otherwise. | |
511 | @end deftypefun | |
512 | ||
513 | @deftypefun int gh_symbol_p (SCM @var{val}) | |
514 | Returns 1 if @var{val} is a symbol, 0 otherwise. | |
515 | @end deftypefun | |
516 | ||
517 | @deftypefun int gh_char_p (SCM @var{val}) | |
518 | Returns 1 if @var{val} is a char, 0 otherwise. | |
519 | @end deftypefun | |
520 | ||
521 | @deftypefun int gh_vector_p (SCM @var{val}) | |
522 | Returns 1 if @var{val} is a vector, 0 otherwise. | |
523 | @end deftypefun | |
524 | ||
525 | @deftypefun int gh_pair_p (SCM @var{val}) | |
526 | Returns 1 if @var{val} is a pair, 0 otherwise. | |
527 | @end deftypefun | |
528 | ||
529 | @deftypefun int gh_procedure_p (SCM @var{val}) | |
530 | Returns 1 if @var{val} is a procedure, 0 otherwise. | |
531 | @end deftypefun | |
532 | ||
533 | @deftypefun int gh_list_p (SCM @var{val}) | |
534 | Returns 1 if @var{val} is a list, 0 otherwise. | |
535 | @end deftypefun | |
536 | ||
537 | @deftypefun int gh_inexact_p (SCM @var{val}) | |
538 | Returns 1 if @var{val} is an inexact number, 0 otherwise. | |
539 | @end deftypefun | |
540 | ||
541 | @deftypefun int gh_exact_p (SCM @var{val}) | |
542 | Returns 1 if @var{val} is an exact number, 0 otherwise. | |
543 | @end deftypefun | |
544 | ||
545 | ||
546 | @node Equality predicates | |
547 | @section Equality predicates | |
548 | ||
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}. | |
552 | ||
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(...)}. | |
557 | ||
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. | |
561 | @end deftypefun | |
562 | ||
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. | |
566 | @end deftypefun | |
567 | ||
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. | |
571 | @end deftypefun | |
572 | ||
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. | |
575 | @end deftypefun | |
576 | ||
577 | @deftypefun int gh_null_p (SCM @var{l}) | |
578 | Returns 1 if @var{l} is an empty list or pair; 0 otherwise. | |
579 | @end deftypefun | |
580 | ||
581 | ||
582 | @node Memory allocation and garbage collection | |
583 | @section Memory allocation and garbage collection | |
584 | ||
585 | @c [FIXME: flesh this out with some description of garbage collection in | |
586 | @c scm/guile] | |
587 | ||
588 | @c @deftypefun SCM gh_mkarray (int size) | |
589 | @c Allocate memory for a Scheme object in a garbage-collector-friendly | |
590 | @c manner. | |
591 | @c @end deftypefun | |
592 | ||
593 | ||
594 | @node Calling Scheme procedures from C | |
595 | @section Calling Scheme procedures from C | |
596 | ||
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. | |
600 | ||
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. | |
606 | ||
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. | |
610 | @end deftypefun | |
611 | ||
612 | @heading Pairs and lists | |
613 | ||
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 | |
7395c9cb | 618 | @code{scm_list_n()}. |
a0e07ba4 NJ |
619 | @end deftypefun |
620 | ||
621 | @deftypefun SCM gh_car (SCM @var{obj}) | |
622 | @deftypefunx SCM gh_cdr (SCM @var{obj}) | |
623 | @dots{} | |
624 | ||
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{} | |
627 | @end deftypefun | |
628 | ||
218b088e | 629 | @deftypefun SCM gh_set_car_x (SCM @var{pair}, SCM @var{value}) |
a0e07ba4 NJ |
630 | Modifies the CAR of @var{pair} to be @var{value}. This is equivalent to |
631 | the Scheme procedure @code{(set-car! ...)}. | |
632 | @end deftypefun | |
633 | ||
218b088e | 634 | @deftypefun SCM gh_set_cdr_x (SCM @var{pair}, SCM @var{value}) |
a0e07ba4 NJ |
635 | Modifies the CDR of @var{pair} to be @var{value}. This is equivalent to |
636 | the Scheme procedure @code{(set-cdr! ...)}. | |
637 | @end deftypefun | |
638 | ||
639 | @deftypefun {unsigned long} gh_length (SCM @var{ls}) | |
640 | Returns the length of the list. | |
641 | @end deftypefun | |
642 | ||
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. | |
650 | ||
651 | A typical invocation of @code{gh_append()} to append 5 lists together | |
652 | would be | |
653 | @smallexample | |
654 | gh_append(gh_list(l1, l2, l3, l4, l5, SCM_UNDEFINED)); | |
655 | @end smallexample | |
656 | ||
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()}. | |
661 | @end deftypefun | |
662 | ||
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()}. | |
667 | @end deftypefun | |
668 | ||
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. | |
671 | @end deftypefun | |
672 | ||
673 | @deftypefun SCM gh_list_ref (SCM @var{ls}, SCM @var{k}) | |
674 | Returns the @var{k}th element of the list @var{ls}. | |
675 | @end deftypefun | |
676 | ||
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. | |
684 | ||
685 | If @var{x} does not appear in @var{ls}, the value @code{SCM_BOOL_F} (not | |
686 | the empty list) is returned. | |
687 | ||
688 | Note that these functions are implemented as macros which call | |
689 | @code{scm_memq()}, @code{scm_memv()} and @code{scm_member()} | |
690 | respectively. | |
691 | @end deftypefun | |
692 | ||
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 | |
698 | that pair. | |
699 | ||
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. | |
702 | ||
703 | Note that these functions are implemented as macros which call | |
704 | @code{scm_assq()}, @code{scm_assv()} and @code{scm_assoc()} | |
705 | respectively. | |
706 | @end deftypefun | |
707 | ||
708 | ||
709 | @heading Symbols | |
710 | ||
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. | |
715 | @c @end deftypefun | |
716 | ||
717 | ||
718 | @heading Vectors | |
719 | ||
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. | |
729 | ||
730 | The correspondence is not perfect for @code{gh_vector}: this routine | |
85a9b4ed | 731 | takes a list @var{ls} instead of the individual list elements, thus |
a0e07ba4 NJ |
732 | making it identical to @code{gh_list_to_vector}. |
733 | ||
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. | |
736 | @end deftypefun | |
737 | ||
738 | ||
739 | @heading Procedures | |
740 | ||
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. | |
752 | @c | |
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: | |
755 | @c | |
756 | @c @example | |
757 | @c SCM scm_read_line (SCM port, SCM handle_delim); | |
758 | @c gh_make_subr (scm_read_line, 0, 2, 0, "read-line"); | |
759 | @c @end example | |
760 | @c | |
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. | |
769 | @c @end deftypefun | |
770 | ||
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. | |
774 | @end deftypefun | |
775 | ||
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. | |
784 | @end deftypefun | |
785 | ||
786 | ||
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. | |
791 | @end deftypefun | |
792 | ||
793 | @c [FIXME: must add the I/O section in gscm.h] | |
794 | ||
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?} | |
799 | predicates. | |
800 | @end deftypefun | |
801 | ||
802 | @deftypefun int gh_obj_length (SCM @var{obj}) | |
803 | Returns the raw object length. | |
804 | @end deftypefun | |
805 | ||
806 | @heading Data lookup | |
807 | ||
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 | |
810 | here. | |
811 | ||
812 | @smallexample | |
813 | /* Data lookups between C and Scheme | |
814 | ||
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 | |
85a9b4ed | 817 | gh_module_lookup checks the module name space specified by the |
a0e07ba4 NJ |
818 | `vec' argument. |
819 | ||
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? | |
824 | -twp] */ | |
825 | @end smallexample | |
826 | ||
827 | ||
828 | @node Mixing gh and scm APIs | |
829 | @section Mixing gh and scm APIs | |
830 | ||
831 | ||
832 | @node scm transition summary | |
833 | @section Transitioning to the scm Interface | |
834 | ||
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. | |
839 | ||
840 | @table @asis | |
841 | @item Header file | |
842 | Use @code{#include <libguile.h>} instead of @code{#include | |
843 | <guile/gh.h>}. | |
844 | ||
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 | |
848 | ||
849 | @smallexample | |
850 | $(CC) -o prog.o -c prog.c `guile-config compile` | |
851 | @end smallexample | |
852 | ||
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 | |
85a9b4ed | 857 | options explicitly. A linker command like |
a0e07ba4 NJ |
858 | |
859 | @smallexample | |
860 | $(CC) -o prog prog.o `guile-config link` | |
861 | @end smallexample | |
862 | ||
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 | |
865 | and the link stage. | |
866 | ||
867 | @item The @code{SCM} type | |
868 | No change: the scm interface also uses this type to represent an | |
869 | arbitrary Scheme value. | |
870 | ||
871 | @item @code{SCM_BOOL_F} and @code{SCM_BOOL_T} | |
872 | No change. | |
873 | ||
874 | @item @code{SCM_UNSPECIFIED} and @code{SCM_UNDEFINED} | |
875 | No change. | |
876 | ||
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. | |
883 | ||
884 | @item @code{gh_repl} | |
885 | Use @code{scm_shell} instead. | |
886 | ||
887 | @item @code{gh_init} | |
888 | Use @code{scm_init_guile} instead. | |
889 | ||
890 | @item @code{gh_eval_str} | |
891 | Use @code{scm_c_eval_string} instead. | |
892 | ||
893 | @item @code{gh_eval_file} or @code{gh_load} | |
894 | Use @code{scm_c_primitive_load} instead. | |
895 | ||
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 | |
900 | example. | |
901 | ||
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;}. | |
905 | ||
906 | @item @code{gh_bool2scm} | |
907 | Use @code{SCM_BOOL} instead. | |
908 | ||
909 | @item @code{gh_ulong2scm} | |
910 | Use @code{scm_ulong2num} instead. | |
911 | ||
912 | @item @code{gh_long2scm} | |
913 | Use @code{scm_long2num} instead. | |
914 | ||
915 | @item @code{gh_double2scm} | |
916 | Use @code{scm_make_real} instead. | |
917 | ||
918 | @item @code{gh_char2scm} | |
919 | Use @code{SCM_MAKE_CHAR} instead. | |
920 | ||
921 | @item @code{gh_str2scm} | |
922 | Use @code{scm_mem2string} instead. | |
923 | ||
924 | @item @code{gh_str02scm} | |
925 | Use @code{scm_makfrom0str} instead. | |
926 | ||
927 | @item @code{gh_set_substr} | |
928 | No direct scm equivalent. [FIXME] | |
929 | ||
930 | @item @code{gh_symbol2scm} | |
931 | Use @code{scm_str2symbol} instead. [FIXME: inconsistent naming, | |
932 | should be @code{scm_str02symbol}.] | |
933 | ||
934 | @item @code{gh_ints2scm} and @code{gh_doubles2scm} | |
edb810bb | 935 | Use @code{scm_c_ints2scm} and @code{scm_c_doubles2scm} instead. |
a0e07ba4 NJ |
936 | |
937 | @item @code{gh_chars2byvect} and @code{gh_shorts2svect} | |
edb810bb | 938 | Use @code{scm_c_chars2byvect} and @code{scm_c_shorts2svect} instead. |
a0e07ba4 NJ |
939 | |
940 | @item @code{gh_longs2ivect} and @code{gh_ulongs2uvect} | |
edb810bb | 941 | Use @code{scm_c_longs2ivect} and @code{scm_c_ulongs2uvect} instead. |
a0e07ba4 NJ |
942 | |
943 | @item @code{gh_floats2fvect} and @code{gh_doubles2dvect} | |
edb810bb | 944 | Use @code{scm_c_floats2fvect} and @code{scm_c_doubles2dvect} instead. |
a0e07ba4 NJ |
945 | |
946 | @item @code{gh_scm2bool} | |
947 | Use @code{SCM_NFALSEP} instead. | |
948 | ||
949 | @item @code{gh_scm2int} | |
950 | Replace @code{gh_scm2int (@var{obj})} by | |
951 | @example | |
952 | scm_num2int (@var{obj}, SCM_ARG1, @var{str}) | |
953 | @end example | |
954 | where @var{str} is a C string that describes the context of the call. | |
955 | ||
956 | @item @code{gh_scm2ulong} | |
957 | Replace @code{gh_scm2ulong (@var{obj})} by | |
958 | @example | |
959 | scm_num2ulong (@var{obj}, SCM_ARG1, @var{str}) | |
960 | @end example | |
961 | where @var{str} is a C string that describes the context of the call. | |
962 | ||
963 | @item @code{gh_scm2long} | |
964 | Replace @code{gh_scm2long (@var{obj})} by | |
965 | @example | |
966 | scm_num2long (@var{obj}, SCM_ARG1, @var{str}) | |
967 | @end example | |
968 | where @var{str} is a C string that describes the context of the call. | |
969 | ||
970 | @item @code{gh_scm2double} | |
971 | Replace @code{gh_scm2double (@var{obj})} by | |
972 | @example | |
973 | scm_num2dbl (@var{obj}, @var{str}) | |
974 | @end example | |
975 | where @var{str} is a C string that describes the context of the call. | |
976 | ||
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. | |
982 | ||
983 | @item @code{gh_scm2newstr} | |
f74fa0a0 SJ |
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. | |
a0e07ba4 NJ |
988 | |
989 | @item @code{gh_get_substr} | |
f74fa0a0 SJ |
990 | Use the @code{scm_c_substring2str (@var{obj}, @var{str}, @var{start}, |
991 | @var{len})} function instead. | |
a0e07ba4 NJ |
992 | |
993 | @item @code{gh_symbol2newstr} | |
f74fa0a0 SJ |
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. | |
a0e07ba4 NJ |
997 | |
998 | @item @code{gh_scm2chars} | |
edb810bb | 999 | Use @code{scm_c_scm2chars} instead. |
a0e07ba4 NJ |
1000 | |
1001 | @item @code{gh_scm2shorts} and @code{gh_scm2longs} | |
edb810bb | 1002 | Use @code{scm_c_shorts2scm} and @code{scm_c_longs2scm} instead. |
a0e07ba4 NJ |
1003 | |
1004 | @item @code{gh_scm2floats} and @code{gh_scm2doubles} | |
edb810bb | 1005 | Use @code{scm_c_floats2scm} and @code{scm_c_doubles2scm} instead. |
a0e07ba4 NJ |
1006 | |
1007 | @item @code{gh_boolean_p} | |
1008 | Use the @code{SCM_BOOLP} macro instead, or replace @code{gh_boolean_p | |
1009 | (@var{obj})} by | |
1010 | @example | |
1011 | SCM_NFALSEP (scm_boolean_p (@var{obj})) | |
1012 | @end example | |
1013 | ||
1014 | @item @code{gh_symbol_p} | |
1015 | Use the @code{SCM_SYMBOLP} macro instead, or replace @code{gh_symbol_p | |
1016 | (@var{obj})} by | |
1017 | @example | |
1018 | SCM_NFALSEP (scm_symbol_p (@var{obj})) | |
1019 | @end example | |
1020 | ||
1021 | @item @code{gh_char_p} | |
1022 | Use the @code{SCM_CHARP} macro instead, or replace @code{gh_char_p | |
1023 | (@var{obj})} by | |
1024 | @example | |
1025 | SCM_NFALSEP (scm_char_p (@var{obj})) | |
1026 | @end example | |
1027 | ||
1028 | @item @code{gh_vector_p} | |
1029 | Use the @code{SCM_VECTORP} macro instead, or replace @code{gh_vector_p | |
1030 | (@var{obj})} by | |
1031 | @example | |
1032 | SCM_NFALSEP (scm_vector_p (@var{obj})) | |
1033 | @end example | |
1034 | ||
1035 | @item @code{gh_pair_p} | |
1036 | Use the @code{SCM_CONSP} macro instead, or replace @code{gh_pair_p | |
1037 | (@var{obj})} by | |
1038 | @example | |
1039 | SCM_NFALSEP (scm_pair_p (@var{obj})) | |
1040 | @end example | |
1041 | ||
1042 | @item @code{gh_number_p} | |
1043 | Use the @code{SCM_NUMBERP} macro instead, or replace @code{gh_number_p | |
1044 | (@var{obj})} by | |
1045 | @example | |
1046 | SCM_NFALSEP (scm_number_p (@var{obj})) | |
1047 | @end example | |
1048 | ||
1049 | @item @code{gh_string_p} | |
1050 | Use the @code{SCM_STRINGP} macro instead, or replace @code{gh_string_p | |
1051 | (@var{obj})} by | |
1052 | @example | |
1053 | SCM_NFALSEP (scm_string_p (@var{obj})) | |
1054 | @end example | |
1055 | ||
1056 | @item @code{gh_procedure_p} | |
1057 | Replace @code{gh_procedure_p (@var{obj})} by | |
1058 | @example | |
1059 | SCM_NFALSEP (scm_procedure_p (@var{obj})) | |
1060 | @end example | |
1061 | ||
1062 | @item @code{gh_list_p} | |
1063 | Replace @code{gh_list_p (@var{obj})} by | |
1064 | @example | |
1065 | SCM_NFALSEP (scm_list_p (@var{obj})) | |
1066 | @end example | |
1067 | ||
1068 | @item @code{gh_inexact_p} | |
1069 | Use the @code{SCM_INEXACTP} macro instead, or replace @code{gh_inexact_p | |
1070 | (@var{obj})} by | |
1071 | @example | |
1072 | SCM_NFALSEP (scm_inexact_p (@var{obj})) | |
1073 | @end example | |
1074 | ||
1075 | @item @code{gh_exact_p} | |
1076 | Replace @code{gh_exact_p (@var{obj})} by | |
1077 | @example | |
1078 | SCM_NFALSEP (scm_exact_p (@var{obj})) | |
1079 | @end example | |
1080 | ||
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 | |
1084 | @example | |
1085 | SCM_NFALSEP (scm_eq_p (@var{x}, @var{y})) | |
1086 | @end example | |
1087 | ||
1088 | @item @code{gh_eqv_p} | |
1089 | Replace @code{gh_eqv_p (@var{x}, @var{y})} by | |
1090 | @example | |
1091 | SCM_NFALSEP (scm_eqv_p (@var{x}, @var{y})) | |
1092 | @end example | |
1093 | ||
1094 | @item @code{gh_equal_p} | |
1095 | Replace @code{gh_equal_p (@var{x}, @var{y})} by | |
1096 | @example | |
1097 | SCM_NFALSEP (scm_equal_p (@var{x}, @var{y})) | |
1098 | @end example | |
1099 | ||
1100 | @item @code{gh_string_equal_p} | |
1101 | Replace @code{gh_string_equal_p (@var{x}, @var{y})} by | |
1102 | @example | |
1103 | SCM_NFALSEP (scm_string_equal_p (@var{x}, @var{y})) | |
1104 | @end example | |
1105 | ||
1106 | @item @code{gh_null_p} | |
1107 | Use the @code{SCM_NULLP} macro instead, or replace @code{gh_null_p | |
1108 | (@var{obj})} by | |
1109 | @example | |
1110 | SCM_NFALSEP (scm_null_p (@var{obj})) | |
1111 | @end example | |
1112 | ||
1113 | @item @code{gh_cons} | |
1114 | Use @code{scm_cons} instead. | |
1115 | ||
1116 | @item @code{gh_car} and @code{gh_cdr} | |
1117 | Use the @code{SCM_CAR} and @code{SCM_CDR} macros instead. | |
1118 | ||
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. | |
1122 | ||
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. | |
1125 | ||
1126 | @item @code{gh_list} | |
7395c9cb | 1127 | Use @code{scm_list_n} instead. |
a0e07ba4 NJ |
1128 | |
1129 | @item @code{gh_length} | |
1130 | Replace @code{gh_length (@var{lst})} by | |
1131 | @example | |
1132 | scm_num2ulong (scm_length (@var{lst}), SCM_ARG1, @var{str}) | |
1133 | @end example | |
1134 | where @var{str} is a C string that describes the context of the call. | |
1135 | ||
1136 | @item @code{gh_append} | |
1137 | Use @code{scm_append} instead. | |
1138 | ||
1139 | @item @code{gh_append2}, @code{gh_append3}, @code{gh_append4} | |
1140 | Replace @code{gh_append@var{N} (@var{l1}, @dots{}, @var{lN})} by | |
1141 | @example | |
7395c9cb | 1142 | scm_append (scm_list_n (@var{l1}, @dots{}, @var{lN}, SCM_UNDEFINED)) |
a0e07ba4 NJ |
1143 | @end example |
1144 | ||
1145 | @item @code{gh_reverse} | |
1146 | Use @code{scm_reverse} instead. | |
1147 | ||
1148 | @item @code{gh_list_tail} and @code{gh_list_ref} | |
1149 | Use @code{scm_list_tail} and @code{scm_list_ref} instead. | |
1150 | ||
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. | |
1153 | ||
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. | |
1156 | ||
1157 | @item @code{gh_make_vector} | |
1158 | Use @code{scm_make_vector} instead. | |
1159 | ||
1160 | @item @code{gh_vector} or @code{gh_list_to_vector} | |
1161 | Use @code{scm_vector} instead. | |
1162 | ||
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. | |
1165 | ||
1166 | @item @code{gh_vector_length} | |
1167 | Use the @code{SCM_VECTOR_LENGTH} macro instead. | |
1168 | ||
1169 | @item @code{gh_apply} | |
7395c9cb | 1170 | Use @code{scm_apply_0} instead. |
a0e07ba4 NJ |
1171 | |
1172 | @end table |