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 |
|
|
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: |
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 |