doc/ref/scm.texi

   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
   7 @page
   8 @node API Overview
   9 @chapter Overview of the Guile API
  10
  11 Guile's application programming interface (@dfn{API}) makes
  12 functionality available that an application developer can use in either
  13 C or Scheme programming.  The interface consists of @dfn{elements} that
  14 may be macros, functions or variables in C, and procedures, variables,
  15 syntax or other types of object in Scheme.  Broadly speaking, the
  16 interface as a whole can be divided into three groups.
  17
  18 @enumerate
  19 @item
  20 Elements that are available equivalently as C functions or Scheme
  21 procedures.
  22
  23 @item
  24 Elements that are only available as macros, functions or variables for C
  25 programming.
  26
  27 @item
  28 Elements that are only available as procedures or other objects in
  29 Scheme.
  30 @end enumerate
  31
  32 Functions/procedures in the first group are often known as
  33 @dfn{primitives}, @dfn{subrs} or @dfn{builtins}.  An example is the
  34 @code{assq} Scheme procedure, which is also available as @code{scm_assq}
  35 in C.
  36
  37 Elements in the second and third groups exist because they provide
  38 additional language-specific benefits in either Scheme or C.  Examples
  39 are the C macro @code{SCM_CONSP}, which is faster and more convenient in
  40 C programming than the primitive @code{scm_pair_p}, and the
  41 procedure-with-setter @code{make-object-property}, which provides a
  42 more convenient property handling interface in Scheme than the
  43 primitives on which it is based.
  44
  45 @menu
  46 * Primitives::                  Identical function for Scheme and C.
  47 * C Only::                      Elements only available in C.
  48 * Scheme Only::                 Elements only available in Scheme.
  49 * Reference Layout::            The layout of this part of the manual.
  50 @end menu
  51
  52
  53 @node Primitives
  54 @section Identical Function in both Scheme and C
  55
  56 They form the majority of the API, and allow both C and Scheme
  57 programmers to perform identical operations.
  58
  59 @c @node Scheme Primitives
  60 @c @chapter Writing Scheme primitives in C
  61 @c - according to the menu in guile.texi - NJ 2001/1/26
  62 @c @chapter Relationship between Scheme and C functions
  63
  64 @c Chapter contents contributed by Thien-Thi Nguyen <ttn@gnu.org>.
  65
  66 Scheme procedures marked "primitive functions" have a regular interface
  67 when calling from C, reflected in two areas: the name of a C function, and
  68 the convention for passing non-required arguments to this function.
  69
  70 @c Although the vast majority of functions support these relationships,
  71 @c there are some exceptions.
  72
  73 @menu
  74 * Transforming Scheme name to C name::
  75 * Structuring argument lists for C functions::
  76 @c * Exceptions to the regularity::
  77 @end menu
  78
  79
  80 @node Transforming Scheme name to C name
  81 @subsection Transforming Scheme name to C name
  82
  83 Normally, the name of a C function can be derived given its Scheme name,
  84 using some simple textual transformations:
  85
  86 @itemize @bullet
  87
  88 @item
  89 Replace @code{-} (hyphen) with @code{_} (underscore).
  90
  91 @item
  92 Replace @code{?} (question mark) with "_p".
  93
  94 @item
  95 Replace @code{!} (exclamation point) with "_x".
  96
  97 @item
  98 Replace internal @code{->} with "_to_".
  99
 100 @item
 101 Replace @code{<=} (less than or equal) with "_leq".
 102
 103 @item
 104 Replace @code{>=} (greater than or equal) with "_geq".
 105
 106 @item
 107 Replace @code{<} (less than) with "_less".
 108
 109 @item
 110 Replace @code{>} (greater than) with "_gr".
 111
 112 @item
 113 Replace @code{@@} with "at". [Omit?]
 114
 115 @item
 116 Prefix with "gh_" (or "scm_" if you are ignoring the gh interface).
 117
 118 @item
 119 [Anything else?  --ttn, 2000/01/16 15:17:28]
 120
 121 @end itemize
 122
 123 Here is an Emacs Lisp command that prompts for a Scheme function name and
 124 inserts the corresponding C function name into the buffer.
 125
 126 @example
 127 (defun insert-scheme-to-C (name &optional use-gh)
 128   "Transforms Scheme NAME, a string, to its C counterpart, and inserts it.
 129 Prefix arg non-nil means use \"gh_\" prefix, otherwise use \"scm_\" prefix."
 130   (interactive "sScheme name: \nP")
 131   (let ((transforms '(("-"  . "_")
 132                       ("?"  . "_p")
 133                       ("!"  . "_x")
 134                       ("->" . "_to_")
 135                       ("<=" . "_leq")
 136                       (">=" . "_geq")
 137                       ("<"  . "_less")
 138                       (">"  . "_gr")
 139                       ("@@"  . "at"))))
 140     (while transforms
 141       (let ((trigger (concat "\\(.*\\)"
 142                              (regexp-quote (caar transforms))
 143                              "\\(.*\\)"))
 144             (sub (cdar transforms))
 145             (m nil))
 146         (while (setq m (string-match trigger name))
 147           (setq name (concat (match-string 1 name)
 148                              sub
 149                              (match-string 2 name)))))
 150       (setq transforms (cdr transforms))))
 151   (insert (if use-gh "gh_" "scm_") name))
 152 @end example
 153
 154
 155 @node Structuring argument lists for C functions
 156 @subsection Structuring argument lists for C functions
 157
 158 The C function's arguments will be all of the Scheme procedure's
 159 arguments, both required and optional; if the Scheme procedure takes a
 160 ``rest'' argument, that will be a final argument to the C function.  The
 161 C function's arguments, as well as its return type, will be @code{SCM}.
 162
 163
 164 @node C Only
 165 @section Elements Available Only in C
 166
 167 For C this is usually a matter of better performance (e.g. the
 168 @code{SCM_CONSP} macro) or of accepting C language types rather than the
 169 generic @code{SCM}.
 170
 171
 172 @node Scheme Only
 173 @section Elements Available Only in Scheme
 174
 175
 176 @node Reference Layout
 177 @section Reference Material Layout
 178
 179 This part of the reference manual documents all of Guile's core
 180 Scheme-level language and features in functionally-related groups.
 181 Where a particular section of the manual includes both R5RS-compliant
 182 parts and Guile-specific extensions, the text indicates which parts of
 183 the documentation describe R5RS behaviour and which parts describe Guile
 184 extensions.
 185
 186 For a quick way of identifying the parts of Guile that implement
 187 R5RS-compliant features, see the R5RS index: @ref{R5RS Index}.