diff options
Diffstat (limited to 'doc/ref/scheme-procedures.texi')
-rw-r--r-- | doc/ref/scheme-procedures.texi | 37 |
1 files changed, 37 insertions, 0 deletions
diff --git a/doc/ref/scheme-procedures.texi b/doc/ref/scheme-procedures.texi index 8c08b387c..bc9c0baed 100644 --- a/doc/ref/scheme-procedures.texi +++ b/doc/ref/scheme-procedures.texi @@ -4,6 +4,7 @@ @menu * Lambda:: Basic procedure creation using lambda. +* Primitive Procedures:: Procedures defined in C. * Optional Arguments:: Handling keyword, optional and rest arguments. * Procedure Properties:: Procedure properties and meta-information. * Procedures with Setters:: Procedures with setters. @@ -80,6 +81,42 @@ empty list is stored into the location of the last formal argument. order when the procedure is invoked. @end deffn +@node Primitive Procedures +@section Primitive Procedures +@cindex primitives +@cindex primitive procedures + +Procedures written in C can be registered for use from Scheme, +provided they take only arguments of type @code{SCM} and return +@code{SCM} values. @code{scm_c_define_gsubr} is likely to be the most +useful mechanism, combining the process of registration +(@code{scm_c_make_gsubr}) and definition (@code{scm_define}). + +@deftypefun SCM scm_c_make_gsubr (const char *name, int req, int opt, int rst, fcn) +Register a C procedure @var{FCN} as a ``subr'' --- a primitive +subroutine that can be called from Scheme. It will be associated with +the given @var{name} but no environment binding will be created. The +arguments @var{req}, @var{opt} and @var{rst} specify the number of +required, optional and ``rest'' arguments respectively. The total +number of these arguments should match the actual number of arguments +to @var{fcn}. The number of rest arguments should be 0 or 1. +@code{scm_c_make_gsubr} returns a value of type @code{SCM} which is a +``handle'' for the procedure. +@end deftypefun + +@deftypefun SCM scm_c_define_gsubr (const char *name, int req, int opt, int rst, fcn) +Register a C procedure @var{FCN}, as for @code{scm_c_make_gsubr} +above, and additionally create a top-level Scheme binding for the +procedure in the ``current environment'' using @code{scm_define}. +@code{scm_c_define_gsubr} returns a handle for the procedure in the +same way as @code{scm_c_make_gsubr}, which is usually not further +required. +@end deftypefun + +@code{scm_c_make_gsubr} and @code{scm_c_define_gsubr} automatically +use @code{scm_c_make_subr} and also @code{scm_makcclo} if necessary. +It is advisable to use the gsubr variants since they provide a +slightly higher-level abstraction of the Guile implementation. @node Optional Arguments @section Optional Arguments |