doc/gh.texi

   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 The Guile interpreter is based on Aubrey Jaffer's @emph{SCM} interpreter
   9 (@pxref{Overview, SCM: a portable Scheme interpreter, Overview, scm,
  10 SCM: a portable Scheme interpreter}) with some modifications to make it
  11 suitable as an embedded interpreter, and further modifications as Guile
  12 evolves.
  13 @cindex SCM interpreter
  14 @cindex Jaffer, Aubrey
  15
  16 Part of the modification has been to provide a restricted interface to
  17 limit access to the SCM internals; this is called the @code{gh_}
  18 interface, or @emph{libguile} interface.
  19 @cindex gh_ interface
  20 @cindex libguile interface
  21
  22 If you are @emph{programming with Guile}, you should only use the C
  23 subroutines described in this manual, which all begin with
  24 @code{gh_}.
  25
  26 If instead you are @emph{extending Guile}, you have the entire SCM
  27 source to play with.  This manual will not help you at all, but you can
  28 consult Aubrey Jaffer's SCM manual (@pxref{Internals, SCM: a portable
  29 Scheme interpreter, Internals, scm, SCM: a portable Scheme
  30 interpreter}).
  31 @cindex Guile - extending
  32 @cindex extending Guile
  33 @cindex SCM internals
  34
  35 If you are @emph{adding a module to Guile}, I recommend that you stick
  36 to the @code{gh_} interface: this interface is guaranteed to not
  37 change drastically, while the SCM internals might change as Guile is
  38 developed.
  39
  40
  41 @menu
  42 * gh preliminaries::
  43 * Data types and constants defined by gh::
  44 * Starting and controlling the interpreter::
  45 * Error messages::
  46 * Executing Scheme code::
  47 * Defining new Scheme procedures in C::
  48 * Converting data between C and Scheme::
  49 * Type predicates::
  50 * Equality predicates::
  51 * Memory allocation and garbage collection::
  52 * Calling Scheme procedures from C::
  53 * Mixing gh and scm APIs::
  54 @end menu
  55
  56
  57 @node gh preliminaries
  58 @section gh preliminaries
  59
  60 To use gh, you must have the following toward the beginning of your C
  61 source:
  62 @smallexample
  63 #include <guile/gh.h>
  64 @end smallexample
  65 @cindex gh - headers
  66
  67 When you link, you will have to add at least @code{-lguile} to the list
  68 of libraries.  If you are using more of Guile than the basic Scheme
  69 interpreter, you will have to add more libraries.
  70 @cindex gh - linking
  71
  72
  73 @node Data types and constants defined by gh
  74 @section Data types and constants defined by gh
  75 @cindex libguile - data types
  76
  77 The following C constants and data types are defined in gh:
  78
  79 @deftp {Data type} SCM
  80 This is a C data type used to store all Scheme data, no matter what the
  81 Scheme type.  Values are converted between C data types and the SCM type
  82 with utility functions described below (@pxref{Converting data between C
  83 and Scheme}).  [FIXME: put in references to Jim's essay and so forth.]
  84 @end deftp
  85 @cindex SCM data type
  86
  87 @defvr Constant SCM_BOOL_T
  88 @defvrx Constant SCM_BOOL_F
  89 The @emph{Scheme} values returned by many boolean procedures in
  90 libguile.
  91
  92 This can cause confusion because they are different from 0 and 1.  In
  93 testing a boolean function in libguile programming, you must always make
  94 sure that you check the spec: @code{gh_} and @code{scm_} functions will
  95 usually return @code{SCM_BOOL_T} and @code{SCM_BOOL_F}, but other C
  96 functions usually can be tested against 0 and 1, so programmers' fingers
  97 tend to just type @code{if (boolean_function()) @{ ... @}}
  98 @end defvr
  99
 100 @defvr Constant SCM_UNSPECIFIED
 101 This is an SCM object which does not correspond to any legal Scheme
 102 value.  It can be used in C to terminate functions with variable numbers
 103 of arguments, such as @code{gh_list()}.
 104 @end defvr
 105
 106
 107 @node Starting and controlling the interpreter
 108 @section Starting and controlling the interpreter
 109 @cindex libguile - start interpreter
 110
 111 In almost every case, your first @code{gh_} call will be:
 112
 113 @deftypefun void gh_enter (int @var{argc}, char *@var{argv}[], void (*@var{main_prog})())
 114 Starts up a Scheme interpreter with all the builtin Scheme primitives.
 115 @code{gh_enter()} never exits, and the user's code should all be in the
 116 @code{@var{main_prog}()} function.  @code{argc} and @code{argv} will be
 117 passed to @var{main_prog}.
 118
 119 @deftypefun void main_prog (int @var{argc}, char *@var{argv}[])
 120 This is the user's main program.  It will be invoked by
 121 @code{gh_enter()} after Guile has been started up.
 122 @end deftypefun
 123
 124 Note that you can use @code{gh_repl} inside @code{gh_enter} (in other
 125 words, inside the code for @code{main-prog}) if you want the program to
 126 be controled by a Scheme read-eval-print loop.
 127 @end deftypefun
 128
 129 @cindex read eval print loop -- from the gh_ interface
 130 @cindex REPL -- from the gh_ interface
 131 A convenience routine which enters the Guile interpreter with the
 132 standard Guile read-eval-print loop (@dfn{REPL}) is:
 133
 134 @deftypefun void gh_repl (int @var{argc}, char *@var{argv}[])
 135 Enters the Scheme interpreter giving control to the Scheme REPL.
 136 Arguments are processed as if the Guile program @file{guile} were being
 137 invoked.
 138
 139 Note that @code{gh_repl} should be used @emph{inside} @code{gh_enter},
 140 since any Guile interpreter calls are meaningless unless they happen in
 141 the context of the interpreter.
 142
 143 Also note that when you use @code{gh_repl}, your program will be
 144 controlled by Guile's REPL (which is written in Scheme and has many
 145 useful features).  Use straight C code inside @code{gh_enter} if you
 146 want to maintain execution control in your C program.
 147 @end deftypefun
 148
 149 You will typically use @code{gh_enter} and @code{gh_repl} when you
 150 want a Guile interpreter enhanced by your own libraries, but otherwise
 151 quite normal.  For example, to build a Guile--derived program that
 152 includes some random number routines @dfn{GSL} (GNU Scientific Library),
 153 you would write a C program that looks like this:
 154
 155 @smallexample
 156 #include <guile/gh.h>
 157 #include <gsl_ran.h>
 158
 159 /* random number suite */
 160 SCM gw_ran_seed(SCM s)
 161 @{
 162   gsl_ran_seed(gh_scm2int(s));
 163   return SCM_UNSPECIFIED;
 164 @}
 165
 166 SCM gw_ran_random()
 167 @{
 168   SCM x;
 169
 170   x = gh_ulong2scm(gsl_ran_random());
 171   return x;
 172 @}
 173
 174 SCM gw_ran_uniform()
 175 @{
 176   SCM x;
 177
 178   x = gh_double2scm(gsl_ran_uniform());
 179   return x;
 180 @}
 181 SCM gw_ran_max()
 182 @{
 183   return gh_double2scm(gsl_ran_max());
 184 @}
 185
 186 void
 187 init_gsl()
 188 @{
 189   /* random number suite */
 190   gh_new_procedure("gsl-ran-seed", gw_ran_seed, 1, 0, 0);
 191   gh_new_procedure("gsl-ran-random", gw_ran_random, 0, 0, 0);
 192   gh_new_procedure("gsl-ran-uniform", gw_ran_uniform, 0, 0, 0);
 193   gh_new_procedure("gsl-ran-max", gw_ran_max, 0, 0, 0);
 194 @}
 195
 196 void
 197 main_prog (int argc, char *argv[])
 198 @{
 199   init_gsl();
 200
 201   gh_repl(argc, argv);
 202 @}
 203
 204 int
 205 main (int argc, char *argv[])
 206 @{
 207   gh_enter (argc, argv, main_prog);
 208 @}
 209 @end smallexample
 210
 211 Then, supposing the C program is in @file{guile-gsl.c}, you could
 212 compile it with @kbd{gcc -o guile-gsl guile-gsl.c -lguile -lgsl}.
 213
 214 The resulting program @file{guile-gsl} would have new primitive
 215 procedures @code{gsl-ran-random}, @code{gsl-ran-gaussian} and so forth.
 216
 217
 218 @node Error messages
 219 @section Error messages
 220 @cindex libguile - error messages
 221 @cindex error messages in libguile
 222
 223 [FIXME: need to fill this based on Jim's new mechanism]
 224
 225
 226 @node Executing Scheme code
 227 @section Executing Scheme code
 228 @cindex libguile - executing Scheme
 229 @cindex executing Scheme
 230
 231 Once you have an interpreter running, you can ask it to evaluate Scheme
 232 code.  There are two calls that implement this:
 233
 234 @deftypefun SCM gh_eval_str (char *@var{scheme_code})
 235 This asks the interpreter to evaluate a single string of Scheme code,
 236 and returns the result of the last expression evaluated.
 237
 238 Note that the line of code in @var{scheme_code} must be a well formed
 239 Scheme expression.  If you have many lines of code before you balance
 240 parentheses, you must either concatenate them into one string, or use
 241 @code{gh_eval_file()}.
 242 @end deftypefun
 243
 244 @deftypefun SCM gh_eval_file (char *@var{fname})
 245 @deftypefunx SCM gh_load (char *@var{fname})
 246 @code{gh_eval_file} is completely analogous to @code{gh_eval_str()},
 247 except that a whole file is evaluated instead of a string.  Returns the
 248 result of the last expression evaluated.
 249
 250 @code{gh_load} is identical to @code{gh_eval_file} (it's a macro that
 251 calls @code{gh_eval_file} on its argument).  It is provided to start
 252 making the @code{gh_} interface match the R4RS Scheme procedures
 253 closely.
 254 @end deftypefun
 255
 256
 257 @node Defining new Scheme procedures in C
 258 @section Defining new Scheme procedures in C
 259 @cindex libguile - new procedures
 260 @cindex new procedures
 261 @cindex procedures, new
 262 @cindex new primitives
 263 @cindex primitives, new
 264
 265 The real interface between C and Scheme comes when you can write new
 266 Scheme procedures in C.  This is done through the routine
 267
 268
 269 @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})
 270 @code{gh_new_procedure} defines a new Scheme procedure.  Its Scheme name
 271 will be @var{proc_name}, it will be implemented by the C function
 272 (*@var{fn})(), it will take at least @var{n_required_args} arguments,
 273 and at most @var{n_optional_args} extra arguments.
 274
 275 When the @var{restp} parameter is 1, the procedure takes a final
 276 argument: a list of remaining parameters.
 277
 278 @code{gh_new_procedure} returns an SCM value representing the procedure.
 279
 280 The C function @var{fn} should have the form
 281 @deftypefn {Libguile high} SCM fn (SCM @var{req1}, SCM @var{req2}, ..., SCM @var{opt1},  SCM @var{opt2}, ...,  SCM @var{rest_args})
 282 The arguments are all passed as SCM values, so the user will have to use
 283 the conversion functions to convert to standard C types.
 284
 285 Examples of C functions used as new Scheme primitives can be found in
 286 the sample programs @code{learn0} and @code{learn1}.
 287 @end deftypefn
 288
 289 @end deftypefn
 290
 291 @strong{Rationale:} this is the correct way to define new Scheme
 292 procedures in C.  The ugly mess of arguments is required because of how
 293 C handles procedures with variable numbers of arguments.
 294
 295 @strong{Note:} what about documentation strings?
 296
 297 @cartouche
 298 There are several important considerations to be made when writing the C
 299 routine @code{(*fn)()}.
 300
 301 First of all the C routine has to return type @code{SCM}.
 302
 303 Second, all arguments passed to the C funcion will be of type
 304 @code{SCM}.
 305
 306 Third: the C routine is now subject to Scheme flow control, which means
 307 that it could be interrupted at any point, and then reentered.  This
 308 means that you have to be very careful with operations such as
 309 allocating memory, modifying static data @dots{}
 310
 311 Fourth: to get around the latter issue, you can use
 312 @code{GH_DEFER_INTS} and @code{GH_ALLOW_INTS}.
 313 @end cartouche
 314
 315 @defmac GH_DEFER_INTS
 316 @defmacx GH_ALLOW_INTS
 317 These macros disable and reenable Scheme's flow control.  They
 318 @end defmac
 319
 320
 321 @c [??? have to do this right; maybe using subsections, or maybe creating a
 322 @c section called Flow control issues...]
 323
 324 @c [??? Go into exhaustive detail with examples of the various possible
 325 @c combinations of required and optional args...]
 326
 327
 328 @node Converting data between C and Scheme
 329 @section Converting data between C and Scheme
 330 @cindex libguile - converting data
 331 @cindex data conversion
 332 @cindex converting data
 333
 334 Guile provides mechanisms to convert data between C and Scheme.  This
 335 allows new builtin procedures to understand their arguments (which are
 336 of type @code{SCM}) and return values of type @code{SCM}.
 337
 338
 339 @menu
 340 * C to Scheme::
 341 * Scheme to C::
 342 @end menu
 343
 344 @node C to Scheme
 345 @subsection C to Scheme
 346
 347 @deftypefun SCM gh_bool2scm (int @var{x})
 348 Returns @code{#f} if @var{x} is zero, @code{#t} otherwise.
 349 @end deftypefun
 350
 351 @deftypefun SCM gh_ulong2scm (unsigned long @var{x})
 352 @deftypefunx SCM gh_long2scm (long @var{x})
 353 @deftypefunx SCM gh_double2scm (double @var{x})
 354 @deftypefunx SCM gh_char2scm (char @var{x})
 355 Returns a Scheme object with the value of the C quantity @var{x}.
 356 @end deftypefun
 357
 358 @deftypefun SCM gh_str2scm (char *@var{s}, int @var{len})
 359 Returns a new Scheme string with the (not necessarily null-terminated) C
 360 array @var{s} data.
 361 @end deftypefun
 362
 363 @deftypefun SCM gh_str02scm (char *@var{s})
 364 Returns a new Scheme string with the null-terminated C string @var{s}
 365 data.
 366 @end deftypefun
 367
 368 @deftypefun SCM gh_set_substr (char *@var{src}, SCM @var{dst}, int @var{start}, int @var{len})
 369 Copy @var{len} characters at @var{src} into the @emph{existing} Scheme
 370 string @var{dst}, starting at @var{start}.  @var{start} is an index into
 371 @var{dst}; zero means the beginning of the string.
 372
 373 If @var{start} + @var{len} is off the end of @var{dst}, signal an
 374 out-of-range error.
 375 @end deftypefun
 376
 377 @deftypefun SCM gh_symbol2scm (char *@var{name})
 378 Given a null-terminated string @var{name}, return the symbol with that
 379 name.
 380 @end deftypefun
 381
 382 @deftypefun SCM gh_ints2scm (int *@var{dptr}, int @var{n})
 383 @deftypefunx SCM gh_doubles2scm (double *@var{dptr}, int @var{n})
 384 Make a scheme vector containing the @var{n} ints or doubles at memory
 385 location @var{dptr}.
 386 @end deftypefun
 387
 388 @deftypefun SCM gh_chars2byvect (char *@var{dptr}, int @var{n})
 389 @deftypefunx SCM gh_shorts2svect (short *@var{dptr}, int @var{n})
 390 @deftypefunx SCM gh_longs2ivect (long *@var{dptr}, int @var{n})
 391 @deftypefunx SCM gh_ulongs2uvect (ulong *@var{dptr}, int @var{n})
 392 @deftypefunx SCM gh_floats2fvect (float *@var{dptr}, int @var{n})
 393 @deftypefunx SCM gh_doubles2dvect (double *@var{dptr}, int @var{n})
 394 Make a scheme uniform vector containing the @var{n} chars, shorts,
 395 longs, unsigned longs, floats or doubles at memory location @var{dptr}.
 396 @end deftypefun
 397
 398
 399
 400 @node Scheme to C
 401 @subsection Scheme to C
 402
 403 @deftypefun int gh_scm2bool (SCM @var{obj})
 404 @deftypefunx {unsigned long} gh_scm2ulong (SCM @var{obj})
 405 @deftypefunx long gh_scm2long (SCM @var{obj})
 406 @deftypefunx double gh_scm2double (SCM @var{obj})
 407 @deftypefunx int gh_scm2char (SCM @var{obj})
 408 These routines convert the Scheme object to the given C type.
 409 @end deftypefun
 410
 411 @deftypefun char *gh_scm2newstr (SCM @var{str}, int *@var{lenp})
 412 Given a Scheme string @var{str}, return a pointer to a new copy of its
 413 contents, followed by a null byte.  If @var{lenp} is non-null, set
 414 @code{*@var{lenp}} to the string's length.
 415
 416 This function uses malloc to obtain storage for the copy; the caller is
 417 responsible for freeing it.
 418
 419 Note that Scheme strings may contain arbitrary data, including null
 420 characters.  This means that null termination is not a reliable way to
 421 determine the length of the returned value.  However, the function
 422 always copies the complete contents of @var{str}, and sets @var{*lenp}
 423 to the true length of the string (when @var{lenp} is non-null).
 424 @end deftypefun
 425
 426
 427 @deftypefun void gh_get_substr (SCM str, char *return_str, int *lenp)
 428 Copy @var{len} characters at @var{start} from the Scheme string
 429 @var{src} to memory at @var{dst}.  @var{start} is an index into
 430 @var{src}; zero means the beginning of the string.  @var{dst} has
 431 already been allocated by the caller.
 432
 433 If @var{start} + @var{len} is off the end of @var{src}, signal an
 434 out-of-range error.
 435 @end deftypefun
 436
 437 @deftypefun char *gh_symbol2newstr (SCM @var{sym}, int *@var{lenp})
 438 Takes a Scheme symbol and returns a string of the form
 439 @code{"'symbol-name"}.  If @var{lenp} is non-null, the string's length
 440 is returned in @code{*@var{lenp}}.
 441
 442 This function uses malloc to obtain storage for the returned string; the
 443 caller is responsible for freeing it.
 444 @end deftypefun
 445
 446 @deftypefun char *gh_scm2chars (SCM @var{vector}, chars *@var{result})
 447 @deftypefunx short *gh_scm2shorts (SCM @var{vector}, short *@var{result})
 448 @deftypefunx long *gh_scm2longs (SCM @var{vector}, long *@var{result})
 449 @deftypefunx float *gh_scm2floats (SCM @var{vector}, float *@var{result})
 450 @deftypefunx double *gh_scm2doubles (SCM @var{vector}, double *@var{result})
 451 Copy the numbers in @var{vector} to the array pointed to by @var{result}
 452 and return it.  If @var{result} is NULL, allocate a double array large
 453 enough.
 454
 455 @var{vector} can be an ordinary vector, a weak vector, or a signed or
 456 unsigned uniform vector of the same type as the result array.  For
 457 chars, @var{vector} can be a string or substring.  For floats and
 458 doubles, @var{vector} can contain a mix of inexact and integer values.
 459
 460 If @var{vector} is of unsigned type and contains values too large to fit
 461 in the signed destination array, those values will be wrapped around,
 462 that is, data will be copied as if the destination array was unsigned.
 463 @end deftypefun
 464
 465
 466 @node Type predicates
 467 @section Type predicates
 468
 469 These C functions mirror Scheme's type predicate procedures with one
 470 important difference.  The C routines return C boolean values (0 and 1)
 471 instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}.
 472
 473 The Scheme notational convention of putting a @code{?} at the end of
 474 predicate procedure names is mirrored in C by placing @code{_p} at the
 475 end of the procedure.  For example, @code{(pair? ...)} maps to
 476 @code{gh_pair_p(...)}.
 477
 478 @deftypefun int gh_boolean_p (SCM @var{val})
 479 Returns 1 if @var{val} is a boolean, 0 otherwise.
 480 @end deftypefun
 481
 482 @deftypefun int gh_symbol_p (SCM @var{val})
 483 Returns 1 if @var{val} is a symbol, 0 otherwise.
 484 @end deftypefun
 485
 486 @deftypefun int gh_char_p (SCM @var{val})
 487 Returns 1 if @var{val} is a char, 0 otherwise.
 488 @end deftypefun
 489
 490 @deftypefun int gh_vector_p (SCM @var{val})
 491 Returns 1 if @var{val} is a vector, 0 otherwise.
 492 @end deftypefun
 493
 494 @deftypefun int gh_pair_p (SCM @var{val})
 495 Returns 1 if @var{val} is a pair, 0 otherwise.
 496 @end deftypefun
 497
 498 @deftypefun int gh_procedure_p (SCM @var{val})
 499 Returns 1 if @var{val} is a procedure, 0 otherwise.
 500 @end deftypefun
 501
 502 @deftypefun int gh_list_p (SCM @var{val})
 503 Returns 1 if @var{val} is a list, 0 otherwise.
 504 @end deftypefun
 505
 506 @deftypefun int gh_inexact_p (SCM @var{val})
 507 Returns 1 if @var{val} is an inexact number, 0 otherwise.
 508 @end deftypefun
 509
 510 @deftypefun int gh_exact_p (SCM @var{val})
 511 Returns 1 if @var{val} is an exact number, 0 otherwise.
 512 @end deftypefun
 513
 514
 515 @node Equality predicates
 516 @section Equality predicates
 517
 518 These C functions mirror Scheme's equality predicate procedures with one
 519 important difference.  The C routines return C boolean values (0 and 1)
 520 instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}.
 521
 522 The Scheme notational convention of putting a @code{?} at the end of
 523 predicate procedure names is mirrored in C by placing @code{_p} at the
 524 end of the procedure.  For example, @code{(equal? ...)} maps to
 525 @code{gh_equal_p(...)}.
 526
 527 @deftypefun int gh_eq_p (SCM x, SCM y)
 528 Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
 529 @code{eq?} predicate, 0 otherwise.
 530 @end deftypefun
 531
 532 @deftypefun int gh_eqv_p (SCM x, SCM y)
 533 Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
 534 @code{eqv?} predicate, 0 otherwise.
 535 @end deftypefun
 536
 537 @deftypefun int gh_equal_p (SCM x, SCM y)
 538 Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
 539 @code{equal?} predicate, 0 otherwise.
 540 @end deftypefun
 541
 542 @deftypefun int gh_string_equal_p (SCM @var{s1}, SCM @var{s2})
 543 Returns 1 if the strings @var{s1} and @var{s2} are equal, 0 otherwise.
 544 @end deftypefun
 545
 546 @deftypefun int gh_null_p (SCM @var{l})
 547 Returns 1 if @var{l} is an empty list or pair; 0 otherwise.
 548 @end deftypefun
 549
 550
 551 @node Memory allocation and garbage collection
 552 @section Memory allocation and garbage collection
 553
 554 @c [FIXME: flesh this out with some description of garbage collection in
 555 @c scm/guile]
 556
 557 @c @deftypefun SCM gh_mkarray (int size)
 558 @c Allocate memory for a Scheme object in a garbage-collector-friendly
 559 @c manner.
 560 @c @end deftypefun
 561
 562
 563 @node Calling Scheme procedures from C
 564 @section Calling Scheme procedures from C
 565
 566 Many of the Scheme primitives are available in the @code{gh_}
 567 interface; they take and return objects of type SCM, and one could
 568 basically use them to write C code that mimics Scheme code.
 569
 570 I will list these routines here without much explanation, since what
 571 they do is the same as documented in @ref{Standard Procedures, R4RS, ,
 572 r4rs, R4RS}.  But I will point out that when a procedure takes a
 573 variable number of arguments (such as @code{gh_list}), you should pass
 574 the constant @var{SCM_EOL} from C to signify the end of the list.
 575
 576 @deftypefun SCM gh_define (char *@var{name}, SCM @var{val})
 577 Corresponds to the Scheme @code{(define name val)}: it binds a value to
 578 the given name (which is a C string).  Returns the new object.
 579 @end deftypefun
 580
 581 @heading Pairs and lists
 582
 583 @deftypefun SCM gh_cons (SCM @var{a}, SCM @var{b})
 584 @deftypefunx SCM gh_list (SCM l0, SCM l1, ... , SCM_UNDEFINED)
 585 These correspond to the Scheme @code{(cons a b)} and @code{(list l0 l1
 586 ...)} procedures.  Note that @code{gh_list()} is a C macro that invokes
 587 @code{scm_listify()}.
 588 @end deftypefun
 589
 590 @deftypefun SCM gh_set_car (SCM @var{obj}, SCM @var{val})
 591 @deftypefunx SCM gh_set_cdr (SCM @var{obj}, SCM @var{val})
 592 These correspond to the Scheme @code{(set-car! ...)} and @code{(set-cdr!
 593 ...)} procedures.
 594 @end deftypefun
 595
 596
 597 @deftypefun SCM gh_car (SCM @var{obj})
 598 @deftypefunx SCM gh_cdr (SCM @var{obj})
 599 @dots{}
 600
 601 @deftypefunx SCM gh_c[ad][ad][ad][ad]r (SCM @var{obj})
 602 These correspond to the Scheme @code{(caadar ls)} procedures etc @dots{}
 603 @end deftypefun
 604
 605 @deftypefun SCM gh_set_car_x(SCM @var{pair}, SCM @var{value})
 606 Modifies the CAR of @var{pair} to be @var{value}.  This is equivalent to
 607 the Scheme procedure @code{(set-car! ...)}.
 608 @end deftypefun
 609
 610 @deftypefun SCM gh_set_cdr_x(SCM @var{pair}, SCM @var{value})
 611 Modifies the CDR of @var{pair} to be @var{value}.  This is equivalent to
 612 the Scheme procedure @code{(set-cdr! ...)}.
 613 @end deftypefun
 614
 615 @deftypefun {unsigned long} gh_length (SCM @var{ls})
 616 Returns the length of the list.
 617 @end deftypefun
 618
 619 @deftypefun SCM gh_append (SCM @var{args})
 620 @deftypefunx SCM gh_append2 (SCM @var{l1}, SCM @var{l2})
 621 @deftypefunx SCM gh_append3 (SCM @var{l1}, SCM @var{l2}, @var{l3})
 622 @deftypefunx SCM gh_append4 (SCM @var{l1}, SCM @var{l2}, @var{l3}, @var{l4})
 623 @code{gh_append()} takes @var{args}, which is a list of lists
 624 @code{(list1 list2 ...)}, and returns a list containing all the elements
 625 of the individual lists.
 626
 627 A typical invocation of @code{gh_append()} to append 5 lists together
 628 would be
 629 @smallexample
 630   gh_append(gh_list(l1, l2, l3, l4, l5, SCM_UNDEFINED));
 631 @end smallexample
 632
 633 The functions @code{gh_append2()}, @code{gh_append2()},
 634 @code{gh_append3()} and @code{gh_append4()} are convenience routines to
 635 make it easier for C programs to form the list of lists that goes as an
 636 argument to @code{gh_append()}.
 637 @end deftypefun
 638
 639 @deftypefun SCM gh_reverse (SCM @var{ls})
 640 Returns a new list that has the same elements as @var{ls} but in the
 641 reverse order.  Note that this is implemented as a macro which calls
 642 @code{scm_reverse()}.
 643 @end deftypefun
 644
 645 @deftypefun SCM gh_list_tail (SCM @var{ls}, SCM @var{k})
 646 Returns the sublist of @var{ls} with the last @var{k} elements.
 647 @end deftypefun
 648
 649 @deftypefun SCM gh_list_ref (SCM @var{ls}, SCM @var{k})
 650 Returns the @var{k}th element of the list @var{ls}.
 651 @end deftypefun
 652
 653 @deftypefun SCM gh_memq (SCM @var{x}, SCM @var{ls})
 654 @deftypefunx SCM gh_memv (SCM @var{x}, SCM @var{ls})
 655 @deftypefunx SCM gh_member (SCM @var{x}, SCM @var{ls})
 656 These functions return the first sublist of @var{ls} whose CAR is
 657 @var{x}.  They correspond to @code{(memq x ls)}, @code{(memv x ls)} and
 658 @code{(member x ls)}, and hence use (respectively) @code{eq?},
 659 @code{eqv?} and @code{equal?} to do comparisons.
 660
 661 If @var{x} does not appear in @var{ls}, the value @code{SCM_BOOL_F} (not
 662 the empty list) is returned.
 663
 664 Note that these functions are implemented as macros which call
 665 @code{scm_memq()}, @code{scm_memv()} and @code{scm_member()}
 666 respectively.
 667 @end deftypefun
 668
 669 @deftypefun SCM gh_assq (SCM @var{x}, SCM @var{alist})
 670 @deftypefunx SCM gh_assv (SCM @var{x}, SCM @var{alist})
 671 @deftypefunx SCM gh_assoc (SCM @var{x}, SCM @var{alist})
 672 These functions search an @dfn{association list} (list of pairs)
 673 @var{alist} for the first pair whose CAR is @var{x}, and they return
 674 that pair.
 675
 676 If no pair in @var{alist} has @var{x} as its CAR, the value
 677 @code{SCM_BOOL_F} (not the empty list) is returned.
 678
 679 Note that these functions are implemented as macros which call
 680 @code{scm_assq()}, @code{scm_assv()} and @code{scm_assoc()}
 681 respectively.
 682 @end deftypefun
 683
 684
 685 @heading Symbols
 686
 687 @c @deftypefun SCM gh_symbol (SCM str, SCM len)
 688 @c @deftypefunx SCM gh_tmp_symbol (SCM str, SCM len)
 689 @c Takes the given string @var{str} of length @var{len} and returns a
 690 @c symbol corresponding to that string.
 691 @c @end deftypefun
 692
 693
 694 @heading Vectors
 695
 696 @deftypefun SCM gh_make_vector (SCM @var{n}, SCM @var{fill})
 697 @deftypefunx SCM gh_vector (SCM @var{ls})
 698 @deftypefunx SCM gh_vector_ref (SCM @var{v}, SCM @var{i})
 699 @deftypefunx SCM gh_vector_set (SCM @var{v}, SCM @var{i}, SCM @var{val})
 700 @deftypefunx {unsigned long} gh_vector_length (SCM @var{v})
 701 @deftypefunx SCM gh_list_to_vector (SCM @var{ls})
 702 These correspond to the Scheme @code{(make-vector n fill)},
 703 @code{(vector a b c ...)} @code{(vector-ref v i)} @code{(vector-set v i
 704 value)} @code{(vector-length v)} @code{(list->vector ls)} procedures.
 705
 706 The correspondence is not perfect for @code{gh_vector}: this routine
 707 taks a list @var{ls} instead of the individual list elements, thus
 708 making it identical to @code{gh_list_to_vector}.
 709
 710 There is also a difference in gh_vector_length: the value returned is a
 711 C @code{unsigned long} instead of an SCM object.
 712 @end deftypefun
 713
 714
 715 @heading Procedures
 716
 717 @c @deftypefun SCM gh_make_subr (SCM (*@var{fn})(), int @var{req}, int @var{opt}, int @var{restp}, char *@var{sym})
 718 @c Make the C function @var{fn} available to Scheme programs.  The function
 719 @c will be bound to the symbol @var{sym}.  The arguments @var{req},
 720 @c @var{opt} and @var{restp} describe @var{fn}'s calling conventions.  The
 721 @c function must take @var{req} required arguments and may take @var{opt}
 722 @c optional arguments.  Any optional arguments which are not supplied by
 723 @c the caller will be bound to @var{SCM_UNSPECIFIED}.  If @var{restp} is
 724 @c non-zero, it means that @var{fn} may be called with an arbitrary number
 725 @c of arguments, and that any extra arguments supplied by the caller will
 726 @c be passed to @var{fn} as a list.  The @var{restp} argument is exactly
 727 @c like Scheme's @code{(lambda (arg1 arg2 . arglist))} calling convention.
 728 @c
 729 @c For example, the procedure @code{read-line}, which takes optional
 730 @c @var{port} and @var{handle-delim} arguments, would be declared like so:
 731 @c
 732 @c @example
 733 @c SCM scm_read_line (SCM port, SCM handle_delim);
 734 @c gh_make_subr (scm_read_line, 0, 2, 0, "read-line");
 735 @c @end example
 736 @c
 737 @c The @var{req} argument to @code{gh_make_subr} is 0 to indicate that
 738 @c there are no required arguments, so @code{read-line} may be called
 739 @c without any arguments at all.  The @var{opt} argument is 2, to indicate
 740 @c that both the @var{port} and @var{handle_delim} arguments to
 741 @c @code{scm_read_line} are optional, and will be bound to
 742 @c @code{SCM_UNSPECIFIED} if the calling program does not supply them.
 743 @c Because the @var{restp} argument is 0, this function may not be called
 744 @c with more than two arguments.
 745 @c @end deftypefun
 746
 747 @deftypefun SCM gh_apply (SCM proc, SCM args)
 748 Call the Scheme procedure @var{proc}, with the elements of @var{args} as
 749 arguments.  @var{args} must be a proper list.
 750 @end deftypefun
 751
 752 @deftypefun SCM gh_call0 (SCM proc)
 753 @deftypefunx SCM gh_call1 (SCM proc, SCM arg)
 754 @deftypefunx SCM gh_call2 (SCM proc, SCM arg1, SCM arg2)
 755 @deftypefunx SCM gh_call3 (SCM proc, SCM arg1, SCM arg2, SCM arg3)
 756 Call the Scheme procedure @var{proc} with no arguments
 757 (@code{gh_call0}), one argument (@code{gh_call1}), and so on.  You can
 758 get the same effect by wrapping the arguments up into a list, and
 759 calling @code{gh_apply}; Guile provides these functions for convenience.
 760 @end deftypefun
 761
 762
 763 @deftypefun SCM gh_catch (SCM key, SCM thunk, SCM handler)
 764 @deftypefunx SCM gh_throw (SCM key, SCM args)
 765 Corresponds to the Scheme @code{catch} and @code{throw} procedures,
 766 which in Guile are provided as primitives.
 767 @end deftypefun
 768
 769 @c [FIXME: must add the I/O section in gscm.h]
 770
 771 @deftypefun SCM gh_is_eq (SCM a, SCM b)
 772 @deftypefunx SCM gh_is_eqv (SCM a, SCM b)
 773 @deftypefunx SCM gh_is_equal (SCM a, SCM b)
 774 These correspond to the Scheme @code{eq?}, @code{eqv?} and @code{equal?}
 775 predicates.
 776 @end deftypefun
 777
 778 @deftypefun int gh_obj_length (SCM @var{obj})
 779 Returns the raw object length.
 780 @end deftypefun
 781
 782 @heading Data lookup
 783
 784 For now I just include Tim Pierce's comments from the @file{gh_data.c}
 785 file; it should be organized into a documentation of the two functions
 786 here.
 787
 788 @smallexample
 789 /* Data lookups between C and Scheme
 790
 791    Look up a symbol with a given name, and return the object to which
 792    it is bound.  gh_lookup examines the Guile top level, and
 793    gh_module_lookup checks the module namespace specified by the
 794    `vec' argument.
 795
 796    The return value is the Scheme object to which SNAME is bound, or
 797    SCM_UNDEFINED if SNAME is not bound in the given context. [FIXME:
 798    should this be SCM_UNSPECIFIED?  Can a symbol ever legitimately be
 799    bound to SCM_UNDEFINED or SCM_UNSPECIFIED?  What is the difference?
 800    -twp] */
 801 @end smallexample
 802
 803
 804 @node Mixing gh and scm APIs
 805 @section Mixing gh and scm APIs