summaryrefslogtreecommitdiff
path: root/doc/ref/api-overview.texi
diff options
context:
space:
mode:
authorMarius Vollmer <mvo@zagadka.de>2004-08-02 12:29:00 +0000
committerMarius Vollmer <mvo@zagadka.de>2004-08-02 12:29:00 +0000
commit07d83abe7b8b617e4bb70a08efc0c0f6999fa0cc (patch)
tree34c8a7b9d98000169379038be8551ed44c0bdb83 /doc/ref/api-overview.texi
parent237be238424f1b6d130799ad931ba6fa8504a97c (diff)
downloadguile-07d83abe7b8b617e4bb70a08efc0c0f6999fa0cc.tar.gz
* scheme-binding.texi: Renamed to api-binding.texi.
* scheme-compound.texi: Renamed to api-compound.texi. * scheme-control.texi: Renamed to api-control.texi. * scheme-data.texi: Renamed to api-data.texi. * scheme-debug.texi: Renamed to api-debug.texi. * deprecated.texi: Renamed to api-deprecated.texi. * scheme-evaluation.texi: Renamed to api-evaluation.texi. * ref-init.texi: Renamed to api-init.texi. * scheme-io.texi: Renamed to api-io.texi. * scheme-memory.texi: Renamed to api-memory.texi. * scheme-modules.texi: Renamed to api-modules.texi. * scheme-options.texi: Renamed to api-options.texi. * scm.texi: Renamed to api-overview.texi. * scheme-procedures.texi: Renamed to api-procedures.texi. * scheme-scheduling.texi: Renamed to api-scheduling.texi. * scheme-scm.texi: Renamed to api-scm.texi. * scheme-smobs.texi: Renamed to api-smobs.texi. * scheme-snarf.texi: Renamed to api-snarf.texi. * scheme-translation.texi: Renamed to api-translation.texi. * scheme-utility.texi: Renamed to api-utility.texi. * debugging.texi: Renamed to scheme-debugging.texi. * scripts.texi: Renamed to scheme-scripts.texi. * program.texi: Renamed to libguile-program.texi.
Diffstat (limited to 'doc/ref/api-overview.texi')
-rw-r--r--doc/ref/api-overview.texi112
1 files changed, 112 insertions, 0 deletions
diff --git a/doc/ref/api-overview.texi b/doc/ref/api-overview.texi
new file mode 100644
index 000000000..48378895e
--- /dev/null
+++ b/doc/ref/api-overview.texi
@@ -0,0 +1,112 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@page
+@node API Overview
+@section Overview of the Guile API
+
+Guile's application programming interface (@dfn{API}) makes
+functionality available that an application developer can use in either
+C or Scheme programming. The interface consists of @dfn{elements} that
+may be macros, functions or variables in C, and procedures, variables,
+syntax or other types of object in Scheme.
+
+Many elements are available to both Scheme and C, in a form that is
+appropriate. For example, the @code{assq} Scheme procedure is also
+available as @code{scm_assq} to C code. These elements are documented
+only once, addressing both the Scheme and C aspects of them.
+
+The Scheme name of an element is related to its C name in a regular
+way. Also, a C function takes its parameters in a systematic way.
+
+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 @code{_p}.
+
+@item
+Replace @code{!} (exclamation point) with @code{_x}.
+
+@item
+Replace internal @code{->} with @code{_to_}.
+
+@item
+Replace @code{<=} (less than or equal) with @code{_leq}.
+
+@item
+Replace @code{>=} (greater than or equal) with @code{_geq}.
+
+@item
+Replace @code{<} (less than) with @code{_less}.
+
+@item
+Replace @code{>} (greater than) with @code{_gr}.
+
+@item
+Prefix with @code{scm_}.
+
+@end itemize
+
+@c Here is an Emacs Lisp command that prompts for a Scheme function name and
+@c inserts the corresponding C function name into the buffer.
+
+@c @example
+@c (defun insert-scheme-to-C (name &optional use-gh)
+@c "Transforms Scheme NAME, a string, to its C counterpart, and inserts it.
+@c Prefix arg non-nil means use \"gh_\" prefix, otherwise use \"scm_\" prefix."
+@c (interactive "sScheme name: \nP")
+@c (let ((transforms '(("-" . "_")
+@c ("?" . "_p")
+@c ("!" . "_x")
+@c ("->" . "_to_")
+@c ("<=" . "_leq")
+@c (">=" . "_geq")
+@c ("<" . "_less")
+@c (">" . "_gr")
+@c ("@@" . "at"))))
+@c (while transforms
+@c (let ((trigger (concat "\\(.*\\)"
+@c (regexp-quote (caar transforms))
+@c "\\(.*\\)"))
+@c (sub (cdar transforms))
+@c (m nil))
+@c (while (setq m (string-match trigger name))
+@c (setq name (concat (match-string 1 name)
+@c sub
+@c (match-string 2 name)))))
+@c (setq transforms (cdr transforms))))
+@c (insert (if use-gh "gh_" "scm_") name))
+@c @end example
+
+A C function always takes a fixed number of arguments of type
+@code{SCM}, even when the corresponding Scheme function takes a
+variable number.
+
+For some Scheme functions, some last arguments are optional; the
+corresponding C function must always be invoked with all optional
+arguments specified. To get the effect as if an argument has not been
+specified, pass @code{SCM_UNDEFINED} as its value. You can not do
+this for an argument in the middle; when one argument is
+@code{SCM_UNDEFINED} all the ones following it must be
+@code{SCM_UNDEFINED} as well.
+
+Some Scheme functions take an arbitrary number of @emph{rest}
+arguments; the corresponding C function must be invoked with a list of
+all these arguments. This list is always the last argument of the C
+function.
+
+These two variants can also be combined.
+
+The type of the return value of a C function that corresponds to a
+Scheme function is always @code{SCM}. In the descriptions below,
+types are therefore often omitted bot for the return value and for the
+arguments.