doc/ref/api-overview.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 @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,
 110 types are therefore often omitted but for the return value and for the
 111 arguments.