Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 | |
4 | @c Free Software Foundation, Inc. | |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
07d83abe MV |
7 | @node API Overview |
8 | @section Overview of the Guile API | |
9 | ||
10 | Guile's application programming interface (@dfn{API}) makes | |
11 | functionality available that an application developer can use in either | |
12 | C or Scheme programming. The interface consists of @dfn{elements} that | |
13 | may be macros, functions or variables in C, and procedures, variables, | |
14 | syntax or other types of object in Scheme. | |
15 | ||
16 | Many elements are available to both Scheme and C, in a form that is | |
17 | appropriate. For example, the @code{assq} Scheme procedure is also | |
18 | available as @code{scm_assq} to C code. These elements are documented | |
19 | only once, addressing both the Scheme and C aspects of them. | |
20 | ||
21 | The Scheme name of an element is related to its C name in a regular | |
22 | way. Also, a C function takes its parameters in a systematic way. | |
23 | ||
24 | Normally, the name of a C function can be derived given its Scheme name, | |
25 | using some simple textual transformations: | |
26 | ||
27 | @itemize @bullet | |
28 | ||
29 | @item | |
30 | Replace @code{-} (hyphen) with @code{_} (underscore). | |
31 | ||
32 | @item | |
33 | Replace @code{?} (question mark) with @code{_p}. | |
34 | ||
35 | @item | |
36 | Replace @code{!} (exclamation point) with @code{_x}. | |
37 | ||
38 | @item | |
39 | Replace internal @code{->} with @code{_to_}. | |
40 | ||
41 | @item | |
42 | Replace @code{<=} (less than or equal) with @code{_leq}. | |
43 | ||
44 | @item | |
45 | Replace @code{>=} (greater than or equal) with @code{_geq}. | |
46 | ||
47 | @item | |
48 | Replace @code{<} (less than) with @code{_less}. | |
49 | ||
50 | @item | |
51 | Replace @code{>} (greater than) with @code{_gr}. | |
52 | ||
53 | @item | |
54 | Prefix with @code{scm_}. | |
55 | ||
56 | @end itemize | |
57 | ||
58 | @c Here is an Emacs Lisp command that prompts for a Scheme function name and | |
59 | @c inserts the corresponding C function name into the buffer. | |
60 | ||
61 | @c @example | |
62 | @c (defun insert-scheme-to-C (name &optional use-gh) | |
63 | @c "Transforms Scheme NAME, a string, to its C counterpart, and inserts it. | |
64 | @c Prefix arg non-nil means use \"gh_\" prefix, otherwise use \"scm_\" prefix." | |
65 | @c (interactive "sScheme name: \nP") | |
66 | @c (let ((transforms '(("-" . "_") | |
67 | @c ("?" . "_p") | |
68 | @c ("!" . "_x") | |
69 | @c ("->" . "_to_") | |
70 | @c ("<=" . "_leq") | |
71 | @c (">=" . "_geq") | |
72 | @c ("<" . "_less") | |
73 | @c (">" . "_gr") | |
74 | @c ("@@" . "at")))) | |
75 | @c (while transforms | |
76 | @c (let ((trigger (concat "\\(.*\\)" | |
77 | @c (regexp-quote (caar transforms)) | |
78 | @c "\\(.*\\)")) | |
79 | @c (sub (cdar transforms)) | |
80 | @c (m nil)) | |
81 | @c (while (setq m (string-match trigger name)) | |
82 | @c (setq name (concat (match-string 1 name) | |
83 | @c sub | |
84 | @c (match-string 2 name))))) | |
85 | @c (setq transforms (cdr transforms)))) | |
86 | @c (insert (if use-gh "gh_" "scm_") name)) | |
87 | @c @end example | |
88 | ||
89 | A C function always takes a fixed number of arguments of type | |
90 | @code{SCM}, even when the corresponding Scheme function takes a | |
91 | variable number. | |
92 | ||
93 | For some Scheme functions, some last arguments are optional; the | |
94 | corresponding C function must always be invoked with all optional | |
95 | arguments specified. To get the effect as if an argument has not been | |
96 | specified, pass @code{SCM_UNDEFINED} as its value. You can not do | |
97 | this for an argument in the middle; when one argument is | |
98 | @code{SCM_UNDEFINED} all the ones following it must be | |
99 | @code{SCM_UNDEFINED} as well. | |
100 | ||
101 | Some Scheme functions take an arbitrary number of @emph{rest} | |
102 | arguments; the corresponding C function must be invoked with a list of | |
103 | all these arguments. This list is always the last argument of the C | |
104 | function. | |
105 | ||
106 | These two variants can also be combined. | |
107 | ||
108 | The type of the return value of a C function that corresponds to a | |
109 | Scheme function is always @code{SCM}. In the descriptions below, | |
03f6e5ed | 110 | types are therefore often omitted but for the return value and for the |
07d83abe | 111 | arguments. |