code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@page
@node GH
@section 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 also documents how to achieve
the same result using the scm interface.

@menu
* GH deprecation::              Why the GH interface is now deprecated.
* Transitioning away from GH::
* 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::
@end menu

@node GH deprecation
@subsection 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 Transitioning away from GH
@subsection Transitioning away from GH

The following table summarizes how to transition from the GH to the
scm interface.  The replacements that are recommended are not always
completely equivalent to the GH functionality that they should
replace.  Therefore, you should read the reference documentation of
the replacements carefully if you are not yet familiar with them.

@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_catch}
Use @code{scm_internal_catch} instead.

@item @code{gh_eval_str}
Use @code{scm_c_eval_string} instead.

@item @code{gh_eval_str_with_catch}
Use @code{scm_c_eval_string} together with @code{scm_internal_catch}
instead.

@item @code{gh_eval_str_with_standard_handler}
Use @code{scm_c_eval_string} together with @code{scm_internal_catch}
and @code{scm_handle_by_message_no_exit} instead.

@item @code{gh_eval_str_with_stack_saving_handler}
Use @code{scm_c_eval_string} together with
@code{scm_internal_stack_catch} and
@code{scm_handle_by_message_no_exit} instead.

@item @code{gh_eval_file} or @code{gh_load}
Use @code{scm_c_primitive_load} instead.

@item @code{gh_eval_file_with_catch}
Use @code{scm_c_primitive_load} together with
@code{scm_internal_catch} instead.

@item @code{gh_eval_file_with_standard_handler}
Use @code{scm_c_primitive_load} together with
@code{scm_internal_catch} and @code{scm_handle_by_message_no_exit}
instead.

@item  @code{gh_new_procedure}
@itemx @code{gh_new_procedure0_0}
@itemx @code{gh_new_procedure0_1}
@itemx @code{gh_new_procedure0_2}
@itemx @code{gh_new_procedure1_0}
@itemx @code{gh_new_procedure1_1}
@itemx @code{gh_new_procedure1_2}
@itemx @code{gh_new_procedure2_0}
@itemx @code{gh_new_procedure2_1}
@itemx @code{gh_new_procedure2_2}
@itemx @code{gh_new_procedure3_0}
@itemx @code{gh_new_procedure4_0}
@itemx @code{gh_new_procedure5_0}
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_CRITICAL_SECTION_START} and
@code{SCM_CRITICAL_SECTION_END} instead.  Note that these macros are
used without parentheses, as in @code{SCM_DEFER_INTS;}.

@item @code{gh_bool2scm}
Use @code{scm_from_bool} instead.

@item @code{gh_int2scm}
Use @code{scm_from_int} instead.

@item @code{gh_ulong2scm}
Use @code{scm_from_ulong} instead.

@item @code{gh_long2scm}
Use @code{scm_from_long} 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_from_locale_stringn} instead.

@item @code{gh_str02scm}
Use @code{scm_from_locale_string} instead.

@item @code{gh_set_substr}
Use @code{scm_string_copy_x}.

@item @code{gh_symbol2scm}
Use @code{scm_from_locale_symbol} instead.

@item  @code{gh_ints2scm}
@itemx @code{gh_doubles2scm}
@itemx @code{gh_chars2byvect}
@itemx @code{gh_shorts2svect}
@itemx @code{gh_longs2ivect}
@itemx @code{gh_ulongs2uvect}
@itemx @code{gh_floats2fvect}
@itemx @code{gh_doubles2dvect}
Use the uniform numeric vector function, @xref{Uniform Numeric
Vectors}.

@item @code{gh_scm2bool}
Use @code{scm_is_true} or @code{scm_to_bool} instead.

@item @code{gh_scm2int}
Use @code{scm_to_int} instead.

@item @code{gh_scm2ulong}
Use @code{scm_to_ulong} instead.

@item @code{gh_scm2long}
Use @code{scm_to_long} instead.

@item @code{gh_scm2double}
Use @code{scm_to_double} instead.

@item @code{gh_scm2char}
Use @code{scm_to_char} instead.

@item @code{gh_scm2newstr}
Use @code{scm_to_locale_string} or similar instead.

@item @code{gh_get_substr}
Use @code{scm_c_substring} together with @code{scm_to_locale_string}
or similar instead.

@item @code{gh_symbol2newstr}
Use @code{scm_symbol_to_string} together with @code{scm_to_locale_string} or similar instead.

@item @code{gh_scm2chars}
Use @code{scm_from_locale_string} (or similar) or the uniform numeric
vector functions (@pxref{Uniform Numeric Vectors}) instead.

@item  @code{gh_scm2shorts}
@itemx @code{gh_scm2longs}
@itemx @code{gh_scm2floats}
@itemx @code{gh_scm2doubles}
Use the uniform numeric vector function, @xref{Uniform Numeric
Vectors}.

@item @code{gh_boolean_p}
Use @code{scm_is_bool} instead.

@item @code{gh_symbol_p}
Use @code{scm_is_symbol} instead.

@item @code{gh_char_p}
Replace @code{gh_char_p (@var{obj})} with
@example
scm_is_true (scm_char_p (@var{obj}))
@end example

@item @code{gh_vector_p}
Replace @code{gh_vector_p (@var{obj})} with
@example
scm_is_true (scm_vector_p (@var{obj}))
@end example

@item @code{gh_pair_p}
Replace @code{gh_pair_p (@var{obj})} with
@example
scm_is_true (scm_pair_p (@var{obj}))
@end example

@item @code{gh_number_p}
Use @code{scm_is_number} instead.

@item @code{gh_string_p}
Use @code{scm_is_string} instead.

@item @code{gh_procedure_p}
Replace @code{gh_procedure_p (@var{obj})} by
@example
scm_is_true (scm_procedure_p (@var{obj}))
@end example

@item @code{gh_list_p}
Replace @code{gh_list_p (@var{obj})} with
@example
scm_is_true (scm_list_p (@var{obj}))
@end example

@item @code{gh_inexact_p}
Replace @code{gh_inexact_p (@var{obj})} with
@example
scm_is_true (scm_inexact_p (@var{obj}))
@end example

@item @code{gh_exact_p}
Replace @code{gh_exact_p (@var{obj})} with
@example
scm_is_true (scm_exact_p (@var{obj}))
@end example

@item @code{gh_eq_p}
Use @code{scm_is_eq} instead.

@item @code{gh_eqv_p}
Replace @code{gh_eqv_p (@var{x}, @var{y})} with
@example
scm_is_true (scm_eqv_p (@var{x}, @var{y}))
@end example

@item @code{gh_equal_p}
Replace @code{gh_equal_p (@var{x}, @var{y})} with
@example
scm_is_true (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})} with
@example
scm_is_true (scm_string_equal_p (@var{x}, @var{y}))
@end example

@item @code{gh_null_p}
Use @code{scm_is_null} instead.

@item @code{gh_not}
Use @code{scm_not} instead.

@item @code{gh_make_string}
Use @code{scm_make_string} instead.

@item @code{gh_string_length}
Use @code{scm_string_length} instead.

@item @code{gh_string_ref}
Use @code{scm_string_ref} instead.

@item @code{gh_string_set_x}
Use @code{scm_string_set_x} instead.

@item @code{gh_substring}
Use @code{scm_substring} instead.

@item @code{gh_string_append}
Use @code{scm_string_append} instead.

@item @code{gh_cons}
Use @code{scm_cons} instead.

@item @code{gh_car} and @code{gh_cdr}
Use @code{scm_car} and @code{scm_cdr} 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} function 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_list_n} instead.

@item @code{gh_length}
Replace @code{gh_length (@var{lst})} with
@example
scm_to_size_t (scm_length (@var{lst}))
@end example

@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_list_n (@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 @code{scm_c_vector_length} instead.

@item @code{gh_uniform_vector_length}
Use @code{scm_c_uniform_vector_length} instead.

@item @code{gh_uniform_vector_ref}
Use @code{scm_c_uniform_vector_ref} instead.

@item @code{gh_vector_to_list}
Use @code{scm_vector_to_list} instead.

@item @code{gh_apply}
Use @code{scm_apply_0} instead.

@item  @code{gh_call0}
@itemx @code{gh_call1}
@itemx @code{gh_call2}
@itemx @code{gh_call3}
Use @code{scm_call_0}, @code{scm_call_1}, etc instead.

@item  @code{gh_display}
@itemx @code{gh_write}
@itemx @code{gh_newline}
Use @code{scm_display (obj, scm_current_output_port ())} instead, etc.

@item @code{gh_lookup}
Use @code{scm_variable_ref (scm_c_lookup (name))} instead.

@item @code{gh_module_lookup}
Use @code{scm_variable_ref (scm_c_module_lookup (module, name))} instead.

@end table

@node GH preliminaries
@subsection 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
@subsection Data types and constants defined by GH

The following C constants and data types are defined in gh:

@code{SCM} 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.]

@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
@subsection 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
@subsection 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
@subsection 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
@subsection 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{NB:} 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
@subsection 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
@subsubsection 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
@subsubsection 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}, size_t *@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
@subsection 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
@subsection 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
@subsection 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
@subsection 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_list_n()}.
@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


code:
\input texinfo
@c -*-texinfo-*-
@c %**start of header
@setfilename guile.info
@settitle Guile Reference Manual
@set guile
@set MANUAL-EDITION 1.1
@c %**end of header
@include version.texi

@copying
This reference manual documents Guile, GNU's Ubiquitous Intelligent
Language for Extensions.  This is edition @value{MANUAL-EDITION}
corresponding to Guile @value{VERSION}.

Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
2007, 2008, 2009, 2010 Free Software Foundation.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
no Invariant Sections, with the Front-Cover Texts being ``A GNU
Manual,'' and with the Back-Cover Text ``You are free to copy and
modify this GNU Manual.''.  A copy of the license is included in the
section entitled ``GNU Free Documentation License''.
@end copying

@c Notes
@c
@c We no longer use the category "primitive" to distinguish C-defined
@c Scheme procedures from those defined in Scheme.  Instead, the
@c reference manual now includes a C declaration as well as a Scheme
@c declaration for each procedure that is available in both Scheme and
@c C.
@c
@c When adding a new reference entry to the Guile manual, please
@c document it with @deffn using one of the following categories:
@c
@c   {Scheme Procedure}
@c   {Scheme Syntax}
@c   {C Function}
@c   {C Macro}
@c
@c If the entry is for a new primitive, it should have both a @deffn
@c {Scheme Procedure} line and a @deffnx {C Function} line; see the
@c manual source for plenty of existing examples of this.
@c
@c For {C Function} entries where the return type and all parameter
@c types are SCM, we omit the SCMs.  This is easier to read and also
@c gets round the problem that Texinfo doesn't allow a @deftypefnx
@c inside a @deffn.
@c
@c For a list of Guile primitives that are not yet incorporated into the
@c reference manual, see the file `new-docstrings.texi', which holds all
@c the docstrings snarfed from the libguile C sources for primitives
@c that are not in the reference manual.  If you have worked with some
@c of these concepts, implemented them, or just happen to know what they
@c do, please write up a little explanation -- it would be a big help.
@c Alternatively, if you know of any reason why some of these should
@c *not* go in the manual, please let the mailing list
@c <guile-devel@gnu.org> know.

@c Define indices that are used in the Guile Scheme part of the
@c reference manual to group stuff according to whether it is R5RS or a
@c Guile extension.
@defcodeindex rn

@c vnew - For (some) new items, indicates the Guile version in which
@c item first appeared.  In future, this could be made to expand to
@c something like a "New in Guile 45!" banner.
@macro vnew{VERSION}
@end macro

@c  The following, @le{} and @ge{}, are standard tex directives, given
@c  definitions for use in non-tex.
@c
@ifnottex
@macro ge
>=
@end macro
@macro le
<=
@end macro
@end ifnottex

@c  @cross{} is a \times symbol in tex, or an "x" in info.  In tex it works
@c  inside or outside $ $.
@tex
\gdef\cross{\ifmmode\times\else$\times$\fi}
@end tex
@ifnottex
@macro cross
x
@end macro
@end ifnottex

@c  @m{T,N} is $T$ in tex or @math{N} otherwise.  This is an easy way to give
@c  different forms for math in tex and info.
@iftex
@macro m {T,N}
@tex$\T\$@end tex
@end macro
@end iftex
@ifnottex
@macro m {T,N}
@math{\N\}
@end macro
@end ifnottex

@c  @nicode{S} is plain S in info, or @code{S} elsewhere.  This can be used
@c  when the quotes that @code{} gives in info aren't wanted, but the
@c  fontification in tex or html is wanted.  @alias is used rather
@c  than @macro because backslashes don't work properly in an @macro.
@ifinfo
@alias nicode=asis
@end ifinfo
@ifnotinfo
@alias nicode=code
@end ifnotinfo

@c @iftex
@c @cropmarks
@c @end iftex

@dircategory The Algorithmic Language Scheme
@direntry
* Guile Reference: (guile).     The Guile reference manual.
@end direntry

@setchapternewpage odd

@titlepage
@sp 10
@comment The title is printed in a large font.
@title Guile Reference Manual
@subtitle Edition @value{MANUAL-EDITION}, for use with Guile @value{VERSION}
@c @subtitle $Id: guile.texi,v 1.44.2.2 2008-03-12 00:57:40 ossau Exp $

@c See preface.texi for the list of authors
@author The Guile Developers

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@c @smallbook
@finalout
@headings double

@c Where to find Guile examples.
@set example-dir doc/examples

@ifnottex
@node Top, Preface, (dir), (dir)
@top The Guile Reference Manual

@insertcopying
@sp 1
@end ifnottex

@menu

* Preface::
* Introduction to Guile::

* Programming in Scheme::
* Programming in C::

* API Reference::

* Guile Modules::

* Autoconf Support::

Appendices

* Data Representation::             All the details.
* GNU Free Documentation License::  The license of this manual.

Indices

* Concept Index::
* Procedure Index::
* Variable Index::
* Type Index::
* R5RS Index::

@end menu

@contents

@include preface.texi

@include intro.texi

@node Programming in Scheme
@chapter Programming in Scheme

Guile's core language is Scheme, and an awful lot can be achieved simply
by using Guile to write and run Scheme programs.  In this part of the
manual, we explain how to use Guile in this mode, and describe the tools
that Guile provides to help you with script writing, debugging and
packaging your programs for distribution.

For readers who are not yet familiar with the Scheme language, this part
includes a chapter that presents the basic concepts of the language, and
gives references to freely available Scheme tutorial material on the
web.

For detailed reference information on the variables, functions
etc. that make up Guile's application programming interface (API),
@xref{API Reference}.

@menu
* Basic Ideas::                 Basic ideas in Scheme.
* Guile Scheme::                Guile's implementation of Scheme.
* Guile Scripting::             How to write Guile scripts.
* Using Guile Interactively::   Guile's REPL features.
* Using Guile in Emacs::        Guile and Emacs.
* Further Reading::             Where to find out more about Scheme.
@end menu

@include scheme-ideas.texi
@include scheme-intro.texi
@include scheme-scripts.texi
@include scheme-using.texi
@include scheme-reading.texi

@node Programming in C
@chapter Programming in C

This part of the manual explains the general concepts that you need to
understand when interfacing to Guile from C.  You will learn about how
the latent typing of Scheme is embedded into the static typing of C, how
the garbage collection of Guile is made available to C code, and how
continuations influence the control flow in a C program.

This knowledge should make it straightforward to add new functions to
Guile that can be called from Scheme.  Adding new data types is also
possible and is done by defining @dfn{smobs}.

The @ref{Programming Overview} section of this part contains general
musings and guidelines about programming with Guile.  It explores
different ways to design a program around Guile, or how to embed Guile
into existing programs.

There is also a pedagogical yet detailed explanation of how the data
representation of Guile is implemented, @xref{Data Representation}.
You don't need to know the details given there to use Guile from C,
but they are useful when you want to modify Guile itself or when you
are just curious about how it is all done.

For detailed reference information on the variables, functions
etc. that make up Guile's application programming interface (API),
@xref{API Reference}.

@menu
* Linking Programs With Guile:: More precisely, with the libguile library.
* Linking Guile with Libraries::  To extend Guile itself.
* General Libguile Concepts::   General concepts for using libguile.
* Defining New Types (Smobs)::  Adding new types to Guile.
* Function Snarfing::           A way to define new functions.
* Programming Overview::        An overview of Guile programming.
@end menu

@include libguile-linking.texi
@include libguile-extensions.texi
@include libguile-concepts.texi
@include libguile-smobs.texi
@include libguile-snarf.texi
@include libguile-program.texi

@node API Reference
@chapter API Reference

Guile provides an application programming interface (@dfn{API}) to
developers in two core languages: Scheme and C.  This part of the manual
contains reference documentation for all of the functionality that is
available through both Scheme and C interfaces.

@menu
* API Overview::                Overview of the Guile API.
* The SCM Type::                The fundamental data type for C code.
* Initialization::              Initializing Guile.
* Snarfing Macros::             Macros for snarfing initialization actions.
* Simple Data Types::           Numbers, strings, booleans and so on.
* Compound Data Types::         Data types for holding other data.
* Smobs::                       Defining new data types in C.
* Procedures and Macros::       Procedures and macros.
* Utility Functions::           General utility functions.
* Binding Constructs::          Definitions and variable bindings.
* Control Mechanisms::          Controlling the flow of program execution.
* Input and Output::            Ports, reading and writing.
* Read/Load/Eval::              Reading and evaluating Scheme code.
* Memory Management::           Memory management and garbage collection.
* Objects::                     Low level object orientation support.
* Modules::                     Designing reusable code libraries.
* Scheduling::                  Threads, mutexes, asyncs and dynamic roots.
* Options and Config::          Configuration, features and runtime options.
* Translation::                 Support for translating other languages.
* Internationalization::        Support for gettext, etc.
* Debugging::                   Debugging infrastructure and Scheme interface.
* GH::                          The deprecated GH interface.
@end menu

@include api-overview.texi
@include api-scm.texi
@include api-init.texi
@include api-snarf.texi
@include api-data.texi
@include api-compound.texi
@include api-smobs.texi
@include api-procedures.texi
@include api-utility.texi
@include api-binding.texi
@include api-control.texi
@include api-io.texi
@include api-evaluation.texi
@include api-memory.texi
@include api-modules.texi
@include api-scheduling.texi
@c object orientation support here
@include api-options.texi
@include api-translation.texi
@include api-i18n.texi
@include api-debug.texi
@include gh.texi

@node Guile Modules
@chapter Guile Modules

@menu
* SLIB::                        Using the SLIB Scheme library.
* POSIX::                       POSIX system calls and networking.
* getopt-long::                 Command line handling.
* SRFI Support::                Support for various SRFIs.
* Readline Support::            Module for using the readline library.
* Value History::               Maintaining a value history in the REPL.
* Pretty Printing::             Nicely formatting Scheme objects for output.
* Formatted Output::            The @code{format} procedure.
* File Tree Walk::              Traversing the file system.
* Queues::                      First-in first-out queuing.
* Streams::                     Sequences of values.
* Buffered Input::              Ports made from a reader function.
* Expect::			Controlling interactive programs with Guile.
* The Scheme shell (scsh)::     Using scsh interfaces in Guile.
* Tracing::                     Tracing program execution.
@end menu

@include slib.texi
@include posix.texi
@include mod-getopt-long.texi
@include srfi-modules.texi
@include repl-modules.texi
@include misc-modules.texi
@include expect.texi
@include scsh.texi
@include scheme-debugging.texi

@include autoconf.texi

@include data-rep.texi
@include fdl.texi

@iftex
@page
@unnumbered{Indices}
@end iftex

@include indices.texi
@include scheme-indices.texi

@bye

license: unknown


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@page
@node Concept Index
@unnumbered Concept Index

This index contains concepts, keywords and non-Schemey names for several
features, to make it easier to locate the desired sections.

@printindex cp

@page
@node Procedure Index
@unnumbered Procedure Index

@c FIXME::martin: Review me!

This is an alphabetical list of all the procedures and macros in Guile.

When looking for a particular procedure, please look under its Scheme
name as well as under its C name.  The C name can be constructed from
the Scheme names by a simple transformation described in the section
@xref{API Overview}.

@printindex fn

@page
@node Variable Index
@unnumbered Variable Index

@c FIXME::martin: Review me!

This is an alphabetical list of all the important variables and
constants in Guile.

When looking for a particular variable or constant, please look under
its Scheme name as well as under its C name.  The C name can be
constructed from the Scheme names by a simple transformation described
in the section @xref{API Overview}.

@printindex vr

@page
@node Type Index
@unnumbered Type Index

This is an alphabetical list of all the important data types defined in
the Guile Programmers Manual.

@printindex tp


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@node Introduction to Guile
@chapter Introduction to Guile

@menu
* What is Guile?::
* Obtaining and Installing Guile::
* Whirlwind Tour::
* Discouraged and Deprecated::
* Reporting Bugs::
@end menu

@node What is Guile?
@section What is Guile?

Guile is an interpreter for the Scheme programming language, packaged
for use in a wide variety of environments.  Guile implements Scheme as
described in the
@tex
Revised$^5$
@end tex
@ifnottex
Revised^5
@end ifnottex
Report on the Algorithmic Language Scheme (usually known as @acronym{R5RS}),
providing clean and general data and control structures.  Guile goes
beyond the rather austere language presented in @acronym{R5RS}, extending it with
a module system, full access to @acronym{POSIX} system calls, networking support,
multiple threads, dynamic linking, a foreign function call interface,
powerful string processing, and many other features needed for
programming in the real world.

Like a shell, Guile can run interactively, reading expressions from the
user, evaluating them, and displaying the results, or as a script
interpreter, reading and executing Scheme code from a file.  However,
Guile is also packaged as an object library, allowing other applications
to easily incorporate a complete Scheme interpreter.  An application can
then use Guile as an extension language, a clean and powerful configuration
language, or as multi-purpose ``glue'', connecting primitives provided
by the application.  It is easy to call Scheme code from C code and vice
versa, giving the application designer full control of how and when to
invoke the interpreter.  Applications can add new functions, data types,
control structures, and even syntax to Guile, creating a domain-specific
language tailored to the task at hand, but based on a robust language
design.

Guile's module system allows one to break up a large program into
manageable sections with well-defined interfaces between them.
Modules may contain a mixture of interpreted and compiled code; Guile
can use either static or dynamic linking to incorporate compiled code.
Modules also encourage developers to package up useful collections of
routines for general distribution; as of this writing, one can find
Emacs interfaces, database access routines, compilers, @acronym{GUI}
toolkit interfaces, and @acronym{HTTP} client functions, among others.

In the future, we hope to expand Guile to support other languages like
Tcl and Perl by translating them to Scheme code.  This means that users
can program applications which use Guile in the language of their
choice, rather than having the tastes of the application's author
imposed on them.

@node Obtaining and Installing Guile
@section Obtaining and Installing Guile

Guile can be obtained from the main GNU archive site
@url{ftp://ftp.gnu.org} or any of its mirrors.  The file will be named
guile-@var{version}.tar.gz.  The current version is @value{VERSION},
so the file you should grab is:

@url{ftp://ftp.gnu.org/gnu/guile/guile-@value{VERSION}.tar.gz}

To unbundle Guile use the instruction

@example
zcat guile-@value{VERSION}.tar.gz | tar xvf -
@end example

which will create a directory called @file{guile-@value{VERSION}} with
all the sources.  You can look at the file @file{INSTALL} for detailed
instructions on how to build and install Guile, but you should be able
to just do

@example
cd guile-@value{VERSION}
./configure
make
make install
@end example

This will install the Guile executable @file{guile}, the Guile library
@file{-lguile} and various associated header files and support
libraries. It will also install the Guile tutorial and reference
manual.

@c [[include instructions for getting R5RS]]

Since this manual frequently refers to the Scheme ``standard'', also
known as R5RS, or the
@iftex
``Revised$^5$ Report on the Algorithmic Language Scheme'',
@end iftex
@ifnottex
``Revised^5 Report on the Algorithmic Language Scheme'',
@end ifnottex
we have included the report in the Guile distribution;
@xref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
Language Scheme}.
This will also be installed in your info directory.

@node Whirlwind Tour
@section A Whirlwind Tour

This chapter presents a quick tour of all the ways that Guile can be
used.  There are additional examples in the @file{examples/}
directory in the Guile source distribution.

The following examples assume that Guile has been installed in
@code{/usr/local/}.

@menu
* Running Guile Interactively::
* Running Guile Scripts::
* Linking Guile into Programs::
* Writing Guile Extensions::
* Using the Guile Module System::
@end menu

@node Running Guile Interactively
@subsection Running Guile Interactively

In its simplest form, Guile acts as an interactive interpreter for the
Scheme programming language, reading and evaluating Scheme expressions
the user enters from the terminal.  Here is a sample interaction between
Guile and a user; the user's input appears after the @code{$} and
@code{guile>} prompts:

@example
$ guile
guile> (+ 1 2 3)                ; add some numbers
6
guile> (define (factorial n)    ; define a function
         (if (zero? n) 1 (* n (factorial (- n 1)))))
guile> (factorial 20)
2432902008176640000
guile> (getpwnam "jimb")        ; find my entry in /etc/passwd
#("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
  "/usr/local/bin/bash")
guile> @kbd{C-d}
$
@end example

@node Running Guile Scripts
@subsection Running Guile Scripts

Like AWK, Perl, or any shell, Guile can interpret script files.  A Guile
script is simply a file of Scheme code with some extra information at
the beginning which tells the operating system how to invoke Guile, and
then tells Guile how to handle the Scheme code.

Here is a trivial Guile script, for more details @xref{Guile Scripting}.

@example
#!/usr/local/bin/guile -s
!#
(display "Hello, world!")
(newline)
@end example

@node Linking Guile into Programs
@subsection Linking Guile into Programs

The Guile interpreter is available as an object library, to be linked
into applications using Scheme as a configuration or extension
language.

Here is @file{simple-guile.c}, source code for a program that will
produce a complete Guile interpreter.  In addition to all usual
functions provided by Guile, it will also offer the function
@code{my-hostname}.

@example
#include <stdlib.h>
#include <libguile.h>

static SCM
my_hostname (void)
@{
  char *s = getenv ("HOSTNAME");
  if (s == NULL)
    return SCM_BOOL_F;
  else
    return scm_from_locale_string (s);
@}

static void
inner_main (void *data, int argc, char **argv)
@{
  scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
  scm_shell (argc, argv);
@}

int
main (int argc, char **argv)
@{
  scm_boot_guile (argc, argv, inner_main, 0);
  return 0; /* never reached */
@}
@end example

When Guile is correctly installed on your system, the above program
can be compiled and linked like this:

@example
$ gcc -o simple-guile simple-guile.c -lguile
@end example

When it is run, it behaves just like the @code{guile} program except
that you can also call the new @code{my-hostname} function.

@example
$ ./simple-guile
guile> (+ 1 2 3)
6
guile> (my-hostname)
"burns"
@end example

@node Writing Guile Extensions
@subsection Writing Guile Extensions

You can link Guile into your program and make Scheme available to the
users of your program.  You can also link your library into Guile and
make its functionality available to all users of Guile.

A library that is linked into Guile is called an @dfn{extensions}, but
it really just is an ordinary object library.

The following example shows how to write a simple extension for Guile
that makes the @code{j0} function available to Scheme code.

@smallexample
#include <math.h>
#include <libguile.h>

SCM
j0_wrapper (SCM x)
@{
  return scm_make_real (j0 (scm_num2dbl (x, "j0")));
@}

void
init_bessel ()
@{
  scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
@}
@end smallexample

This C source file needs to be compiled into a shared library.  Here is
how to do it on GNU/Linux:

@smallexample
gcc -shared -o libguile-bessel.so -fPIC bessel.c
@end smallexample

For creating shared libraries portably, we recommend the use of GNU
Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}).

A shared library can be loaded into a running Guile process with the
function @code{load-extension}.  The @code{j0} is then immediately
available:

@smallexample
$ guile
guile> (load-extension "./libguile-bessel" "init_bessel")
guile> (j0 2)
0.223890779141236
@end smallexample

@node Using the Guile Module System
@subsection Using the Guile Module System

Guile has support for dividing a program into @dfn{modules}.  By using
modules, you can group related code together and manage the
composition of complete programs from largely independent parts.

(Although the module system implementation is in flux, feel free to use it
anyway.  Guile will provide reasonable backwards compatibility.)

Details on the module system beyond this introductory material can be found in
@xref{Modules}.

@menu
* Using Modules::
* Writing new Modules::
* Putting Extensions into Modules::
@end menu

@node Using Modules
@subsubsection Using Modules

Guile comes with a lot of useful modules, for example for string
processing or command line parsing.  Additionally, there exist many
Guile modules written by other Guile hackers, but which have to be
installed manually.

Here is a sample interactive session that shows how to use the
@code{(ice-9 popen)} module which provides the means for communicating
with other processes over pipes together with the @code{(ice-9
rdelim)} module that provides the function @code{read-line}.

@smallexample
$ guile
guile> (use-modules (ice-9 popen))
guile> (use-modules (ice-9 rdelim))
guile> (define p (open-input-pipe "ls -l"))
guile> (read-line p)
"total 30"
guile> (read-line p)
"drwxr-sr-x    2 mgrabmue mgrabmue     1024 Mar 29 19:57 CVS"
@end smallexample

@node Writing new Modules
@subsubsection Writing new Modules

You can create new modules using the syntactic form
@code{define-module}.  All definitions following this form until the
next @code{define-module} are placed into the new module.

One module is usually placed into one file, and that file is installed
in a location where Guile can automatically find it.  The following
session shows a simple example.

@smallexample
$ cat /usr/local/share/guile/foo/bar.scm

(define-module (foo bar))
(export frob)

(define (frob x) (* 2 x))

$ guile
guile> (use-modules (foo bar))
guile> (frob 12)
24
@end smallexample

@node Putting Extensions into Modules
@subsubsection Putting Extensions into Modules

In addition to Scheme code you can also put things that are defined in
C into a module.

You do this by writing a small Scheme file that defines the module and
call @code{load-extension} directly in the body of the module.

@smallexample
$ cat /usr/local/share/guile/math/bessel.scm

(define-module (math bessel))
(export j0)

(load-extension "libguile-bessel" "init_bessel")

$ file /usr/local/lib/libguile-bessel.so
@dots{} ELF 32-bit LSB shared object @dots{}
$ guile
guile> (use-modules (math bessel))
guile> (j0 2)
0.223890779141236
@end smallexample

There is also a way to manipulate the module system from C but only
Scheme files can be autoloaded.  Thus, we recommend that you define
your modules in Scheme.

@node Discouraged and Deprecated
@section Discouraged and Deprecated

From time to time functions and other features of Guile become
obsolete.  Guile has some mechanisms in place that can help you cope
with this.

Guile has two levels of obsoleteness: things can be @emph{deprecated},
meaning that their use is considered harmful and should be avoided,
even in old code; or they can be merely @emph{discouraged}, meaning
that they are fine in and of themselves, but that there are better
alternatives that should be used in new code.

When you use a feature that is deprecated, you will likely get a
warning message at run-time.  Also, deprecated features are not ready
for production use: they might be very slow.  When something is merely
discouraged, it performs normally and you wont get any messages at
run-time.

The primary source for information about just what things are
discouraged or deprecated in a given release is the file
@file{NEWS}.  That file also documents what you should use instead
of the obsoleted things.

The file @file{README} contains instructions on how to control the
inclusion or removal of the deprecated and/or discouraged features
from the public API of Guile, and how to control the warning messages
for deprecated features.

The idea behind those mechanisms is that normally all deprecated and
discouraged features are available, but that you can omit them on
purpose to check whether your code still relies on them.

@node Reporting Bugs
@section Reporting Bugs

Any problems with the installation should be reported to
@email{bug-guile@@gnu.org}.

Whenever you have found a bug in Guile you are encouraged to report it
to the Guile developers, so they can fix it.  They may also be able to
suggest workarounds when it is not possible for you to apply the bug-fix
or install a new version of Guile yourself.

Before sending in bug reports, please check with the following list that
you really have found a bug.

@itemize @bullet
@item
Whenever documentation and actual behavior differ, you have certainly
found a bug, either in the documentation or in the program.

@item
When Guile crashes, it is a bug.

@item
When Guile hangs or takes forever to complete a task, it is a bug.

@item
When calculations produce wrong results, it is a bug.

@item
When Guile signals an error for valid Scheme programs, it is a bug.

@item
When Guile does not signal an error for invalid Scheme programs, it may
be a bug, unless this is explicitly documented.

@item
When some part of the documentation is not clear and does not make sense
to you even after re-reading the section, it is a bug.
@end itemize

When you write a bug report, please make sure to include as much of the
information described below in the report.  If you can't figure out some
of the items, it is not a problem, but the more information we get, the
more likely we can diagnose and fix the bug.

@itemize @bullet
@item
The version number of Guile.  Without this, we won't know whether there
is any point in looking for the bug in the current version of Guile.

You can get the version number by invoking the command

@example
$ guile --version
Guile 1.4.1
Copyright (c) 1995, 1996, 1997, 2000, 2006 Free Software Foundation
Guile may be distributed under the terms of the GNU General Public License;
certain other uses are permitted as well.  For details, see the file
`COPYING', which is included in the Guile distribution.
There is no warranty, to the extent permitted by law.
@end example

@item
The type of machine you are using, and the operating system name and
version number.  On GNU systems, you can get it with @file{uname}.

@example
$ uname -a
Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown
@end example

@item
The operands given to the @file{configure} command when Guile was
installed.  It's often useful to augment this with the output of the
command @code{guile-config info}.

@item
A complete list of any modifications you have made to the Guile source.
(We may not have time to investigate the bug unless it happens in an
unmodified Guile.  But if you've made modifications and you don't tell
us, you are sending us on a wild goose chase.)

Be precise about these changes.  A description in English is not
enough---send a context diff for them.

Adding files of your own, or porting to another machine, is a
modification of the source.

@item
Details of any other deviations from the standard procedure for
installing Guile.

@item
The complete text of any source files needed to reproduce the bug.

If you can tell us a way to cause the problem without loading any source
files, please do so.  This makes it much easier to debug.  If you do
need files, make sure you arrange for us to see their exact contents.

@item
The precise Guile invocation command line we need to type to reproduce
the bug.

@item
A description of what behavior you observe that you believe is
incorrect.  For example, "The Guile process gets a fatal signal," or,
"The resulting output is as follows, which I think is wrong."

Of course, if the bug is that Guile gets a fatal signal, then one can't
miss it.  But if the bug is incorrect results, the maintainer might fail
to notice what is wrong.  Why leave it to chance?

If the manifestation of the bug is a Guile error message, it is
important to report the precise text of the error message, and a
backtrace showing how the Scheme program arrived at the error.

This can be done using the procedure @code{backtrace} in the REPL.

@item
Check whether any programs you have loaded into Guile, including your
@file{.guile} file, set any variables that may affect the functioning of
Guile.  Also, see whether the problem happens in a freshly started Guile
without loading your @file{.guile} file (start Guile with the @code{-q}
switch to prevent loading the init file).  If the problem does
@emph{not} occur then, you must report the precise contents of any
programs that you must load into Guile in order to cause the problem to
occur.

@item
If the problem does depend on an init file or other Scheme programs that
are not part of the standard Guile distribution, then you should make
sure it is not a bug in those programs by complaining to their
maintainers first.  After they verify that they are using Guile in a way
that is supposed to work, they should report the bug.

@item
If you wish to mention something in the Guile source, show the line of
code with a few lines of context.  Don't just give a line number.

The line numbers in the development sources might not match those in your
sources.  It would take extra work for the maintainers to determine what
code is in your version at a given line number, and we could not be
certain.

@item
Additional information from a C debugger such as GDB might enable
someone to find a problem on a machine which he does not have available.
If you don't know how to use GDB, please read the GDB manual---it is not
very long, and using GDB is easy.  You can find the GDB distribution,
including the GDB manual in online form, in most of the same places you
can find the Guile distribution.  To run Guile under GDB, you should
switch to the @file{libguile} subdirectory in which Guile was compiled, then
do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool).

However, you need to think when you collect the additional information
if you want it to show what causes the bug.

For example, many people send just a backtrace, but that is not very
useful by itself.  A simple backtrace with arguments often conveys
little about what is happening inside Guile, because most of the
arguments listed in the backtrace are pointers to Scheme objects.  The
numeric values of these pointers have no significance whatever; all that
matters is the contents of the objects they point to (and most of the
contents are themselves pointers).
@end itemize

@c Local Variables:
@c TeX-master: "guile.texi"
@c End: