summaryrefslogtreecommitdiff
path: root/doc/ref/scm.texi
blob: 948823afb88060c8246cef5ca076f303af553bd6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
@page
@node Scheme Primitives
@c @chapter Writing Scheme primitives in C
@c - according to the menu in guile.texi - NJ 2001/1/26
@chapter Relationship between Scheme and C functions

@c Chapter contents contributed by Thien-Thi Nguyen <ttn@gnu.org>.

Scheme procedures marked "primitive functions" have a regular interface
when calling from C, reflected in two areas: the name of a C function, and
the convention for passing non-required arguments to this function.

@c Although the vast majority of functions support these relationships,
@c there are some exceptions.

@menu
* Transforming Scheme name to C name::
* Structuring argument lists for C functions::
@c * Exceptions to the regularity::
@end menu

@node Transforming Scheme name to C name
@section Transforming Scheme name to C name

Normally, the name of a C function can be derived given its Scheme name,
using some simple textual transformations:

@itemize @bullet

@item
Replace @code{-} (hyphen) with @code{_} (underscore).

@item
Replace @code{?} (question mark) with "_p".

@item
Replace @code{!} (exclamation point) with "_x".

@item
Replace internal @code{->} with "_to_".

@item
Replace @code{<=} (less than or equal) with "_leq".

@item
Replace @code{>=} (greater than or equal) with "_geq".

@item
Replace @code{<} (less than) with "_less".

@item
Replace @code{>} (greater than) with "_gr".

@item
Replace @code{@@} with "at". [Omit?]

@item
Prefix with "gh_" (or "scm_" if you are ignoring the gh interface).

@item
[Anything else?  --ttn, 2000/01/16 15:17:28]

@end itemize

Here is an Emacs Lisp command that prompts for a Scheme function name and
inserts the corresponding C function name into the buffer.

@example
(defun insert-scheme-to-C (name &optional use-gh)
  "Transforms Scheme NAME, a string, to its C counterpart, and inserts it.
Prefix arg non-nil means use \"gh_\" prefix, otherwise use \"scm_\" prefix."
  (interactive "sScheme name: \nP")
  (let ((transforms '(("-"  . "_")
                      ("?"  . "_p")
                      ("!"  . "_x")
                      ("->" . "_to_")
                      ("<=" . "_leq")
                      (">=" . "_geq")
                      ("<"  . "_less")
                      (">"  . "_gr")
                      ("@@"  . "at"))))
    (while transforms
      (let ((trigger (concat "\\(.*\\)"
                             (regexp-quote (caar transforms))
                             "\\(.*\\)"))
            (sub (cdar transforms))
            (m nil))
        (while (setq m (string-match trigger name))
          (setq name (concat (match-string 1 name)
                             sub
                             (match-string 2 name)))))
      (setq transforms (cdr transforms))))
  (insert (if use-gh "gh_" "scm_") name))
@end example

@node Structuring argument lists for C functions
@section Structuring argument lists for C functions

The C function's arguments will be all of the Scheme procedure's
argumements, both required and optional; if the Scheme procedure takes a
``rest'' argument, that will be a final argument to the C function.  The
C function's arguments, as well as its return type, will be @code{SCM}.