| 1 | @page |
| 2 | @node GH |
| 3 | @chapter GH: A Portable C to Scheme Interface |
| 4 | @cindex libguile - gh |
| 5 | @cindex gh |
| 6 | @cindex gh - reference manual |
| 7 | |
| 8 | This chapter shows how to use the GH interface to call Guile from your |
| 9 | application's C code, and to add new Scheme level procedures to Guile |
| 10 | whose behaviour is specified by application specific code written in C. |
| 11 | |
| 12 | Note, however, that the GH interface is now deprecated, and developers |
| 13 | are encouraged to switch to using the scm interface instead. Therefore, |
| 14 | for each GH feature, this chapter should also document how to achieve |
| 15 | the same result using the scm interface. |
| 16 | |
| 17 | @menu |
| 18 | * GH deprecation:: Why the GH interface is now deprecated. |
| 19 | * gh preliminaries:: |
| 20 | * Data types and constants defined by gh:: |
| 21 | * Starting and controlling the interpreter:: |
| 22 | * Error messages:: |
| 23 | * Executing Scheme code:: |
| 24 | * Defining new Scheme procedures in C:: |
| 25 | * Converting data between C and Scheme:: |
| 26 | * Type predicates:: |
| 27 | * Equality predicates:: |
| 28 | * Memory allocation and garbage collection:: |
| 29 | * Calling Scheme procedures from C:: |
| 30 | * Mixing gh and scm APIs:: |
| 31 | * scm transition summary:: |
| 32 | @end menu |
| 33 | |
| 34 | |
| 35 | @node GH deprecation |
| 36 | @section Why the GH Interface is Now Deprecated |
| 37 | |
| 38 | Historically, the GH interface was the product of a practical problem |
| 39 | and a neat idea. The practical problem was that the interface of the |
| 40 | @code{scm_} functions with which Guile itself was written (inherited |
| 41 | from Aubrey Jaffer's SCM) was so closely tied to the (rather arcane) |
| 42 | details of the internal data representation that it was extremely |
| 43 | difficult to write a Guile extension using these functions. The neat |
| 44 | idea was to define a high level language extension interface in such a |
| 45 | way that other extension language projects, not just Guile, would be |
| 46 | able to provide an implementation of that interface; then applications |
| 47 | using this interface could be compiled with whichever of the various |
| 48 | available implementations they chose. So the GH interface was created, |
| 49 | and advertised both as the recommended interface for application |
| 50 | developers wishing to use Guile, and as a portable high level interface |
| 51 | that could theoretically be implemented by other extension language |
| 52 | projects. |
| 53 | |
| 54 | Time passed, and various things changed. Crucially, an enormous number |
| 55 | of improvements were made to the @code{scm_} interface that Guile itself |
| 56 | uses in its implementation, with the result that it is now both easy and |
| 57 | comfortable to write a Guile extension with this interface. At the same |
| 58 | time, the contents of the GH interface were somewhat neglected by the |
| 59 | core Guile developers, such that some key operations --- such as smob |
| 60 | creation and management --- are simply not possible using GH alone. |
| 61 | Finally, the idea of multiple implementations of the GH interface did |
| 62 | not really crystallize (apart, I believe, from a short lived |
| 63 | implementation by the MzScheme project). |
| 64 | |
| 65 | For all these reasons, the Guile developers have decided to deprecate |
| 66 | the GH interface --- which means that support for GH will be completely |
| 67 | removed after the next few releases --- and to focus only on the |
| 68 | @code{scm_} interface, with additions to ensure that it is as easy to |
| 69 | use in all respects as GH was. |
| 70 | |
| 71 | It remains an open question whether a deep kind of interface portability |
| 72 | would be useful for extension language-based applications, and it may |
| 73 | still be an interesting project to attempt to define a corresponding |
| 74 | GH-like interface, but the Guile developers no longer plan to try to do |
| 75 | this as part of the core Guile project. |
| 76 | |
| 77 | |
| 78 | @node gh preliminaries |
| 79 | @section gh preliminaries |
| 80 | |
| 81 | To use gh, you must have the following toward the beginning of your C |
| 82 | source: |
| 83 | @smallexample |
| 84 | #include <guile/gh.h> |
| 85 | @end smallexample |
| 86 | @cindex gh - headers |
| 87 | |
| 88 | When you link, you will have to add at least @code{-lguile} to the list |
| 89 | of libraries. If you are using more of Guile than the basic Scheme |
| 90 | interpreter, you will have to add more libraries. |
| 91 | @cindex gh - linking |
| 92 | |
| 93 | |
| 94 | @node Data types and constants defined by gh |
| 95 | @section Data types and constants defined by gh |
| 96 | @cindex libguile - data types |
| 97 | |
| 98 | The following C constants and data types are defined in gh: |
| 99 | |
| 100 | @code{SCM} is a C data type used to store all Scheme data, no matter what the |
| 101 | Scheme type. Values are converted between C data types and the SCM type |
| 102 | with utility functions described below (@pxref{Converting data between C |
| 103 | and Scheme}). [FIXME: put in references to Jim's essay and so forth.] |
| 104 | |
| 105 | @defvr Constant SCM_BOOL_T |
| 106 | @defvrx Constant SCM_BOOL_F |
| 107 | The @emph{Scheme} values returned by many boolean procedures in |
| 108 | libguile. |
| 109 | |
| 110 | This can cause confusion because they are different from 0 and 1. In |
| 111 | testing a boolean function in libguile programming, you must always make |
| 112 | sure that you check the spec: @code{gh_} and @code{scm_} functions will |
| 113 | usually return @code{SCM_BOOL_T} and @code{SCM_BOOL_F}, but other C |
| 114 | functions usually can be tested against 0 and 1, so programmers' fingers |
| 115 | tend to just type @code{if (boolean_function()) @{ ... @}} |
| 116 | @end defvr |
| 117 | |
| 118 | @defvr Constant SCM_UNSPECIFIED |
| 119 | This is a SCM value that is not the same as any legal Scheme value. It |
| 120 | is the value that a Scheme function returns when its specification says |
| 121 | that its return value is unspecified. |
| 122 | @end defvr |
| 123 | |
| 124 | @defvr Constant SCM_UNDEFINED |
| 125 | This is another SCM value that is not the same as any legal Scheme |
| 126 | value. It is the value used to mark variables that do not yet have a |
| 127 | value, and it is also used in C to terminate functions with variable |
| 128 | numbers of arguments, such as @code{gh_list()}. |
| 129 | @end defvr |
| 130 | |
| 131 | |
| 132 | @node Starting and controlling the interpreter |
| 133 | @section Starting and controlling the interpreter |
| 134 | @cindex libguile - start interpreter |
| 135 | |
| 136 | In almost every case, your first @code{gh_} call will be: |
| 137 | |
| 138 | @deftypefun void gh_enter (int @var{argc}, char *@var{argv}[], void (*@var{main_prog})()) |
| 139 | Starts up a Scheme interpreter with all the builtin Scheme primitives. |
| 140 | @code{gh_enter()} never exits, and the user's code should all be in the |
| 141 | @code{@var{main_prog}()} function. @code{argc} and @code{argv} will be |
| 142 | passed to @var{main_prog}. |
| 143 | |
| 144 | @deftypefun void main_prog (int @var{argc}, char *@var{argv}[]) |
| 145 | This is the user's main program. It will be invoked by |
| 146 | @code{gh_enter()} after Guile has been started up. |
| 147 | @end deftypefun |
| 148 | |
| 149 | Note that you can use @code{gh_repl} inside @code{gh_enter} (in other |
| 150 | words, inside the code for @code{main-prog}) if you want the program to |
| 151 | be controlled by a Scheme read-eval-print loop. |
| 152 | @end deftypefun |
| 153 | |
| 154 | @cindex read eval print loop -- from the gh_ interface |
| 155 | @cindex REPL -- from the gh_ interface |
| 156 | A convenience routine which enters the Guile interpreter with the |
| 157 | standard Guile read-eval-print loop (@dfn{REPL}) is: |
| 158 | |
| 159 | @deftypefun void gh_repl (int @var{argc}, char *@var{argv}[]) |
| 160 | Enters the Scheme interpreter giving control to the Scheme REPL. |
| 161 | Arguments are processed as if the Guile program @file{guile} were being |
| 162 | invoked. |
| 163 | |
| 164 | Note that @code{gh_repl} should be used @emph{inside} @code{gh_enter}, |
| 165 | since any Guile interpreter calls are meaningless unless they happen in |
| 166 | the context of the interpreter. |
| 167 | |
| 168 | Also note that when you use @code{gh_repl}, your program will be |
| 169 | controlled by Guile's REPL (which is written in Scheme and has many |
| 170 | useful features). Use straight C code inside @code{gh_enter} if you |
| 171 | want to maintain execution control in your C program. |
| 172 | @end deftypefun |
| 173 | |
| 174 | You will typically use @code{gh_enter} and @code{gh_repl} when you |
| 175 | want a Guile interpreter enhanced by your own libraries, but otherwise |
| 176 | quite normal. For example, to build a Guile--derived program that |
| 177 | includes some random number routines @dfn{GSL} (GNU Scientific Library), |
| 178 | you would write a C program that looks like this: |
| 179 | |
| 180 | @smallexample |
| 181 | #include <guile/gh.h> |
| 182 | #include <gsl_ran.h> |
| 183 | |
| 184 | /* random number suite */ |
| 185 | SCM gw_ran_seed(SCM s) |
| 186 | @{ |
| 187 | gsl_ran_seed(gh_scm2int(s)); |
| 188 | return SCM_UNSPECIFIED; |
| 189 | @} |
| 190 | |
| 191 | SCM gw_ran_random() |
| 192 | @{ |
| 193 | SCM x; |
| 194 | |
| 195 | x = gh_ulong2scm(gsl_ran_random()); |
| 196 | return x; |
| 197 | @} |
| 198 | |
| 199 | SCM gw_ran_uniform() |
| 200 | @{ |
| 201 | SCM x; |
| 202 | |
| 203 | x = gh_double2scm(gsl_ran_uniform()); |
| 204 | return x; |
| 205 | @} |
| 206 | SCM gw_ran_max() |
| 207 | @{ |
| 208 | return gh_double2scm(gsl_ran_max()); |
| 209 | @} |
| 210 | |
| 211 | void |
| 212 | init_gsl() |
| 213 | @{ |
| 214 | /* random number suite */ |
| 215 | gh_new_procedure("gsl-ran-seed", gw_ran_seed, 1, 0, 0); |
| 216 | gh_new_procedure("gsl-ran-random", gw_ran_random, 0, 0, 0); |
| 217 | gh_new_procedure("gsl-ran-uniform", gw_ran_uniform, 0, 0, 0); |
| 218 | gh_new_procedure("gsl-ran-max", gw_ran_max, 0, 0, 0); |
| 219 | @} |
| 220 | |
| 221 | void |
| 222 | main_prog (int argc, char *argv[]) |
| 223 | @{ |
| 224 | init_gsl(); |
| 225 | |
| 226 | gh_repl(argc, argv); |
| 227 | @} |
| 228 | |
| 229 | int |
| 230 | main (int argc, char *argv[]) |
| 231 | @{ |
| 232 | gh_enter (argc, argv, main_prog); |
| 233 | @} |
| 234 | @end smallexample |
| 235 | |
| 236 | Then, supposing the C program is in @file{guile-gsl.c}, you could |
| 237 | compile it with @kbd{gcc -o guile-gsl guile-gsl.c -lguile -lgsl}. |
| 238 | |
| 239 | The resulting program @file{guile-gsl} would have new primitive |
| 240 | procedures @code{gsl-ran-random}, @code{gsl-ran-gaussian} and so forth. |
| 241 | |
| 242 | |
| 243 | @node Error messages |
| 244 | @section Error messages |
| 245 | @cindex libguile - error messages |
| 246 | @cindex error messages in libguile |
| 247 | |
| 248 | [FIXME: need to fill this based on Jim's new mechanism] |
| 249 | |
| 250 | |
| 251 | @node Executing Scheme code |
| 252 | @section Executing Scheme code |
| 253 | @cindex libguile - executing Scheme |
| 254 | @cindex executing Scheme |
| 255 | |
| 256 | Once you have an interpreter running, you can ask it to evaluate Scheme |
| 257 | code. There are two calls that implement this: |
| 258 | |
| 259 | @deftypefun SCM gh_eval_str (char *@var{scheme_code}) |
| 260 | This asks the interpreter to evaluate a single string of Scheme code, |
| 261 | and returns the result of the last expression evaluated. |
| 262 | |
| 263 | Note that the line of code in @var{scheme_code} must be a well formed |
| 264 | Scheme expression. If you have many lines of code before you balance |
| 265 | parentheses, you must either concatenate them into one string, or use |
| 266 | @code{gh_eval_file()}. |
| 267 | @end deftypefun |
| 268 | |
| 269 | @deftypefun SCM gh_eval_file (char *@var{fname}) |
| 270 | @deftypefunx SCM gh_load (char *@var{fname}) |
| 271 | @code{gh_eval_file} is completely analogous to @code{gh_eval_str()}, |
| 272 | except that a whole file is evaluated instead of a string. |
| 273 | @code{gh_eval_file} returns @code{SCM_UNSPECIFIED}. |
| 274 | |
| 275 | @code{gh_load} is identical to @code{gh_eval_file} (it's a macro that |
| 276 | calls @code{gh_eval_file} on its argument). It is provided to start |
| 277 | making the @code{gh_} interface match the R5RS Scheme procedures |
| 278 | closely. |
| 279 | @end deftypefun |
| 280 | |
| 281 | |
| 282 | @node Defining new Scheme procedures in C |
| 283 | @section Defining new Scheme procedures in C |
| 284 | @cindex libguile - new procedures |
| 285 | @cindex new procedures |
| 286 | @cindex procedures, new |
| 287 | @cindex new primitives |
| 288 | @cindex primitives, new |
| 289 | |
| 290 | The real interface between C and Scheme comes when you can write new |
| 291 | Scheme procedures in C. This is done through the routine |
| 292 | |
| 293 | |
| 294 | @deftypefn {Libguile high} SCM gh_new_procedure (char *@var{proc_name}, SCM (*@var{fn})(), int @var{n_required_args}, int @var{n_optional_args}, int @var{restp}) |
| 295 | @code{gh_new_procedure} defines a new Scheme procedure. Its Scheme name |
| 296 | will be @var{proc_name}, it will be implemented by the C function |
| 297 | (*@var{fn})(), it will take at least @var{n_required_args} arguments, |
| 298 | and at most @var{n_optional_args} extra arguments. |
| 299 | |
| 300 | When the @var{restp} parameter is 1, the procedure takes a final |
| 301 | argument: a list of remaining parameters. |
| 302 | |
| 303 | @code{gh_new_procedure} returns an SCM value representing the procedure. |
| 304 | |
| 305 | The C function @var{fn} should have the form |
| 306 | @deftypefn {Libguile high} SCM fn (SCM @var{req1}, SCM @var{req2}, ..., SCM @var{opt1}, SCM @var{opt2}, ..., SCM @var{rest_args}) |
| 307 | The arguments are all passed as SCM values, so the user will have to use |
| 308 | the conversion functions to convert to standard C types. |
| 309 | |
| 310 | Examples of C functions used as new Scheme primitives can be found in |
| 311 | the sample programs @code{learn0} and @code{learn1}. |
| 312 | @end deftypefn |
| 313 | |
| 314 | @end deftypefn |
| 315 | |
| 316 | @strong{Rationale:} this is the correct way to define new Scheme |
| 317 | procedures in C. The ugly mess of arguments is required because of how |
| 318 | C handles procedures with variable numbers of arguments. |
| 319 | |
| 320 | @strong{Note:} what about documentation strings? |
| 321 | |
| 322 | @cartouche |
| 323 | There are several important considerations to be made when writing the C |
| 324 | routine @code{(*fn)()}. |
| 325 | |
| 326 | First of all the C routine has to return type @code{SCM}. |
| 327 | |
| 328 | Second, all arguments passed to the C function will be of type |
| 329 | @code{SCM}. |
| 330 | |
| 331 | Third: the C routine is now subject to Scheme flow control, which means |
| 332 | that it could be interrupted at any point, and then reentered. This |
| 333 | means that you have to be very careful with operations such as |
| 334 | allocating memory, modifying static data @dots{} |
| 335 | |
| 336 | Fourth: to get around the latter issue, you can use |
| 337 | @code{GH_DEFER_INTS} and @code{GH_ALLOW_INTS}. |
| 338 | @end cartouche |
| 339 | |
| 340 | @defmac GH_DEFER_INTS |
| 341 | @defmacx GH_ALLOW_INTS |
| 342 | These macros disable and re-enable Scheme's flow control. They |
| 343 | @end defmac |
| 344 | |
| 345 | |
| 346 | @c [??? have to do this right; maybe using subsections, or maybe creating a |
| 347 | @c section called Flow control issues...] |
| 348 | |
| 349 | @c [??? Go into exhaustive detail with examples of the various possible |
| 350 | @c combinations of required and optional args...] |
| 351 | |
| 352 | |
| 353 | @node Converting data between C and Scheme |
| 354 | @section Converting data between C and Scheme |
| 355 | @cindex libguile - converting data |
| 356 | @cindex data conversion |
| 357 | @cindex converting data |
| 358 | |
| 359 | Guile provides mechanisms to convert data between C and Scheme. This |
| 360 | allows new builtin procedures to understand their arguments (which are |
| 361 | of type @code{SCM}) and return values of type @code{SCM}. |
| 362 | |
| 363 | |
| 364 | @menu |
| 365 | * C to Scheme:: |
| 366 | * Scheme to C:: |
| 367 | @end menu |
| 368 | |
| 369 | @node C to Scheme |
| 370 | @subsection C to Scheme |
| 371 | |
| 372 | @deftypefun SCM gh_bool2scm (int @var{x}) |
| 373 | Returns @code{#f} if @var{x} is zero, @code{#t} otherwise. |
| 374 | @end deftypefun |
| 375 | |
| 376 | @deftypefun SCM gh_ulong2scm (unsigned long @var{x}) |
| 377 | @deftypefunx SCM gh_long2scm (long @var{x}) |
| 378 | @deftypefunx SCM gh_double2scm (double @var{x}) |
| 379 | @deftypefunx SCM gh_char2scm (char @var{x}) |
| 380 | Returns a Scheme object with the value of the C quantity @var{x}. |
| 381 | @end deftypefun |
| 382 | |
| 383 | @deftypefun SCM gh_str2scm (char *@var{s}, int @var{len}) |
| 384 | Returns a new Scheme string with the (not necessarily null-terminated) C |
| 385 | array @var{s} data. |
| 386 | @end deftypefun |
| 387 | |
| 388 | @deftypefun SCM gh_str02scm (char *@var{s}) |
| 389 | Returns a new Scheme string with the null-terminated C string @var{s} |
| 390 | data. |
| 391 | @end deftypefun |
| 392 | |
| 393 | @deftypefun SCM gh_set_substr (char *@var{src}, SCM @var{dst}, int @var{start}, int @var{len}) |
| 394 | Copy @var{len} characters at @var{src} into the @emph{existing} Scheme |
| 395 | string @var{dst}, starting at @var{start}. @var{start} is an index into |
| 396 | @var{dst}; zero means the beginning of the string. |
| 397 | |
| 398 | If @var{start} + @var{len} is off the end of @var{dst}, signal an |
| 399 | out-of-range error. |
| 400 | @end deftypefun |
| 401 | |
| 402 | @deftypefun SCM gh_symbol2scm (char *@var{name}) |
| 403 | Given a null-terminated string @var{name}, return the symbol with that |
| 404 | name. |
| 405 | @end deftypefun |
| 406 | |
| 407 | @deftypefun SCM gh_ints2scm (int *@var{dptr}, int @var{n}) |
| 408 | @deftypefunx SCM gh_doubles2scm (double *@var{dptr}, int @var{n}) |
| 409 | Make a scheme vector containing the @var{n} ints or doubles at memory |
| 410 | location @var{dptr}. |
| 411 | @end deftypefun |
| 412 | |
| 413 | @deftypefun SCM gh_chars2byvect (char *@var{dptr}, int @var{n}) |
| 414 | @deftypefunx SCM gh_shorts2svect (short *@var{dptr}, int @var{n}) |
| 415 | @deftypefunx SCM gh_longs2ivect (long *@var{dptr}, int @var{n}) |
| 416 | @deftypefunx SCM gh_ulongs2uvect (ulong *@var{dptr}, int @var{n}) |
| 417 | @deftypefunx SCM gh_floats2fvect (float *@var{dptr}, int @var{n}) |
| 418 | @deftypefunx SCM gh_doubles2dvect (double *@var{dptr}, int @var{n}) |
| 419 | Make a scheme uniform vector containing the @var{n} chars, shorts, |
| 420 | longs, unsigned longs, floats or doubles at memory location @var{dptr}. |
| 421 | @end deftypefun |
| 422 | |
| 423 | |
| 424 | |
| 425 | @node Scheme to C |
| 426 | @subsection Scheme to C |
| 427 | |
| 428 | @deftypefun int gh_scm2bool (SCM @var{obj}) |
| 429 | @deftypefunx {unsigned long} gh_scm2ulong (SCM @var{obj}) |
| 430 | @deftypefunx long gh_scm2long (SCM @var{obj}) |
| 431 | @deftypefunx double gh_scm2double (SCM @var{obj}) |
| 432 | @deftypefunx int gh_scm2char (SCM @var{obj}) |
| 433 | These routines convert the Scheme object to the given C type. |
| 434 | @end deftypefun |
| 435 | |
| 436 | @deftypefun char *gh_scm2newstr (SCM @var{str}, int *@var{lenp}) |
| 437 | Given a Scheme string @var{str}, return a pointer to a new copy of its |
| 438 | contents, followed by a null byte. If @var{lenp} is non-null, set |
| 439 | @code{*@var{lenp}} to the string's length. |
| 440 | |
| 441 | This function uses malloc to obtain storage for the copy; the caller is |
| 442 | responsible for freeing it. |
| 443 | |
| 444 | Note that Scheme strings may contain arbitrary data, including null |
| 445 | characters. This means that null termination is not a reliable way to |
| 446 | determine the length of the returned value. However, the function |
| 447 | always copies the complete contents of @var{str}, and sets @var{*lenp} |
| 448 | to the true length of the string (when @var{lenp} is non-null). |
| 449 | @end deftypefun |
| 450 | |
| 451 | |
| 452 | @deftypefun void gh_get_substr (SCM str, char *return_str, int *lenp) |
| 453 | Copy @var{len} characters at @var{start} from the Scheme string |
| 454 | @var{src} to memory at @var{dst}. @var{start} is an index into |
| 455 | @var{src}; zero means the beginning of the string. @var{dst} has |
| 456 | already been allocated by the caller. |
| 457 | |
| 458 | If @var{start} + @var{len} is off the end of @var{src}, signal an |
| 459 | out-of-range error. |
| 460 | @end deftypefun |
| 461 | |
| 462 | @deftypefun char *gh_symbol2newstr (SCM @var{sym}, int *@var{lenp}) |
| 463 | Takes a Scheme symbol and returns a string of the form |
| 464 | @code{"'symbol-name"}. If @var{lenp} is non-null, the string's length |
| 465 | is returned in @code{*@var{lenp}}. |
| 466 | |
| 467 | This function uses malloc to obtain storage for the returned string; the |
| 468 | caller is responsible for freeing it. |
| 469 | @end deftypefun |
| 470 | |
| 471 | @deftypefun char *gh_scm2chars (SCM @var{vector}, chars *@var{result}) |
| 472 | @deftypefunx short *gh_scm2shorts (SCM @var{vector}, short *@var{result}) |
| 473 | @deftypefunx long *gh_scm2longs (SCM @var{vector}, long *@var{result}) |
| 474 | @deftypefunx float *gh_scm2floats (SCM @var{vector}, float *@var{result}) |
| 475 | @deftypefunx double *gh_scm2doubles (SCM @var{vector}, double *@var{result}) |
| 476 | Copy the numbers in @var{vector} to the array pointed to by @var{result} |
| 477 | and return it. If @var{result} is NULL, allocate a double array large |
| 478 | enough. |
| 479 | |
| 480 | @var{vector} can be an ordinary vector, a weak vector, or a signed or |
| 481 | unsigned uniform vector of the same type as the result array. For |
| 482 | chars, @var{vector} can be a string or substring. For floats and |
| 483 | doubles, @var{vector} can contain a mix of inexact and integer values. |
| 484 | |
| 485 | If @var{vector} is of unsigned type and contains values too large to fit |
| 486 | in the signed destination array, those values will be wrapped around, |
| 487 | that is, data will be copied as if the destination array was unsigned. |
| 488 | @end deftypefun |
| 489 | |
| 490 | |
| 491 | @node Type predicates |
| 492 | @section Type predicates |
| 493 | |
| 494 | These C functions mirror Scheme's type predicate procedures with one |
| 495 | important difference. The C routines return C boolean values (0 and 1) |
| 496 | instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}. |
| 497 | |
| 498 | The Scheme notational convention of putting a @code{?} at the end of |
| 499 | predicate procedure names is mirrored in C by placing @code{_p} at the |
| 500 | end of the procedure. For example, @code{(pair? ...)} maps to |
| 501 | @code{gh_pair_p(...)}. |
| 502 | |
| 503 | @deftypefun int gh_boolean_p (SCM @var{val}) |
| 504 | Returns 1 if @var{val} is a boolean, 0 otherwise. |
| 505 | @end deftypefun |
| 506 | |
| 507 | @deftypefun int gh_symbol_p (SCM @var{val}) |
| 508 | Returns 1 if @var{val} is a symbol, 0 otherwise. |
| 509 | @end deftypefun |
| 510 | |
| 511 | @deftypefun int gh_char_p (SCM @var{val}) |
| 512 | Returns 1 if @var{val} is a char, 0 otherwise. |
| 513 | @end deftypefun |
| 514 | |
| 515 | @deftypefun int gh_vector_p (SCM @var{val}) |
| 516 | Returns 1 if @var{val} is a vector, 0 otherwise. |
| 517 | @end deftypefun |
| 518 | |
| 519 | @deftypefun int gh_pair_p (SCM @var{val}) |
| 520 | Returns 1 if @var{val} is a pair, 0 otherwise. |
| 521 | @end deftypefun |
| 522 | |
| 523 | @deftypefun int gh_procedure_p (SCM @var{val}) |
| 524 | Returns 1 if @var{val} is a procedure, 0 otherwise. |
| 525 | @end deftypefun |
| 526 | |
| 527 | @deftypefun int gh_list_p (SCM @var{val}) |
| 528 | Returns 1 if @var{val} is a list, 0 otherwise. |
| 529 | @end deftypefun |
| 530 | |
| 531 | @deftypefun int gh_inexact_p (SCM @var{val}) |
| 532 | Returns 1 if @var{val} is an inexact number, 0 otherwise. |
| 533 | @end deftypefun |
| 534 | |
| 535 | @deftypefun int gh_exact_p (SCM @var{val}) |
| 536 | Returns 1 if @var{val} is an exact number, 0 otherwise. |
| 537 | @end deftypefun |
| 538 | |
| 539 | |
| 540 | @node Equality predicates |
| 541 | @section Equality predicates |
| 542 | |
| 543 | These C functions mirror Scheme's equality predicate procedures with one |
| 544 | important difference. The C routines return C boolean values (0 and 1) |
| 545 | instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}. |
| 546 | |
| 547 | The Scheme notational convention of putting a @code{?} at the end of |
| 548 | predicate procedure names is mirrored in C by placing @code{_p} at the |
| 549 | end of the procedure. For example, @code{(equal? ...)} maps to |
| 550 | @code{gh_equal_p(...)}. |
| 551 | |
| 552 | @deftypefun int gh_eq_p (SCM x, SCM y) |
| 553 | Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's |
| 554 | @code{eq?} predicate, 0 otherwise. |
| 555 | @end deftypefun |
| 556 | |
| 557 | @deftypefun int gh_eqv_p (SCM x, SCM y) |
| 558 | Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's |
| 559 | @code{eqv?} predicate, 0 otherwise. |
| 560 | @end deftypefun |
| 561 | |
| 562 | @deftypefun int gh_equal_p (SCM x, SCM y) |
| 563 | Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's |
| 564 | @code{equal?} predicate, 0 otherwise. |
| 565 | @end deftypefun |
| 566 | |
| 567 | @deftypefun int gh_string_equal_p (SCM @var{s1}, SCM @var{s2}) |
| 568 | Returns 1 if the strings @var{s1} and @var{s2} are equal, 0 otherwise. |
| 569 | @end deftypefun |
| 570 | |
| 571 | @deftypefun int gh_null_p (SCM @var{l}) |
| 572 | Returns 1 if @var{l} is an empty list or pair; 0 otherwise. |
| 573 | @end deftypefun |
| 574 | |
| 575 | |
| 576 | @node Memory allocation and garbage collection |
| 577 | @section Memory allocation and garbage collection |
| 578 | |
| 579 | @c [FIXME: flesh this out with some description of garbage collection in |
| 580 | @c scm/guile] |
| 581 | |
| 582 | @c @deftypefun SCM gh_mkarray (int size) |
| 583 | @c Allocate memory for a Scheme object in a garbage-collector-friendly |
| 584 | @c manner. |
| 585 | @c @end deftypefun |
| 586 | |
| 587 | |
| 588 | @node Calling Scheme procedures from C |
| 589 | @section Calling Scheme procedures from C |
| 590 | |
| 591 | Many of the Scheme primitives are available in the @code{gh_} |
| 592 | interface; they take and return objects of type SCM, and one could |
| 593 | basically use them to write C code that mimics Scheme code. |
| 594 | |
| 595 | I will list these routines here without much explanation, since what |
| 596 | they do is the same as documented in @ref{Standard procedures, R5RS, , |
| 597 | r5rs, R5RS}. But I will point out that when a procedure takes a |
| 598 | variable number of arguments (such as @code{gh_list}), you should pass |
| 599 | the constant @var{SCM_UNDEFINED} from C to signify the end of the list. |
| 600 | |
| 601 | @deftypefun SCM gh_define (char *@var{name}, SCM @var{val}) |
| 602 | Corresponds to the Scheme @code{(define name val)}: it binds a value to |
| 603 | the given name (which is a C string). Returns the new object. |
| 604 | @end deftypefun |
| 605 | |
| 606 | @heading Pairs and lists |
| 607 | |
| 608 | @deftypefun SCM gh_cons (SCM @var{a}, SCM @var{b}) |
| 609 | @deftypefunx SCM gh_list (SCM l0, SCM l1, ... , SCM_UNDEFINED) |
| 610 | These correspond to the Scheme @code{(cons a b)} and @code{(list l0 l1 |
| 611 | ...)} procedures. Note that @code{gh_list()} is a C macro that invokes |
| 612 | @code{scm_listify()}. |
| 613 | @end deftypefun |
| 614 | |
| 615 | @deftypefun SCM gh_car (SCM @var{obj}) |
| 616 | @deftypefunx SCM gh_cdr (SCM @var{obj}) |
| 617 | @dots{} |
| 618 | |
| 619 | @deftypefunx SCM gh_c[ad][ad][ad][ad]r (SCM @var{obj}) |
| 620 | These correspond to the Scheme @code{(caadar ls)} procedures etc @dots{} |
| 621 | @end deftypefun |
| 622 | |
| 623 | @deftypefun SCM gh_set_car_x(SCM @var{pair}, SCM @var{value}) |
| 624 | Modifies the CAR of @var{pair} to be @var{value}. This is equivalent to |
| 625 | the Scheme procedure @code{(set-car! ...)}. |
| 626 | @end deftypefun |
| 627 | |
| 628 | @deftypefun SCM gh_set_cdr_x(SCM @var{pair}, SCM @var{value}) |
| 629 | Modifies the CDR of @var{pair} to be @var{value}. This is equivalent to |
| 630 | the Scheme procedure @code{(set-cdr! ...)}. |
| 631 | @end deftypefun |
| 632 | |
| 633 | @deftypefun {unsigned long} gh_length (SCM @var{ls}) |
| 634 | Returns the length of the list. |
| 635 | @end deftypefun |
| 636 | |
| 637 | @deftypefun SCM gh_append (SCM @var{args}) |
| 638 | @deftypefunx SCM gh_append2 (SCM @var{l1}, SCM @var{l2}) |
| 639 | @deftypefunx SCM gh_append3 (SCM @var{l1}, SCM @var{l2}, @var{l3}) |
| 640 | @deftypefunx SCM gh_append4 (SCM @var{l1}, SCM @var{l2}, @var{l3}, @var{l4}) |
| 641 | @code{gh_append()} takes @var{args}, which is a list of lists |
| 642 | @code{(list1 list2 ...)}, and returns a list containing all the elements |
| 643 | of the individual lists. |
| 644 | |
| 645 | A typical invocation of @code{gh_append()} to append 5 lists together |
| 646 | would be |
| 647 | @smallexample |
| 648 | gh_append(gh_list(l1, l2, l3, l4, l5, SCM_UNDEFINED)); |
| 649 | @end smallexample |
| 650 | |
| 651 | The functions @code{gh_append2()}, @code{gh_append2()}, |
| 652 | @code{gh_append3()} and @code{gh_append4()} are convenience routines to |
| 653 | make it easier for C programs to form the list of lists that goes as an |
| 654 | argument to @code{gh_append()}. |
| 655 | @end deftypefun |
| 656 | |
| 657 | @deftypefun SCM gh_reverse (SCM @var{ls}) |
| 658 | Returns a new list that has the same elements as @var{ls} but in the |
| 659 | reverse order. Note that this is implemented as a macro which calls |
| 660 | @code{scm_reverse()}. |
| 661 | @end deftypefun |
| 662 | |
| 663 | @deftypefun SCM gh_list_tail (SCM @var{ls}, SCM @var{k}) |
| 664 | Returns the sublist of @var{ls} with the last @var{k} elements. |
| 665 | @end deftypefun |
| 666 | |
| 667 | @deftypefun SCM gh_list_ref (SCM @var{ls}, SCM @var{k}) |
| 668 | Returns the @var{k}th element of the list @var{ls}. |
| 669 | @end deftypefun |
| 670 | |
| 671 | @deftypefun SCM gh_memq (SCM @var{x}, SCM @var{ls}) |
| 672 | @deftypefunx SCM gh_memv (SCM @var{x}, SCM @var{ls}) |
| 673 | @deftypefunx SCM gh_member (SCM @var{x}, SCM @var{ls}) |
| 674 | These functions return the first sublist of @var{ls} whose CAR is |
| 675 | @var{x}. They correspond to @code{(memq x ls)}, @code{(memv x ls)} and |
| 676 | @code{(member x ls)}, and hence use (respectively) @code{eq?}, |
| 677 | @code{eqv?} and @code{equal?} to do comparisons. |
| 678 | |
| 679 | If @var{x} does not appear in @var{ls}, the value @code{SCM_BOOL_F} (not |
| 680 | the empty list) is returned. |
| 681 | |
| 682 | Note that these functions are implemented as macros which call |
| 683 | @code{scm_memq()}, @code{scm_memv()} and @code{scm_member()} |
| 684 | respectively. |
| 685 | @end deftypefun |
| 686 | |
| 687 | @deftypefun SCM gh_assq (SCM @var{x}, SCM @var{alist}) |
| 688 | @deftypefunx SCM gh_assv (SCM @var{x}, SCM @var{alist}) |
| 689 | @deftypefunx SCM gh_assoc (SCM @var{x}, SCM @var{alist}) |
| 690 | These functions search an @dfn{association list} (list of pairs) |
| 691 | @var{alist} for the first pair whose CAR is @var{x}, and they return |
| 692 | that pair. |
| 693 | |
| 694 | If no pair in @var{alist} has @var{x} as its CAR, the value |
| 695 | @code{SCM_BOOL_F} (not the empty list) is returned. |
| 696 | |
| 697 | Note that these functions are implemented as macros which call |
| 698 | @code{scm_assq()}, @code{scm_assv()} and @code{scm_assoc()} |
| 699 | respectively. |
| 700 | @end deftypefun |
| 701 | |
| 702 | |
| 703 | @heading Symbols |
| 704 | |
| 705 | @c @deftypefun SCM gh_symbol (SCM str, SCM len) |
| 706 | @c @deftypefunx SCM gh_tmp_symbol (SCM str, SCM len) |
| 707 | @c Takes the given string @var{str} of length @var{len} and returns a |
| 708 | @c symbol corresponding to that string. |
| 709 | @c @end deftypefun |
| 710 | |
| 711 | |
| 712 | @heading Vectors |
| 713 | |
| 714 | @deftypefun SCM gh_make_vector (SCM @var{n}, SCM @var{fill}) |
| 715 | @deftypefunx SCM gh_vector (SCM @var{ls}) |
| 716 | @deftypefunx SCM gh_vector_ref (SCM @var{v}, SCM @var{i}) |
| 717 | @deftypefunx SCM gh_vector_set (SCM @var{v}, SCM @var{i}, SCM @var{val}) |
| 718 | @deftypefunx {unsigned long} gh_vector_length (SCM @var{v}) |
| 719 | @deftypefunx SCM gh_list_to_vector (SCM @var{ls}) |
| 720 | These correspond to the Scheme @code{(make-vector n fill)}, |
| 721 | @code{(vector a b c ...)} @code{(vector-ref v i)} @code{(vector-set v i |
| 722 | value)} @code{(vector-length v)} @code{(list->vector ls)} procedures. |
| 723 | |
| 724 | The correspondence is not perfect for @code{gh_vector}: this routine |
| 725 | takes a list @var{ls} instead of the individual list elements, thus |
| 726 | making it identical to @code{gh_list_to_vector}. |
| 727 | |
| 728 | There is also a difference in gh_vector_length: the value returned is a |
| 729 | C @code{unsigned long} instead of an SCM object. |
| 730 | @end deftypefun |
| 731 | |
| 732 | |
| 733 | @heading Procedures |
| 734 | |
| 735 | @c @deftypefun SCM gh_make_subr (SCM (*@var{fn})(), int @var{req}, int @var{opt}, int @var{restp}, char *@var{sym}) |
| 736 | @c Make the C function @var{fn} available to Scheme programs. The function |
| 737 | @c will be bound to the symbol @var{sym}. The arguments @var{req}, |
| 738 | @c @var{opt} and @var{restp} describe @var{fn}'s calling conventions. The |
| 739 | @c function must take @var{req} required arguments and may take @var{opt} |
| 740 | @c optional arguments. Any optional arguments which are not supplied by |
| 741 | @c the caller will be bound to @var{SCM_UNSPECIFIED}. If @var{restp} is |
| 742 | @c non-zero, it means that @var{fn} may be called with an arbitrary number |
| 743 | @c of arguments, and that any extra arguments supplied by the caller will |
| 744 | @c be passed to @var{fn} as a list. The @var{restp} argument is exactly |
| 745 | @c like Scheme's @code{(lambda (arg1 arg2 . arglist))} calling convention. |
| 746 | @c |
| 747 | @c For example, the procedure @code{read-line}, which takes optional |
| 748 | @c @var{port} and @var{handle-delim} arguments, would be declared like so: |
| 749 | @c |
| 750 | @c @example |
| 751 | @c SCM scm_read_line (SCM port, SCM handle_delim); |
| 752 | @c gh_make_subr (scm_read_line, 0, 2, 0, "read-line"); |
| 753 | @c @end example |
| 754 | @c |
| 755 | @c The @var{req} argument to @code{gh_make_subr} is 0 to indicate that |
| 756 | @c there are no required arguments, so @code{read-line} may be called |
| 757 | @c without any arguments at all. The @var{opt} argument is 2, to indicate |
| 758 | @c that both the @var{port} and @var{handle_delim} arguments to |
| 759 | @c @code{scm_read_line} are optional, and will be bound to |
| 760 | @c @code{SCM_UNSPECIFIED} if the calling program does not supply them. |
| 761 | @c Because the @var{restp} argument is 0, this function may not be called |
| 762 | @c with more than two arguments. |
| 763 | @c @end deftypefun |
| 764 | |
| 765 | @deftypefun SCM gh_apply (SCM proc, SCM args) |
| 766 | Call the Scheme procedure @var{proc}, with the elements of @var{args} as |
| 767 | arguments. @var{args} must be a proper list. |
| 768 | @end deftypefun |
| 769 | |
| 770 | @deftypefun SCM gh_call0 (SCM proc) |
| 771 | @deftypefunx SCM gh_call1 (SCM proc, SCM arg) |
| 772 | @deftypefunx SCM gh_call2 (SCM proc, SCM arg1, SCM arg2) |
| 773 | @deftypefunx SCM gh_call3 (SCM proc, SCM arg1, SCM arg2, SCM arg3) |
| 774 | Call the Scheme procedure @var{proc} with no arguments |
| 775 | (@code{gh_call0}), one argument (@code{gh_call1}), and so on. You can |
| 776 | get the same effect by wrapping the arguments up into a list, and |
| 777 | calling @code{gh_apply}; Guile provides these functions for convenience. |
| 778 | @end deftypefun |
| 779 | |
| 780 | |
| 781 | @deftypefun SCM gh_catch (SCM key, SCM thunk, SCM handler) |
| 782 | @deftypefunx SCM gh_throw (SCM key, SCM args) |
| 783 | Corresponds to the Scheme @code{catch} and @code{throw} procedures, |
| 784 | which in Guile are provided as primitives. |
| 785 | @end deftypefun |
| 786 | |
| 787 | @c [FIXME: must add the I/O section in gscm.h] |
| 788 | |
| 789 | @deftypefun SCM gh_is_eq (SCM a, SCM b) |
| 790 | @deftypefunx SCM gh_is_eqv (SCM a, SCM b) |
| 791 | @deftypefunx SCM gh_is_equal (SCM a, SCM b) |
| 792 | These correspond to the Scheme @code{eq?}, @code{eqv?} and @code{equal?} |
| 793 | predicates. |
| 794 | @end deftypefun |
| 795 | |
| 796 | @deftypefun int gh_obj_length (SCM @var{obj}) |
| 797 | Returns the raw object length. |
| 798 | @end deftypefun |
| 799 | |
| 800 | @heading Data lookup |
| 801 | |
| 802 | For now I just include Tim Pierce's comments from the @file{gh_data.c} |
| 803 | file; it should be organized into a documentation of the two functions |
| 804 | here. |
| 805 | |
| 806 | @smallexample |
| 807 | /* Data lookups between C and Scheme |
| 808 | |
| 809 | Look up a symbol with a given name, and return the object to which |
| 810 | it is bound. gh_lookup examines the Guile top level, and |
| 811 | gh_module_lookup checks the module name space specified by the |
| 812 | `vec' argument. |
| 813 | |
| 814 | The return value is the Scheme object to which SNAME is bound, or |
| 815 | SCM_UNDEFINED if SNAME is not bound in the given context. [FIXME: |
| 816 | should this be SCM_UNSPECIFIED? Can a symbol ever legitimately be |
| 817 | bound to SCM_UNDEFINED or SCM_UNSPECIFIED? What is the difference? |
| 818 | -twp] */ |
| 819 | @end smallexample |
| 820 | |
| 821 | |
| 822 | @node Mixing gh and scm APIs |
| 823 | @section Mixing gh and scm APIs |
| 824 | |
| 825 | |
| 826 | @node scm transition summary |
| 827 | @section Transitioning to the scm Interface |
| 828 | |
| 829 | The following table summarizes the available information on how to |
| 830 | transition from the GH to the scm interface. Where transitioning is not |
| 831 | completely straightforward, the table includes a reference to more |
| 832 | detailed documentation in the preceding sections. |
| 833 | |
| 834 | @table @asis |
| 835 | @item Header file |
| 836 | Use @code{#include <libguile.h>} instead of @code{#include |
| 837 | <guile/gh.h>}. |
| 838 | |
| 839 | @item Compiling and Linking |
| 840 | Use @code{guile-config} to pick up the flags required to compile C or |
| 841 | C++ code that uses @code{libguile}, like so |
| 842 | |
| 843 | @smallexample |
| 844 | $(CC) -o prog.o -c prog.c `guile-config compile` |
| 845 | @end smallexample |
| 846 | |
| 847 | If you are using libtool to link your executables, just use |
| 848 | @code{-lguile} in your link command. Libtool will expand this into |
| 849 | the needed linker options automatically. If you are not using |
| 850 | libtool, use the @code{guile-config} program to query the needed |
| 851 | options explicitly. A linker command like |
| 852 | |
| 853 | @smallexample |
| 854 | $(CC) -o prog prog.o `guile-config link` |
| 855 | @end smallexample |
| 856 | |
| 857 | should be all that is needed. To link shared libraries that will be |
| 858 | used as Guile Extensions, use libtool to control both the compilation |
| 859 | and the link stage. |
| 860 | |
| 861 | @item The @code{SCM} type |
| 862 | No change: the scm interface also uses this type to represent an |
| 863 | arbitrary Scheme value. |
| 864 | |
| 865 | @item @code{SCM_BOOL_F} and @code{SCM_BOOL_T} |
| 866 | No change. |
| 867 | |
| 868 | @item @code{SCM_UNSPECIFIED} and @code{SCM_UNDEFINED} |
| 869 | No change. |
| 870 | |
| 871 | @item @code{gh_enter} |
| 872 | Use @code{scm_boot_guile} instead, but note that @code{scm_boot_guile} |
| 873 | has a slightly different calling convention from @code{gh_enter}: |
| 874 | @code{scm_boot_guile}, and the main program function that you specify |
| 875 | for @code{scm_boot_guile} to call, both take an additional @var{closure} |
| 876 | parameter. @ref{Guile Initialization Functions} for more details. |
| 877 | |
| 878 | @item @code{gh_repl} |
| 879 | Use @code{scm_shell} instead. |
| 880 | |
| 881 | @item @code{gh_init} |
| 882 | Use @code{scm_init_guile} instead. |
| 883 | |
| 884 | @item @code{gh_eval_str} |
| 885 | Use @code{scm_c_eval_string} instead. |
| 886 | |
| 887 | @item @code{gh_eval_file} or @code{gh_load} |
| 888 | Use @code{scm_c_primitive_load} instead. |
| 889 | |
| 890 | @item @code{gh_new_procedure} |
| 891 | Use @code{scm_c_define_gsubr} instead, but note that the arguments are |
| 892 | in a different order: for @code{scm_c_define_gsubr} the C function |
| 893 | pointer is the last argument. @ref{A Sample Guile Extension} for an |
| 894 | example. |
| 895 | |
| 896 | @item @code{gh_defer_ints} and @code{gh_allow_ints} |
| 897 | Use @code{SCM_DEFER_INTS} and @code{SCM_ALLOW_INTS} instead. Note that |
| 898 | these macros are used without parentheses, as in @code{SCM_DEFER_INTS;}. |
| 899 | |
| 900 | @item @code{gh_bool2scm} |
| 901 | Use @code{SCM_BOOL} instead. |
| 902 | |
| 903 | @item @code{gh_ulong2scm} |
| 904 | Use @code{scm_ulong2num} instead. |
| 905 | |
| 906 | @item @code{gh_long2scm} |
| 907 | Use @code{scm_long2num} instead. |
| 908 | |
| 909 | @item @code{gh_double2scm} |
| 910 | Use @code{scm_make_real} instead. |
| 911 | |
| 912 | @item @code{gh_char2scm} |
| 913 | Use @code{SCM_MAKE_CHAR} instead. |
| 914 | |
| 915 | @item @code{gh_str2scm} |
| 916 | Use @code{scm_mem2string} instead. |
| 917 | |
| 918 | @item @code{gh_str02scm} |
| 919 | Use @code{scm_makfrom0str} instead. |
| 920 | |
| 921 | @item @code{gh_set_substr} |
| 922 | No direct scm equivalent. [FIXME] |
| 923 | |
| 924 | @item @code{gh_symbol2scm} |
| 925 | Use @code{scm_str2symbol} instead. [FIXME: inconsistent naming, |
| 926 | should be @code{scm_str02symbol}.] |
| 927 | |
| 928 | @item @code{gh_ints2scm} and @code{gh_doubles2scm} |
| 929 | Use @code{scm_c_ints2scm} and @code{scm_c_doubles2scm} instead. |
| 930 | |
| 931 | @item @code{gh_chars2byvect} and @code{gh_shorts2svect} |
| 932 | Use @code{scm_c_chars2byvect} and @code{scm_c_shorts2svect} instead. |
| 933 | |
| 934 | @item @code{gh_longs2ivect} and @code{gh_ulongs2uvect} |
| 935 | Use @code{scm_c_longs2ivect} and @code{scm_c_ulongs2uvect} instead. |
| 936 | |
| 937 | @item @code{gh_floats2fvect} and @code{gh_doubles2dvect} |
| 938 | Use @code{scm_c_floats2fvect} and @code{scm_c_doubles2dvect} instead. |
| 939 | |
| 940 | @item @code{gh_scm2bool} |
| 941 | Use @code{SCM_NFALSEP} instead. |
| 942 | |
| 943 | @item @code{gh_scm2int} |
| 944 | Replace @code{gh_scm2int (@var{obj})} by |
| 945 | @example |
| 946 | scm_num2int (@var{obj}, SCM_ARG1, @var{str}) |
| 947 | @end example |
| 948 | where @var{str} is a C string that describes the context of the call. |
| 949 | |
| 950 | @item @code{gh_scm2ulong} |
| 951 | Replace @code{gh_scm2ulong (@var{obj})} by |
| 952 | @example |
| 953 | scm_num2ulong (@var{obj}, SCM_ARG1, @var{str}) |
| 954 | @end example |
| 955 | where @var{str} is a C string that describes the context of the call. |
| 956 | |
| 957 | @item @code{gh_scm2long} |
| 958 | Replace @code{gh_scm2long (@var{obj})} by |
| 959 | @example |
| 960 | scm_num2long (@var{obj}, SCM_ARG1, @var{str}) |
| 961 | @end example |
| 962 | where @var{str} is a C string that describes the context of the call. |
| 963 | |
| 964 | @item @code{gh_scm2double} |
| 965 | Replace @code{gh_scm2double (@var{obj})} by |
| 966 | @example |
| 967 | scm_num2dbl (@var{obj}, @var{str}) |
| 968 | @end example |
| 969 | where @var{str} is a C string that describes the context of the call. |
| 970 | |
| 971 | @item @code{gh_scm2char} |
| 972 | Use the @code{SCM_CHAR} macro instead, but note that @code{SCM_CHAR} |
| 973 | does not check that its argument is actually a character. To check that |
| 974 | a @code{SCM} value is a character before using @code{SCM_CHAR} to |
| 975 | extract the character value, use the @code{SCM_VALIDATE_CHAR} macro. |
| 976 | |
| 977 | @item @code{gh_scm2newstr} |
| 978 | Instead of @code{gh_scm2newstr (@var{obj}, @var{lenp})} use |
| 979 | @code{scm_c_string2str (@var{obj}, @var{str}, @var{lenp})}. With the |
| 980 | additional @var{str} argument the user can pass a pre-allocated memory |
| 981 | chunk or leave it passing NULL. |
| 982 | |
| 983 | @item @code{gh_get_substr} |
| 984 | Use the @code{scm_c_substring2str (@var{obj}, @var{str}, @var{start}, |
| 985 | @var{len})} function instead. |
| 986 | |
| 987 | @item @code{gh_symbol2newstr} |
| 988 | Use the @code{scm_c_symbol2str (@var{obj}, @var{str}, @var{lenp})} function |
| 989 | instead. With the additional @var{str} argument the user can pass a |
| 990 | pre-allocated memory chunk or leave it passing NULL. |
| 991 | |
| 992 | @item @code{gh_scm2chars} |
| 993 | Use @code{scm_c_scm2chars} instead. |
| 994 | |
| 995 | @item @code{gh_scm2shorts} and @code{gh_scm2longs} |
| 996 | Use @code{scm_c_shorts2scm} and @code{scm_c_longs2scm} instead. |
| 997 | |
| 998 | @item @code{gh_scm2floats} and @code{gh_scm2doubles} |
| 999 | Use @code{scm_c_floats2scm} and @code{scm_c_doubles2scm} instead. |
| 1000 | |
| 1001 | @item @code{gh_boolean_p} |
| 1002 | Use the @code{SCM_BOOLP} macro instead, or replace @code{gh_boolean_p |
| 1003 | (@var{obj})} by |
| 1004 | @example |
| 1005 | SCM_NFALSEP (scm_boolean_p (@var{obj})) |
| 1006 | @end example |
| 1007 | |
| 1008 | @item @code{gh_symbol_p} |
| 1009 | Use the @code{SCM_SYMBOLP} macro instead, or replace @code{gh_symbol_p |
| 1010 | (@var{obj})} by |
| 1011 | @example |
| 1012 | SCM_NFALSEP (scm_symbol_p (@var{obj})) |
| 1013 | @end example |
| 1014 | |
| 1015 | @item @code{gh_char_p} |
| 1016 | Use the @code{SCM_CHARP} macro instead, or replace @code{gh_char_p |
| 1017 | (@var{obj})} by |
| 1018 | @example |
| 1019 | SCM_NFALSEP (scm_char_p (@var{obj})) |
| 1020 | @end example |
| 1021 | |
| 1022 | @item @code{gh_vector_p} |
| 1023 | Use the @code{SCM_VECTORP} macro instead, or replace @code{gh_vector_p |
| 1024 | (@var{obj})} by |
| 1025 | @example |
| 1026 | SCM_NFALSEP (scm_vector_p (@var{obj})) |
| 1027 | @end example |
| 1028 | |
| 1029 | @item @code{gh_pair_p} |
| 1030 | Use the @code{SCM_CONSP} macro instead, or replace @code{gh_pair_p |
| 1031 | (@var{obj})} by |
| 1032 | @example |
| 1033 | SCM_NFALSEP (scm_pair_p (@var{obj})) |
| 1034 | @end example |
| 1035 | |
| 1036 | @item @code{gh_number_p} |
| 1037 | Use the @code{SCM_NUMBERP} macro instead, or replace @code{gh_number_p |
| 1038 | (@var{obj})} by |
| 1039 | @example |
| 1040 | SCM_NFALSEP (scm_number_p (@var{obj})) |
| 1041 | @end example |
| 1042 | |
| 1043 | @item @code{gh_string_p} |
| 1044 | Use the @code{SCM_STRINGP} macro instead, or replace @code{gh_string_p |
| 1045 | (@var{obj})} by |
| 1046 | @example |
| 1047 | SCM_NFALSEP (scm_string_p (@var{obj})) |
| 1048 | @end example |
| 1049 | |
| 1050 | @item @code{gh_procedure_p} |
| 1051 | Replace @code{gh_procedure_p (@var{obj})} by |
| 1052 | @example |
| 1053 | SCM_NFALSEP (scm_procedure_p (@var{obj})) |
| 1054 | @end example |
| 1055 | |
| 1056 | @item @code{gh_list_p} |
| 1057 | Replace @code{gh_list_p (@var{obj})} by |
| 1058 | @example |
| 1059 | SCM_NFALSEP (scm_list_p (@var{obj})) |
| 1060 | @end example |
| 1061 | |
| 1062 | @item @code{gh_inexact_p} |
| 1063 | Use the @code{SCM_INEXACTP} macro instead, or replace @code{gh_inexact_p |
| 1064 | (@var{obj})} by |
| 1065 | @example |
| 1066 | SCM_NFALSEP (scm_inexact_p (@var{obj})) |
| 1067 | @end example |
| 1068 | |
| 1069 | @item @code{gh_exact_p} |
| 1070 | Replace @code{gh_exact_p (@var{obj})} by |
| 1071 | @example |
| 1072 | SCM_NFALSEP (scm_exact_p (@var{obj})) |
| 1073 | @end example |
| 1074 | |
| 1075 | @item @code{gh_eq_p} |
| 1076 | Use the @code{SCM_EQ_P} macro instead, or replace @code{gh_eq_p |
| 1077 | (@var{x}, @var{y})} by |
| 1078 | @example |
| 1079 | SCM_NFALSEP (scm_eq_p (@var{x}, @var{y})) |
| 1080 | @end example |
| 1081 | |
| 1082 | @item @code{gh_eqv_p} |
| 1083 | Replace @code{gh_eqv_p (@var{x}, @var{y})} by |
| 1084 | @example |
| 1085 | SCM_NFALSEP (scm_eqv_p (@var{x}, @var{y})) |
| 1086 | @end example |
| 1087 | |
| 1088 | @item @code{gh_equal_p} |
| 1089 | Replace @code{gh_equal_p (@var{x}, @var{y})} by |
| 1090 | @example |
| 1091 | SCM_NFALSEP (scm_equal_p (@var{x}, @var{y})) |
| 1092 | @end example |
| 1093 | |
| 1094 | @item @code{gh_string_equal_p} |
| 1095 | Replace @code{gh_string_equal_p (@var{x}, @var{y})} by |
| 1096 | @example |
| 1097 | SCM_NFALSEP (scm_string_equal_p (@var{x}, @var{y})) |
| 1098 | @end example |
| 1099 | |
| 1100 | @item @code{gh_null_p} |
| 1101 | Use the @code{SCM_NULLP} macro instead, or replace @code{gh_null_p |
| 1102 | (@var{obj})} by |
| 1103 | @example |
| 1104 | SCM_NFALSEP (scm_null_p (@var{obj})) |
| 1105 | @end example |
| 1106 | |
| 1107 | @item @code{gh_cons} |
| 1108 | Use @code{scm_cons} instead. |
| 1109 | |
| 1110 | @item @code{gh_car} and @code{gh_cdr} |
| 1111 | Use the @code{SCM_CAR} and @code{SCM_CDR} macros instead. |
| 1112 | |
| 1113 | @item @code{gh_cxxr} and @code{gh_cxxxr} |
| 1114 | (Where each x is either @samp{a} or @samp{d}.) Use the corresponding |
| 1115 | @code{SCM_CXXR} or @code{SCM_CXXXR} macro instead. |
| 1116 | |
| 1117 | @item @code{gh_set_car_x} and @code{gh_set_cdr_x} |
| 1118 | Use @code{scm_set_car_x} and @code{scm_set_cdr_x} instead. |
| 1119 | |
| 1120 | @item @code{gh_list} |
| 1121 | Use @code{scm_listify} instead. |
| 1122 | |
| 1123 | @item @code{gh_length} |
| 1124 | Replace @code{gh_length (@var{lst})} by |
| 1125 | @example |
| 1126 | scm_num2ulong (scm_length (@var{lst}), SCM_ARG1, @var{str}) |
| 1127 | @end example |
| 1128 | where @var{str} is a C string that describes the context of the call. |
| 1129 | |
| 1130 | @item @code{gh_append} |
| 1131 | Use @code{scm_append} instead. |
| 1132 | |
| 1133 | @item @code{gh_append2}, @code{gh_append3}, @code{gh_append4} |
| 1134 | Replace @code{gh_append@var{N} (@var{l1}, @dots{}, @var{lN})} by |
| 1135 | @example |
| 1136 | scm_append (scm_listify (@var{l1}, @dots{}, @var{lN}, SCM_UNDEFINED)) |
| 1137 | @end example |
| 1138 | |
| 1139 | @item @code{gh_reverse} |
| 1140 | Use @code{scm_reverse} instead. |
| 1141 | |
| 1142 | @item @code{gh_list_tail} and @code{gh_list_ref} |
| 1143 | Use @code{scm_list_tail} and @code{scm_list_ref} instead. |
| 1144 | |
| 1145 | @item @code{gh_memq}, @code{gh_memv} and @code{gh_member} |
| 1146 | Use @code{scm_memq}, @code{scm_memv} and @code{scm_member} instead. |
| 1147 | |
| 1148 | @item @code{gh_assq}, @code{gh_assv} and @code{gh_assoc} |
| 1149 | Use @code{scm_assq}, @code{scm_assv} and @code{scm_assoc} instead. |
| 1150 | |
| 1151 | @item @code{gh_make_vector} |
| 1152 | Use @code{scm_make_vector} instead. |
| 1153 | |
| 1154 | @item @code{gh_vector} or @code{gh_list_to_vector} |
| 1155 | Use @code{scm_vector} instead. |
| 1156 | |
| 1157 | @item @code{gh_vector_ref} and @code{gh_vector_set_x} |
| 1158 | Use @code{scm_vector_ref} and @code{scm_vector_set_x} instead. |
| 1159 | |
| 1160 | @item @code{gh_vector_length} |
| 1161 | Use the @code{SCM_VECTOR_LENGTH} macro instead. |
| 1162 | |
| 1163 | @item @code{gh_apply} |
| 1164 | Use @code{scm_apply} instead, but note that @code{scm_apply} takes an |
| 1165 | additional third argument that you should set to @code{SCM_EOL}. |
| 1166 | |
| 1167 | @end table |