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