@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

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
arguments, 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}.

@c @node Exceptions to the regularity
@c @section Exceptions to the regularity
@c
@c There are some exceptions to the regular structure described above.


@c scm.texi ends here