/[guile]/guile/guile-core/doc/ref/scm.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/scm.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.3 by ossau, Sun Nov 11 15:01:51 2001 UTC revision 1.4 by ossau, Fri Dec 7 17:08:19 2001 UTC
# Line 1  Line 1 
1  @page  @page
2  @node Scheme Primitives  @node Guile API
3    @chapter Overview of the Guile API
4    
5    Guile's application programming interface (@dfn{API}) makes
6    functionality available that an application developer can use in either
7    C or Scheme programming.  The interface consists of @dfn{elements} that
8    may be macros, functions or variables in C, and procedures, variables,
9    syntax or other types of object in Scheme.  Broadly speaking, the
10    interface as a whole can be divided into three groups.
11    
12    @enumerate
13    @item
14    Elements that are available equivalently as C functions or Scheme
15    procedures.
16    
17    @item
18    Elements that are only available as macros, functions or variables for C
19    programming.
20    
21    @item
22    Elements that are only available as procedures or other objects in
23    Scheme.
24    @end enumerate
25    
26    Functions/procedures in the first group are often known as
27    @dfn{primitives}, @dfn{subrs} or @dfn{builtins}.  An example is the
28    @code{assq} Scheme procedure, which is also available as @code{scm_assq}
29    in C.
30    
31    Elements in the second and third groups exist because they provide
32    additional language-specific benefits in either Scheme or C.  Examples
33    are the C macro @code{SCM_CONSP}, which is faster and more convenient in
34    C programming than the primitive @code{scm_pair_p}, and the
35    procedure-with-setter @code{make-object-property}, which provides a
36    more convenient property handling interface in Scheme than the
37    primitives on which it is based.
38    
39    @menu
40    * Primitives::                  Identical function for Scheme and C.
41    * C Only::                      Elements only available in C.
42    * Scheme Only::                 Elements only available in Scheme.
43    @end menu
44    
45    
46    @node Primitives
47    @section Identical Function in both Scheme and C
48    
49    They form the majority of the API, and allow both C and Scheme
50    programmers to perform identical operations.
51    
52    @c @node Scheme Primitives
53  @c @chapter Writing Scheme primitives in C  @c @chapter Writing Scheme primitives in C
54  @c - according to the menu in guile.texi - NJ 2001/1/26  @c - according to the menu in guile.texi - NJ 2001/1/26
55  @chapter Relationship between Scheme and C functions  @c @chapter Relationship between Scheme and C functions
56    
57  @c Chapter contents contributed by Thien-Thi Nguyen <ttn@gnu.org>.  @c Chapter contents contributed by Thien-Thi Nguyen <ttn@gnu.org>.
58    
# Line 19  the convention for passing non-required Line 69  the convention for passing non-required
69  @c * Exceptions to the regularity::  @c * Exceptions to the regularity::
70  @end menu  @end menu
71    
72    
73  @node Transforming Scheme name to C name  @node Transforming Scheme name to C name
74  @section Transforming Scheme name to C name  @subsection Transforming Scheme name to C name
75    
76  Normally, the name of a C function can be derived given its Scheme name,  Normally, the name of a C function can be derived given its Scheme name,
77  using some simple textual transformations:  using some simple textual transformations:
# Line 93  Prefix arg non-nil means use \"gh_\" pre Line 144  Prefix arg non-nil means use \"gh_\" pre
144    (insert (if use-gh "gh_" "scm_") name))    (insert (if use-gh "gh_" "scm_") name))
145  @end example  @end example
146    
147    
148  @node Structuring argument lists for C functions  @node Structuring argument lists for C functions
149  @section Structuring argument lists for C functions  @subsection Structuring argument lists for C functions
150    
151  The C function's arguments will be all of the Scheme procedure's  The C function's arguments will be all of the Scheme procedure's
152  argumements, both required and optional; if the Scheme procedure takes a  argumements, both required and optional; if the Scheme procedure takes a
153  ``rest'' argument, that will be a final argument to the C function.  The  ``rest'' argument, that will be a final argument to the C function.  The
154  C function's arguments, as well as its return type, will be @code{SCM}.  C function's arguments, as well as its return type, will be @code{SCM}.
155    
156    
157    @node C Only
158    @section Elements Available Only in C
159    
160    For C this is usually a matter of better performance (e.g. the
161    @code{SCM_CONSP} macro) or of accepting C language types rather than the
162    generic @code{SCM}.
163    
164    
165    @node Scheme Only
166    @section Elements Available Only in Scheme

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.4

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26