diff options
Diffstat (limited to 'doc/ref/gh.texi')
-rw-r--r-- | doc/ref/gh.texi | 1170 |
1 files changed, 0 insertions, 1170 deletions
diff --git a/doc/ref/gh.texi b/doc/ref/gh.texi deleted file mode 100644 index 1cadc168a..000000000 --- a/doc/ref/gh.texi +++ /dev/null @@ -1,1170 +0,0 @@ -@page -@node GH -@chapter GH: A Portable C to Scheme Interface -@cindex libguile - gh -@cindex gh -@cindex gh - reference manual - -This chapter shows how to use the GH interface to call Guile from your -application's C code, and to add new Scheme level procedures to Guile -whose behaviour is specified by application specific code written in C. - -Note, however, that the GH interface is now deprecated, and developers -are encouraged to switch to using the scm interface instead. Therefore, -for each GH feature, this chapter should also document how to achieve -the same result using the scm interface. - -@menu -* GH deprecation:: Why the GH interface is now deprecated. -* gh preliminaries:: -* Data types and constants defined by gh:: -* Starting and controlling the interpreter:: -* Error messages:: -* Executing Scheme code:: -* Defining new Scheme procedures in C:: -* Converting data between C and Scheme:: -* Type predicates:: -* Equality predicates:: -* Memory allocation and garbage collection:: -* Calling Scheme procedures from C:: -* Mixing gh and scm APIs:: -* scm transition summary:: -@end menu - - -@node GH deprecation -@section Why the GH Interface is Now Deprecated - -Historically, the GH interface was the product of a practical problem -and a neat idea. The practical problem was that the interface of the -@code{scm_} functions with which Guile itself was written (inherited -from Aubrey Jaffer's SCM) was so closely tied to the (rather arcane) -details of the internal data representation that it was extremely -difficult to write a Guile extension using these functions. The neat -idea was to define a high level language extension interface in such a -way that other extension language projects, not just Guile, would be -able to provide an implementation of that interface; then applications -using this interface could be compiled with whichever of the various -available implementations they chose. So the GH interface was created, -and advertised both as the recommended interface for application -developers wishing to use Guile, and as a portable high level interface -that could theoretically be implemented by other extension language -projects. - -Time passed, and various things changed. Crucially, an enormous number -of improvements were made to the @code{scm_} interface that Guile itself -uses in its implementation, with the result that it is now both easy and -comfortable to write a Guile extension with this interface. At the same -time, the contents of the GH interface were somewhat neglected by the -core Guile developers, such that some key operations --- such as smob -creation and management --- are simply not possible using GH alone. -Finally, the idea of multiple implementations of the GH interface did -not really crystallize (apart, I believe, from a short lived -implementation by the MzScheme project). - -For all these reasons, the Guile developers have decided to deprecate -the GH interface --- which means that support for GH will be completely -removed after the next few releases --- and to focus only on the -@code{scm_} interface, with additions to ensure that it is as easy to -use in all respects as GH was. - -It remains an open question whether a deep kind of interface portability -would be useful for extension language-based applications, and it may -still be an interesting project to attempt to define a corresponding -GH-like interface, but the Guile developers no longer plan to try to do -this as part of the core Guile project. - - -@node gh preliminaries -@section gh preliminaries - -To use gh, you must have the following toward the beginning of your C -source: -@smallexample -#include <guile/gh.h> -@end smallexample -@cindex gh - headers - -When you link, you will have to add at least @code{-lguile} to the list -of libraries. If you are using more of Guile than the basic Scheme -interpreter, you will have to add more libraries. -@cindex gh - linking - - -@node Data types and constants defined by gh -@section Data types and constants defined by gh -@cindex libguile - data types - -The following C constants and data types are defined in gh: - -@deftp {Data type} SCM -This is a C data type used to store all Scheme data, no matter what the -Scheme type. Values are converted between C data types and the SCM type -with utility functions described below (@pxref{Converting data between C -and Scheme}). [FIXME: put in references to Jim's essay and so forth.] -@end deftp -@cindex SCM data type - -@defvr Constant SCM_BOOL_T -@defvrx Constant SCM_BOOL_F -The @emph{Scheme} values returned by many boolean procedures in -libguile. - -This can cause confusion because they are different from 0 and 1. In -testing a boolean function in libguile programming, you must always make -sure that you check the spec: @code{gh_} and @code{scm_} functions will -usually return @code{SCM_BOOL_T} and @code{SCM_BOOL_F}, but other C -functions usually can be tested against 0 and 1, so programmers' fingers -tend to just type @code{if (boolean_function()) @{ ... @}} -@end defvr - -@defvr Constant SCM_UNSPECIFIED -This is a SCM value that is not the same as any legal Scheme value. It -is the value that a Scheme function returns when its specification says -that its return value is unspecified. -@end defvr - -@defvr Constant SCM_UNDEFINED -This is another SCM value that is not the same as any legal Scheme -value. It is the value used to mark variables that do not yet have a -value, and it is also used in C to terminate functions with variable -numbers of arguments, such as @code{gh_list()}. -@end defvr - - -@node Starting and controlling the interpreter -@section Starting and controlling the interpreter -@cindex libguile - start interpreter - -In almost every case, your first @code{gh_} call will be: - -@deftypefun void gh_enter (int @var{argc}, char *@var{argv}[], void (*@var{main_prog})()) -Starts up a Scheme interpreter with all the builtin Scheme primitives. -@code{gh_enter()} never exits, and the user's code should all be in the -@code{@var{main_prog}()} function. @code{argc} and @code{argv} will be -passed to @var{main_prog}. - -@deftypefun void main_prog (int @var{argc}, char *@var{argv}[]) -This is the user's main program. It will be invoked by -@code{gh_enter()} after Guile has been started up. -@end deftypefun - -Note that you can use @code{gh_repl} inside @code{gh_enter} (in other -words, inside the code for @code{main-prog}) if you want the program to -be controlled by a Scheme read-eval-print loop. -@end deftypefun - -@cindex read eval print loop -- from the gh_ interface -@cindex REPL -- from the gh_ interface -A convenience routine which enters the Guile interpreter with the -standard Guile read-eval-print loop (@dfn{REPL}) is: - -@deftypefun void gh_repl (int @var{argc}, char *@var{argv}[]) -Enters the Scheme interpreter giving control to the Scheme REPL. -Arguments are processed as if the Guile program @file{guile} were being -invoked. - -Note that @code{gh_repl} should be used @emph{inside} @code{gh_enter}, -since any Guile interpreter calls are meaningless unless they happen in -the context of the interpreter. - -Also note that when you use @code{gh_repl}, your program will be -controlled by Guile's REPL (which is written in Scheme and has many -useful features). Use straight C code inside @code{gh_enter} if you -want to maintain execution control in your C program. -@end deftypefun - -You will typically use @code{gh_enter} and @code{gh_repl} when you -want a Guile interpreter enhanced by your own libraries, but otherwise -quite normal. For example, to build a Guile--derived program that -includes some random number routines @dfn{GSL} (GNU Scientific Library), -you would write a C program that looks like this: - -@smallexample -#include <guile/gh.h> -#include <gsl_ran.h> - -/* random number suite */ -SCM gw_ran_seed(SCM s) -@{ - gsl_ran_seed(gh_scm2int(s)); - return SCM_UNSPECIFIED; -@} - -SCM gw_ran_random() -@{ - SCM x; - - x = gh_ulong2scm(gsl_ran_random()); - return x; -@} - -SCM gw_ran_uniform() -@{ - SCM x; - - x = gh_double2scm(gsl_ran_uniform()); - return x; -@} -SCM gw_ran_max() -@{ - return gh_double2scm(gsl_ran_max()); -@} - -void -init_gsl() -@{ - /* random number suite */ - gh_new_procedure("gsl-ran-seed", gw_ran_seed, 1, 0, 0); - gh_new_procedure("gsl-ran-random", gw_ran_random, 0, 0, 0); - gh_new_procedure("gsl-ran-uniform", gw_ran_uniform, 0, 0, 0); - gh_new_procedure("gsl-ran-max", gw_ran_max, 0, 0, 0); -@} - -void -main_prog (int argc, char *argv[]) -@{ - init_gsl(); - - gh_repl(argc, argv); -@} - -int -main (int argc, char *argv[]) -@{ - gh_enter (argc, argv, main_prog); -@} -@end smallexample - -Then, supposing the C program is in @file{guile-gsl.c}, you could -compile it with @kbd{gcc -o guile-gsl guile-gsl.c -lguile -lgsl}. - -The resulting program @file{guile-gsl} would have new primitive -procedures @code{gsl-ran-random}, @code{gsl-ran-gaussian} and so forth. - - -@node Error messages -@section Error messages -@cindex libguile - error messages -@cindex error messages in libguile - -[FIXME: need to fill this based on Jim's new mechanism] - - -@node Executing Scheme code -@section Executing Scheme code -@cindex libguile - executing Scheme -@cindex executing Scheme - -Once you have an interpreter running, you can ask it to evaluate Scheme -code. There are two calls that implement this: - -@deftypefun SCM gh_eval_str (char *@var{scheme_code}) -This asks the interpreter to evaluate a single string of Scheme code, -and returns the result of the last expression evaluated. - -Note that the line of code in @var{scheme_code} must be a well formed -Scheme expression. If you have many lines of code before you balance -parentheses, you must either concatenate them into one string, or use -@code{gh_eval_file()}. -@end deftypefun - -@deftypefun SCM gh_eval_file (char *@var{fname}) -@deftypefunx SCM gh_load (char *@var{fname}) -@code{gh_eval_file} is completely analogous to @code{gh_eval_str()}, -except that a whole file is evaluated instead of a string. -@code{gh_eval_file} returns @code{SCM_UNSPECIFIED}. - -@code{gh_load} is identical to @code{gh_eval_file} (it's a macro that -calls @code{gh_eval_file} on its argument). It is provided to start -making the @code{gh_} interface match the R5RS Scheme procedures -closely. -@end deftypefun - - -@node Defining new Scheme procedures in C -@section Defining new Scheme procedures in C -@cindex libguile - new procedures -@cindex new procedures -@cindex procedures, new -@cindex new primitives -@cindex primitives, new - -The real interface between C and Scheme comes when you can write new -Scheme procedures in C. This is done through the routine - - -@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}) -@code{gh_new_procedure} defines a new Scheme procedure. Its Scheme name -will be @var{proc_name}, it will be implemented by the C function -(*@var{fn})(), it will take at least @var{n_required_args} arguments, -and at most @var{n_optional_args} extra arguments. - -When the @var{restp} parameter is 1, the procedure takes a final -argument: a list of remaining parameters. - -@code{gh_new_procedure} returns an SCM value representing the procedure. - -The C function @var{fn} should have the form -@deftypefn {Libguile high} SCM fn (SCM @var{req1}, SCM @var{req2}, ..., SCM @var{opt1}, SCM @var{opt2}, ..., SCM @var{rest_args}) -The arguments are all passed as SCM values, so the user will have to use -the conversion functions to convert to standard C types. - -Examples of C functions used as new Scheme primitives can be found in -the sample programs @code{learn0} and @code{learn1}. -@end deftypefn - -@end deftypefn - -@strong{Rationale:} this is the correct way to define new Scheme -procedures in C. The ugly mess of arguments is required because of how -C handles procedures with variable numbers of arguments. - -@strong{Note:} what about documentation strings? - -@cartouche -There are several important considerations to be made when writing the C -routine @code{(*fn)()}. - -First of all the C routine has to return type @code{SCM}. - -Second, all arguments passed to the C function will be of type -@code{SCM}. - -Third: the C routine is now subject to Scheme flow control, which means -that it could be interrupted at any point, and then reentered. This -means that you have to be very careful with operations such as -allocating memory, modifying static data @dots{} - -Fourth: to get around the latter issue, you can use -@code{GH_DEFER_INTS} and @code{GH_ALLOW_INTS}. -@end cartouche - -@defmac GH_DEFER_INTS -@defmacx GH_ALLOW_INTS -These macros disable and re-enable Scheme's flow control. They -@end defmac - - -@c [??? have to do this right; maybe using subsections, or maybe creating a -@c section called Flow control issues...] - -@c [??? Go into exhaustive detail with examples of the various possible -@c combinations of required and optional args...] - - -@node Converting data between C and Scheme -@section Converting data between C and Scheme -@cindex libguile - converting data -@cindex data conversion -@cindex converting data - -Guile provides mechanisms to convert data between C and Scheme. This -allows new builtin procedures to understand their arguments (which are -of type @code{SCM}) and return values of type @code{SCM}. - - -@menu -* C to Scheme:: -* Scheme to C:: -@end menu - -@node C to Scheme -@subsection C to Scheme - -@deftypefun SCM gh_bool2scm (int @var{x}) -Returns @code{#f} if @var{x} is zero, @code{#t} otherwise. -@end deftypefun - -@deftypefun SCM gh_ulong2scm (unsigned long @var{x}) -@deftypefunx SCM gh_long2scm (long @var{x}) -@deftypefunx SCM gh_double2scm (double @var{x}) -@deftypefunx SCM gh_char2scm (char @var{x}) -Returns a Scheme object with the value of the C quantity @var{x}. -@end deftypefun - -@deftypefun SCM gh_str2scm (char *@var{s}, int @var{len}) -Returns a new Scheme string with the (not necessarily null-terminated) C -array @var{s} data. -@end deftypefun - -@deftypefun SCM gh_str02scm (char *@var{s}) -Returns a new Scheme string with the null-terminated C string @var{s} -data. -@end deftypefun - -@deftypefun SCM gh_set_substr (char *@var{src}, SCM @var{dst}, int @var{start}, int @var{len}) -Copy @var{len} characters at @var{src} into the @emph{existing} Scheme -string @var{dst}, starting at @var{start}. @var{start} is an index into -@var{dst}; zero means the beginning of the string. - -If @var{start} + @var{len} is off the end of @var{dst}, signal an -out-of-range error. -@end deftypefun - -@deftypefun SCM gh_symbol2scm (char *@var{name}) -Given a null-terminated string @var{name}, return the symbol with that -name. -@end deftypefun - -@deftypefun SCM gh_ints2scm (int *@var{dptr}, int @var{n}) -@deftypefunx SCM gh_doubles2scm (double *@var{dptr}, int @var{n}) -Make a scheme vector containing the @var{n} ints or doubles at memory -location @var{dptr}. -@end deftypefun - -@deftypefun SCM gh_chars2byvect (char *@var{dptr}, int @var{n}) -@deftypefunx SCM gh_shorts2svect (short *@var{dptr}, int @var{n}) -@deftypefunx SCM gh_longs2ivect (long *@var{dptr}, int @var{n}) -@deftypefunx SCM gh_ulongs2uvect (ulong *@var{dptr}, int @var{n}) -@deftypefunx SCM gh_floats2fvect (float *@var{dptr}, int @var{n}) -@deftypefunx SCM gh_doubles2dvect (double *@var{dptr}, int @var{n}) -Make a scheme uniform vector containing the @var{n} chars, shorts, -longs, unsigned longs, floats or doubles at memory location @var{dptr}. -@end deftypefun - - - -@node Scheme to C -@subsection Scheme to C - -@deftypefun int gh_scm2bool (SCM @var{obj}) -@deftypefunx {unsigned long} gh_scm2ulong (SCM @var{obj}) -@deftypefunx long gh_scm2long (SCM @var{obj}) -@deftypefunx double gh_scm2double (SCM @var{obj}) -@deftypefunx int gh_scm2char (SCM @var{obj}) -These routines convert the Scheme object to the given C type. -@end deftypefun - -@deftypefun char *gh_scm2newstr (SCM @var{str}, int *@var{lenp}) -Given a Scheme string @var{str}, return a pointer to a new copy of its -contents, followed by a null byte. If @var{lenp} is non-null, set -@code{*@var{lenp}} to the string's length. - -This function uses malloc to obtain storage for the copy; the caller is -responsible for freeing it. - -Note that Scheme strings may contain arbitrary data, including null -characters. This means that null termination is not a reliable way to -determine the length of the returned value. However, the function -always copies the complete contents of @var{str}, and sets @var{*lenp} -to the true length of the string (when @var{lenp} is non-null). -@end deftypefun - - -@deftypefun void gh_get_substr (SCM str, char *return_str, int *lenp) -Copy @var{len} characters at @var{start} from the Scheme string -@var{src} to memory at @var{dst}. @var{start} is an index into -@var{src}; zero means the beginning of the string. @var{dst} has -already been allocated by the caller. - -If @var{start} + @var{len} is off the end of @var{src}, signal an -out-of-range error. -@end deftypefun - -@deftypefun char *gh_symbol2newstr (SCM @var{sym}, int *@var{lenp}) -Takes a Scheme symbol and returns a string of the form -@code{"'symbol-name"}. If @var{lenp} is non-null, the string's length -is returned in @code{*@var{lenp}}. - -This function uses malloc to obtain storage for the returned string; the -caller is responsible for freeing it. -@end deftypefun - -@deftypefun char *gh_scm2chars (SCM @var{vector}, chars *@var{result}) -@deftypefunx short *gh_scm2shorts (SCM @var{vector}, short *@var{result}) -@deftypefunx long *gh_scm2longs (SCM @var{vector}, long *@var{result}) -@deftypefunx float *gh_scm2floats (SCM @var{vector}, float *@var{result}) -@deftypefunx double *gh_scm2doubles (SCM @var{vector}, double *@var{result}) -Copy the numbers in @var{vector} to the array pointed to by @var{result} -and return it. If @var{result} is NULL, allocate a double array large -enough. - -@var{vector} can be an ordinary vector, a weak vector, or a signed or -unsigned uniform vector of the same type as the result array. For -chars, @var{vector} can be a string or substring. For floats and -doubles, @var{vector} can contain a mix of inexact and integer values. - -If @var{vector} is of unsigned type and contains values too large to fit -in the signed destination array, those values will be wrapped around, -that is, data will be copied as if the destination array was unsigned. -@end deftypefun - - -@node Type predicates -@section Type predicates - -These C functions mirror Scheme's type predicate procedures with one -important difference. The C routines return C boolean values (0 and 1) -instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}. - -The Scheme notational convention of putting a @code{?} at the end of -predicate procedure names is mirrored in C by placing @code{_p} at the -end of the procedure. For example, @code{(pair? ...)} maps to -@code{gh_pair_p(...)}. - -@deftypefun int gh_boolean_p (SCM @var{val}) -Returns 1 if @var{val} is a boolean, 0 otherwise. -@end deftypefun - -@deftypefun int gh_symbol_p (SCM @var{val}) -Returns 1 if @var{val} is a symbol, 0 otherwise. -@end deftypefun - -@deftypefun int gh_char_p (SCM @var{val}) -Returns 1 if @var{val} is a char, 0 otherwise. -@end deftypefun - -@deftypefun int gh_vector_p (SCM @var{val}) -Returns 1 if @var{val} is a vector, 0 otherwise. -@end deftypefun - -@deftypefun int gh_pair_p (SCM @var{val}) -Returns 1 if @var{val} is a pair, 0 otherwise. -@end deftypefun - -@deftypefun int gh_procedure_p (SCM @var{val}) -Returns 1 if @var{val} is a procedure, 0 otherwise. -@end deftypefun - -@deftypefun int gh_list_p (SCM @var{val}) -Returns 1 if @var{val} is a list, 0 otherwise. -@end deftypefun - -@deftypefun int gh_inexact_p (SCM @var{val}) -Returns 1 if @var{val} is an inexact number, 0 otherwise. -@end deftypefun - -@deftypefun int gh_exact_p (SCM @var{val}) -Returns 1 if @var{val} is an exact number, 0 otherwise. -@end deftypefun - - -@node Equality predicates -@section Equality predicates - -These C functions mirror Scheme's equality predicate procedures with one -important difference. The C routines return C boolean values (0 and 1) -instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}. - -The Scheme notational convention of putting a @code{?} at the end of -predicate procedure names is mirrored in C by placing @code{_p} at the -end of the procedure. For example, @code{(equal? ...)} maps to -@code{gh_equal_p(...)}. - -@deftypefun int gh_eq_p (SCM x, SCM y) -Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's -@code{eq?} predicate, 0 otherwise. -@end deftypefun - -@deftypefun int gh_eqv_p (SCM x, SCM y) -Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's -@code{eqv?} predicate, 0 otherwise. -@end deftypefun - -@deftypefun int gh_equal_p (SCM x, SCM y) -Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's -@code{equal?} predicate, 0 otherwise. -@end deftypefun - -@deftypefun int gh_string_equal_p (SCM @var{s1}, SCM @var{s2}) -Returns 1 if the strings @var{s1} and @var{s2} are equal, 0 otherwise. -@end deftypefun - -@deftypefun int gh_null_p (SCM @var{l}) -Returns 1 if @var{l} is an empty list or pair; 0 otherwise. -@end deftypefun - - -@node Memory allocation and garbage collection -@section Memory allocation and garbage collection - -@c [FIXME: flesh this out with some description of garbage collection in -@c scm/guile] - -@c @deftypefun SCM gh_mkarray (int size) -@c Allocate memory for a Scheme object in a garbage-collector-friendly -@c manner. -@c @end deftypefun - - -@node Calling Scheme procedures from C -@section Calling Scheme procedures from C - -Many of the Scheme primitives are available in the @code{gh_} -interface; they take and return objects of type SCM, and one could -basically use them to write C code that mimics Scheme code. - -I will list these routines here without much explanation, since what -they do is the same as documented in @ref{Standard procedures, R5RS, , -r5rs, R5RS}. But I will point out that when a procedure takes a -variable number of arguments (such as @code{gh_list}), you should pass -the constant @var{SCM_UNDEFINED} from C to signify the end of the list. - -@deftypefun SCM gh_define (char *@var{name}, SCM @var{val}) -Corresponds to the Scheme @code{(define name val)}: it binds a value to -the given name (which is a C string). Returns the new object. -@end deftypefun - -@heading Pairs and lists - -@deftypefun SCM gh_cons (SCM @var{a}, SCM @var{b}) -@deftypefunx SCM gh_list (SCM l0, SCM l1, ... , SCM_UNDEFINED) -These correspond to the Scheme @code{(cons a b)} and @code{(list l0 l1 -...)} procedures. Note that @code{gh_list()} is a C macro that invokes -@code{scm_listify()}. -@end deftypefun - -@deftypefun SCM gh_car (SCM @var{obj}) -@deftypefunx SCM gh_cdr (SCM @var{obj}) -@dots{} - -@deftypefunx SCM gh_c[ad][ad][ad][ad]r (SCM @var{obj}) -These correspond to the Scheme @code{(caadar ls)} procedures etc @dots{} -@end deftypefun - -@deftypefun SCM gh_set_car_x(SCM @var{pair}, SCM @var{value}) -Modifies the CAR of @var{pair} to be @var{value}. This is equivalent to -the Scheme procedure @code{(set-car! ...)}. -@end deftypefun - -@deftypefun SCM gh_set_cdr_x(SCM @var{pair}, SCM @var{value}) -Modifies the CDR of @var{pair} to be @var{value}. This is equivalent to -the Scheme procedure @code{(set-cdr! ...)}. -@end deftypefun - -@deftypefun {unsigned long} gh_length (SCM @var{ls}) -Returns the length of the list. -@end deftypefun - -@deftypefun SCM gh_append (SCM @var{args}) -@deftypefunx SCM gh_append2 (SCM @var{l1}, SCM @var{l2}) -@deftypefunx SCM gh_append3 (SCM @var{l1}, SCM @var{l2}, @var{l3}) -@deftypefunx SCM gh_append4 (SCM @var{l1}, SCM @var{l2}, @var{l3}, @var{l4}) -@code{gh_append()} takes @var{args}, which is a list of lists -@code{(list1 list2 ...)}, and returns a list containing all the elements -of the individual lists. - -A typical invocation of @code{gh_append()} to append 5 lists together -would be -@smallexample - gh_append(gh_list(l1, l2, l3, l4, l5, SCM_UNDEFINED)); -@end smallexample - -The functions @code{gh_append2()}, @code{gh_append2()}, -@code{gh_append3()} and @code{gh_append4()} are convenience routines to -make it easier for C programs to form the list of lists that goes as an -argument to @code{gh_append()}. -@end deftypefun - -@deftypefun SCM gh_reverse (SCM @var{ls}) -Returns a new list that has the same elements as @var{ls} but in the -reverse order. Note that this is implemented as a macro which calls -@code{scm_reverse()}. -@end deftypefun - -@deftypefun SCM gh_list_tail (SCM @var{ls}, SCM @var{k}) -Returns the sublist of @var{ls} with the last @var{k} elements. -@end deftypefun - -@deftypefun SCM gh_list_ref (SCM @var{ls}, SCM @var{k}) -Returns the @var{k}th element of the list @var{ls}. -@end deftypefun - -@deftypefun SCM gh_memq (SCM @var{x}, SCM @var{ls}) -@deftypefunx SCM gh_memv (SCM @var{x}, SCM @var{ls}) -@deftypefunx SCM gh_member (SCM @var{x}, SCM @var{ls}) -These functions return the first sublist of @var{ls} whose CAR is -@var{x}. They correspond to @code{(memq x ls)}, @code{(memv x ls)} and -@code{(member x ls)}, and hence use (respectively) @code{eq?}, -@code{eqv?} and @code{equal?} to do comparisons. - -If @var{x} does not appear in @var{ls}, the value @code{SCM_BOOL_F} (not -the empty list) is returned. - -Note that these functions are implemented as macros which call -@code{scm_memq()}, @code{scm_memv()} and @code{scm_member()} -respectively. -@end deftypefun - -@deftypefun SCM gh_assq (SCM @var{x}, SCM @var{alist}) -@deftypefunx SCM gh_assv (SCM @var{x}, SCM @var{alist}) -@deftypefunx SCM gh_assoc (SCM @var{x}, SCM @var{alist}) -These functions search an @dfn{association list} (list of pairs) -@var{alist} for the first pair whose CAR is @var{x}, and they return -that pair. - -If no pair in @var{alist} has @var{x} as its CAR, the value -@code{SCM_BOOL_F} (not the empty list) is returned. - -Note that these functions are implemented as macros which call -@code{scm_assq()}, @code{scm_assv()} and @code{scm_assoc()} -respectively. -@end deftypefun - - -@heading Symbols - -@c @deftypefun SCM gh_symbol (SCM str, SCM len) -@c @deftypefunx SCM gh_tmp_symbol (SCM str, SCM len) -@c Takes the given string @var{str} of length @var{len} and returns a -@c symbol corresponding to that string. -@c @end deftypefun - - -@heading Vectors - -@deftypefun SCM gh_make_vector (SCM @var{n}, SCM @var{fill}) -@deftypefunx SCM gh_vector (SCM @var{ls}) -@deftypefunx SCM gh_vector_ref (SCM @var{v}, SCM @var{i}) -@deftypefunx SCM gh_vector_set (SCM @var{v}, SCM @var{i}, SCM @var{val}) -@deftypefunx {unsigned long} gh_vector_length (SCM @var{v}) -@deftypefunx SCM gh_list_to_vector (SCM @var{ls}) -These correspond to the Scheme @code{(make-vector n fill)}, -@code{(vector a b c ...)} @code{(vector-ref v i)} @code{(vector-set v i -value)} @code{(vector-length v)} @code{(list->vector ls)} procedures. - -The correspondence is not perfect for @code{gh_vector}: this routine -takes a list @var{ls} instead of the individual list elements, thus -making it identical to @code{gh_list_to_vector}. - -There is also a difference in gh_vector_length: the value returned is a -C @code{unsigned long} instead of an SCM object. -@end deftypefun - - -@heading Procedures - -@c @deftypefun SCM gh_make_subr (SCM (*@var{fn})(), int @var{req}, int @var{opt}, int @var{restp}, char *@var{sym}) -@c Make the C function @var{fn} available to Scheme programs. The function -@c will be bound to the symbol @var{sym}. The arguments @var{req}, -@c @var{opt} and @var{restp} describe @var{fn}'s calling conventions. The -@c function must take @var{req} required arguments and may take @var{opt} -@c optional arguments. Any optional arguments which are not supplied by -@c the caller will be bound to @var{SCM_UNSPECIFIED}. If @var{restp} is -@c non-zero, it means that @var{fn} may be called with an arbitrary number -@c of arguments, and that any extra arguments supplied by the caller will -@c be passed to @var{fn} as a list. The @var{restp} argument is exactly -@c like Scheme's @code{(lambda (arg1 arg2 . arglist))} calling convention. -@c -@c For example, the procedure @code{read-line}, which takes optional -@c @var{port} and @var{handle-delim} arguments, would be declared like so: -@c -@c @example -@c SCM scm_read_line (SCM port, SCM handle_delim); -@c gh_make_subr (scm_read_line, 0, 2, 0, "read-line"); -@c @end example -@c -@c The @var{req} argument to @code{gh_make_subr} is 0 to indicate that -@c there are no required arguments, so @code{read-line} may be called -@c without any arguments at all. The @var{opt} argument is 2, to indicate -@c that both the @var{port} and @var{handle_delim} arguments to -@c @code{scm_read_line} are optional, and will be bound to -@c @code{SCM_UNSPECIFIED} if the calling program does not supply them. -@c Because the @var{restp} argument is 0, this function may not be called -@c with more than two arguments. -@c @end deftypefun - -@deftypefun SCM gh_apply (SCM proc, SCM args) -Call the Scheme procedure @var{proc}, with the elements of @var{args} as -arguments. @var{args} must be a proper list. -@end deftypefun - -@deftypefun SCM gh_call0 (SCM proc) -@deftypefunx SCM gh_call1 (SCM proc, SCM arg) -@deftypefunx SCM gh_call2 (SCM proc, SCM arg1, SCM arg2) -@deftypefunx SCM gh_call3 (SCM proc, SCM arg1, SCM arg2, SCM arg3) -Call the Scheme procedure @var{proc} with no arguments -(@code{gh_call0}), one argument (@code{gh_call1}), and so on. You can -get the same effect by wrapping the arguments up into a list, and -calling @code{gh_apply}; Guile provides these functions for convenience. -@end deftypefun - - -@deftypefun SCM gh_catch (SCM key, SCM thunk, SCM handler) -@deftypefunx SCM gh_throw (SCM key, SCM args) -Corresponds to the Scheme @code{catch} and @code{throw} procedures, -which in Guile are provided as primitives. -@end deftypefun - -@c [FIXME: must add the I/O section in gscm.h] - -@deftypefun SCM gh_is_eq (SCM a, SCM b) -@deftypefunx SCM gh_is_eqv (SCM a, SCM b) -@deftypefunx SCM gh_is_equal (SCM a, SCM b) -These correspond to the Scheme @code{eq?}, @code{eqv?} and @code{equal?} -predicates. -@end deftypefun - -@deftypefun int gh_obj_length (SCM @var{obj}) -Returns the raw object length. -@end deftypefun - -@heading Data lookup - -For now I just include Tim Pierce's comments from the @file{gh_data.c} -file; it should be organized into a documentation of the two functions -here. - -@smallexample -/* Data lookups between C and Scheme - - Look up a symbol with a given name, and return the object to which - it is bound. gh_lookup examines the Guile top level, and - gh_module_lookup checks the module name space specified by the - `vec' argument. - - The return value is the Scheme object to which SNAME is bound, or - SCM_UNDEFINED if SNAME is not bound in the given context. [FIXME: - should this be SCM_UNSPECIFIED? Can a symbol ever legitimately be - bound to SCM_UNDEFINED or SCM_UNSPECIFIED? What is the difference? - -twp] */ -@end smallexample - - -@node Mixing gh and scm APIs -@section Mixing gh and scm APIs - - -@node scm transition summary -@section Transitioning to the scm Interface - -The following table summarizes the available information on how to -transition from the GH to the scm interface. Where transitioning is not -completely straightforward, the table includes a reference to more -detailed documentation in the preceding sections. - -@table @asis -@item Header file -Use @code{#include <libguile.h>} instead of @code{#include -<guile/gh.h>}. - -@item Compiling and Linking -Use @code{guile-config} to pick up the flags required to compile C or -C++ code that uses @code{libguile}, like so - -@smallexample -$(CC) -o prog.o -c prog.c `guile-config compile` -@end smallexample - -If you are using libtool to link your executables, just use -@code{-lguile} in your link command. Libtool will expand this into -the needed linker options automatically. If you are not using -libtool, use the @code{guile-config} program to query the needed -options explicitly. A linker command like - -@smallexample -$(CC) -o prog prog.o `guile-config link` -@end smallexample - -should be all that is needed. To link shared libraries that will be -used as Guile Extensions, use libtool to control both the compilation -and the link stage. - -@item The @code{SCM} type -No change: the scm interface also uses this type to represent an -arbitrary Scheme value. - -@item @code{SCM_BOOL_F} and @code{SCM_BOOL_T} -No change. - -@item @code{SCM_UNSPECIFIED} and @code{SCM_UNDEFINED} -No change. - -@item @code{gh_enter} -Use @code{scm_boot_guile} instead, but note that @code{scm_boot_guile} -has a slightly different calling convention from @code{gh_enter}: -@code{scm_boot_guile}, and the main program function that you specify -for @code{scm_boot_guile} to call, both take an additional @var{closure} -parameter. @ref{Guile Initialization Functions} for more details. - -@item @code{gh_repl} -Use @code{scm_shell} instead. - -@item @code{gh_init} -Use @code{scm_init_guile} instead. - -@item @code{gh_eval_str} -Use @code{scm_c_eval_string} instead. - -@item @code{gh_eval_file} or @code{gh_load} -Use @code{scm_c_primitive_load} instead. - -@item @code{gh_new_procedure} -Use @code{scm_c_define_gsubr} instead, but note that the arguments are -in a different order: for @code{scm_c_define_gsubr} the C function -pointer is the last argument. @ref{A Sample Guile Extension} for an -example. - -@item @code{gh_defer_ints} and @code{gh_allow_ints} -Use @code{SCM_DEFER_INTS} and @code{SCM_ALLOW_INTS} instead. Note that -these macros are used without parentheses, as in @code{SCM_DEFER_INTS;}. - -@item @code{gh_bool2scm} -Use @code{SCM_BOOL} instead. - -@item @code{gh_ulong2scm} -Use @code{scm_ulong2num} instead. - -@item @code{gh_long2scm} -Use @code{scm_long2num} instead. - -@item @code{gh_double2scm} -Use @code{scm_make_real} instead. - -@item @code{gh_char2scm} -Use @code{SCM_MAKE_CHAR} instead. - -@item @code{gh_str2scm} -Use @code{scm_mem2string} instead. - -@item @code{gh_str02scm} -Use @code{scm_makfrom0str} instead. - -@item @code{gh_set_substr} -No direct scm equivalent. [FIXME] - -@item @code{gh_symbol2scm} -Use @code{scm_str2symbol} instead. [FIXME: inconsistent naming, -should be @code{scm_str02symbol}.] - -@item @code{gh_ints2scm} and @code{gh_doubles2scm} -Use @code{scm_c_ints2scm} and @code{scm_c_doubles2scm} instead. - -@item @code{gh_chars2byvect} and @code{gh_shorts2svect} -Use @code{scm_c_chars2byvect} and @code{scm_c_shorts2svect} instead. - -@item @code{gh_longs2ivect} and @code{gh_ulongs2uvect} -Use @code{scm_c_longs2ivect} and @code{scm_c_ulongs2uvect} instead. - -@item @code{gh_floats2fvect} and @code{gh_doubles2dvect} -Use @code{scm_c_floats2fvect} and @code{scm_c_doubles2dvect} instead. - -@item @code{gh_scm2bool} -Use @code{SCM_NFALSEP} instead. - -@item @code{gh_scm2int} -Replace @code{gh_scm2int (@var{obj})} by -@example -scm_num2int (@var{obj}, SCM_ARG1, @var{str}) -@end example -where @var{str} is a C string that describes the context of the call. - -@item @code{gh_scm2ulong} -Replace @code{gh_scm2ulong (@var{obj})} by -@example -scm_num2ulong (@var{obj}, SCM_ARG1, @var{str}) -@end example -where @var{str} is a C string that describes the context of the call. - -@item @code{gh_scm2long} -Replace @code{gh_scm2long (@var{obj})} by -@example -scm_num2long (@var{obj}, SCM_ARG1, @var{str}) -@end example -where @var{str} is a C string that describes the context of the call. - -@item @code{gh_scm2double} -Replace @code{gh_scm2double (@var{obj})} by -@example -scm_num2dbl (@var{obj}, @var{str}) -@end example -where @var{str} is a C string that describes the context of the call. - -@item @code{gh_scm2char} -Use the @code{SCM_CHAR} macro instead, but note that @code{SCM_CHAR} -does not check that its argument is actually a character. To check that -a @code{SCM} value is a character before using @code{SCM_CHAR} to -extract the character value, use the @code{SCM_VALIDATE_CHAR} macro. - -@item @code{gh_scm2newstr} -Instead of @code{gh_scm2newstr (@var{obj}, @var{lenp})} use -@code{scm_c_string2str (@var{obj}, @var{str}, @var{lenp})}. With the -additional @var{str} argument the user can pass a pre-allocated memory -chunk or leave it passing NULL. - -@item @code{gh_get_substr} -Use the @code{scm_c_substring2str (@var{obj}, @var{str}, @var{start}, -@var{len})} function instead. - -@item @code{gh_symbol2newstr} -Use the @code{scm_c_symbol2str (@var{obj}, @var{str}, @var{lenp})} function -instead. With the additional @var{str} argument the user can pass a -pre-allocated memory chunk or leave it passing NULL. - -@item @code{gh_scm2chars} -Use @code{scm_c_scm2chars} instead. - -@item @code{gh_scm2shorts} and @code{gh_scm2longs} -Use @code{scm_c_shorts2scm} and @code{scm_c_longs2scm} instead. - -@item @code{gh_scm2floats} and @code{gh_scm2doubles} -Use @code{scm_c_floats2scm} and @code{scm_c_doubles2scm} instead. - -@item @code{gh_boolean_p} -Use the @code{SCM_BOOLP} macro instead, or replace @code{gh_boolean_p -(@var{obj})} by -@example -SCM_NFALSEP (scm_boolean_p (@var{obj})) -@end example - -@item @code{gh_symbol_p} -Use the @code{SCM_SYMBOLP} macro instead, or replace @code{gh_symbol_p -(@var{obj})} by -@example -SCM_NFALSEP (scm_symbol_p (@var{obj})) -@end example - -@item @code{gh_char_p} -Use the @code{SCM_CHARP} macro instead, or replace @code{gh_char_p -(@var{obj})} by -@example -SCM_NFALSEP (scm_char_p (@var{obj})) -@end example - -@item @code{gh_vector_p} -Use the @code{SCM_VECTORP} macro instead, or replace @code{gh_vector_p -(@var{obj})} by -@example -SCM_NFALSEP (scm_vector_p (@var{obj})) -@end example - -@item @code{gh_pair_p} -Use the @code{SCM_CONSP} macro instead, or replace @code{gh_pair_p -(@var{obj})} by -@example -SCM_NFALSEP (scm_pair_p (@var{obj})) -@end example - -@item @code{gh_number_p} -Use the @code{SCM_NUMBERP} macro instead, or replace @code{gh_number_p -(@var{obj})} by -@example -SCM_NFALSEP (scm_number_p (@var{obj})) -@end example - -@item @code{gh_string_p} -Use the @code{SCM_STRINGP} macro instead, or replace @code{gh_string_p -(@var{obj})} by -@example -SCM_NFALSEP (scm_string_p (@var{obj})) -@end example - -@item @code{gh_procedure_p} -Replace @code{gh_procedure_p (@var{obj})} by -@example -SCM_NFALSEP (scm_procedure_p (@var{obj})) -@end example - -@item @code{gh_list_p} -Replace @code{gh_list_p (@var{obj})} by -@example -SCM_NFALSEP (scm_list_p (@var{obj})) -@end example - -@item @code{gh_inexact_p} -Use the @code{SCM_INEXACTP} macro instead, or replace @code{gh_inexact_p -(@var{obj})} by -@example -SCM_NFALSEP (scm_inexact_p (@var{obj})) -@end example - -@item @code{gh_exact_p} -Replace @code{gh_exact_p (@var{obj})} by -@example -SCM_NFALSEP (scm_exact_p (@var{obj})) -@end example - -@item @code{gh_eq_p} -Use the @code{SCM_EQ_P} macro instead, or replace @code{gh_eq_p -(@var{x}, @var{y})} by -@example -SCM_NFALSEP (scm_eq_p (@var{x}, @var{y})) -@end example - -@item @code{gh_eqv_p} -Replace @code{gh_eqv_p (@var{x}, @var{y})} by -@example -SCM_NFALSEP (scm_eqv_p (@var{x}, @var{y})) -@end example - -@item @code{gh_equal_p} -Replace @code{gh_equal_p (@var{x}, @var{y})} by -@example -SCM_NFALSEP (scm_equal_p (@var{x}, @var{y})) -@end example - -@item @code{gh_string_equal_p} -Replace @code{gh_string_equal_p (@var{x}, @var{y})} by -@example -SCM_NFALSEP (scm_string_equal_p (@var{x}, @var{y})) -@end example - -@item @code{gh_null_p} -Use the @code{SCM_NULLP} macro instead, or replace @code{gh_null_p -(@var{obj})} by -@example -SCM_NFALSEP (scm_null_p (@var{obj})) -@end example - -@item @code{gh_cons} -Use @code{scm_cons} instead. - -@item @code{gh_car} and @code{gh_cdr} -Use the @code{SCM_CAR} and @code{SCM_CDR} macros instead. - -@item @code{gh_cxxr} and @code{gh_cxxxr} -(Where each x is either @samp{a} or @samp{d}.) Use the corresponding -@code{SCM_CXXR} or @code{SCM_CXXXR} macro instead. - -@item @code{gh_set_car_x} and @code{gh_set_cdr_x} -Use @code{scm_set_car_x} and @code{scm_set_cdr_x} instead. - -@item @code{gh_list} -Use @code{scm_listify} instead. - -@item @code{gh_length} -Replace @code{gh_length (@var{lst})} by -@example -scm_num2ulong (scm_length (@var{lst}), SCM_ARG1, @var{str}) -@end example -where @var{str} is a C string that describes the context of the call. - -@item @code{gh_append} -Use @code{scm_append} instead. - -@item @code{gh_append2}, @code{gh_append3}, @code{gh_append4} -Replace @code{gh_append@var{N} (@var{l1}, @dots{}, @var{lN})} by -@example -scm_append (scm_listify (@var{l1}, @dots{}, @var{lN}, SCM_UNDEFINED)) -@end example - -@item @code{gh_reverse} -Use @code{scm_reverse} instead. - -@item @code{gh_list_tail} and @code{gh_list_ref} -Use @code{scm_list_tail} and @code{scm_list_ref} instead. - -@item @code{gh_memq}, @code{gh_memv} and @code{gh_member} -Use @code{scm_memq}, @code{scm_memv} and @code{scm_member} instead. - -@item @code{gh_assq}, @code{gh_assv} and @code{gh_assoc} -Use @code{scm_assq}, @code{scm_assv} and @code{scm_assoc} instead. - -@item @code{gh_make_vector} -Use @code{scm_make_vector} instead. - -@item @code{gh_vector} or @code{gh_list_to_vector} -Use @code{scm_vector} instead. - -@item @code{gh_vector_ref} and @code{gh_vector_set_x} -Use @code{scm_vector_ref} and @code{scm_vector_set_x} instead. - -@item @code{gh_vector_length} -Use the @code{SCM_VECTOR_LENGTH} macro instead. - -@item @code{gh_apply} -Use @code{scm_apply} instead, but note that @code{scm_apply} takes an -additional third argument that you should set to @code{SCM_EOL}. - -@end table |