doc/gh.texi

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