summaryrefslogtreecommitdiff
path: root/doc/ref/scm.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/scm.texi')
-rw-r--r--doc/ref/scm.texi215
1 files changed, 70 insertions, 145 deletions
diff --git a/doc/ref/scm.texi b/doc/ref/scm.texi
index fb1dc8955..c0e386c05 100644
--- a/doc/ref/scm.texi
+++ b/doc/ref/scm.texi
@@ -6,79 +6,21 @@
@page
@node API Overview
-@chapter Overview of the Guile API
+@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. Broadly speaking, the
-interface as a whole can be divided into three groups.
+syntax or other types of object in Scheme.
-@enumerate
-@item
-Elements that are available equivalently as C functions or Scheme
-procedures.
-
-@item
-Elements that are only available as macros, functions or variables for C
-programming.
-
-@item
-Elements that are only available as procedures or other objects in
-Scheme.
-@end enumerate
-
-Functions/procedures in the first group are often known as
-@dfn{primitives}, @dfn{subrs} or @dfn{builtins}. An example is the
-@code{assq} Scheme procedure, which is also available as @code{scm_assq}
-in C.
-
-Elements in the second and third groups exist because they provide
-additional language-specific benefits in either Scheme or C. Examples
-are the C macro @code{SCM_CONSP}, which is faster and more convenient in
-C programming than the primitive @code{scm_pair_p}, and the
-procedure-with-setter @code{make-object-property}, which provides a
-more convenient property handling interface in Scheme than the
-primitives on which it is based.
-
-@menu
-* Primitives:: Identical function for Scheme and C.
-* C Only:: Elements only available in C.
-* Scheme Only:: Elements only available in Scheme.
-* Reference Layout:: The layout of this part of the manual.
-@end menu
-
-
-@node Primitives
-@section Identical Function in both Scheme and C
-
-They form the majority of the API, and allow both C and Scheme
-programmers to perform identical operations.
+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.
-@c @node Scheme Primitives
-@c @chapter Writing Scheme primitives in C
-@c - according to the menu in guile.texi - NJ 2001/1/26
-@c @chapter Relationship between Scheme and C functions
-
-@c Chapter contents contributed by Thien-Thi Nguyen <ttn@gnu.org>.
-
-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
-@subsection Transforming Scheme name to C name
+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:
@@ -89,99 +31,82 @@ using some simple textual transformations:
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_".
+Replace @code{?} (question mark) with @code{_p}.
@item
-Replace @code{<=} (less than or equal) with "_leq".
+Replace @code{!} (exclamation point) with @code{_x}.
@item
-Replace @code{>=} (greater than or equal) with "_geq".
+Replace internal @code{->} with @code{_to_}.
@item
-Replace @code{<} (less than) with "_less".
+Replace @code{<=} (less than or equal) with @code{_leq}.
@item
-Replace @code{>} (greater than) with "_gr".
+Replace @code{>=} (greater than or equal) with @code{_geq}.
@item
-Replace @code{@@} with "at". [Omit?]
+Replace @code{<} (less than) with @code{_less}.
@item
-Prefix with "gh_" (or "scm_" if you are ignoring the gh interface).
+Replace @code{>} (greater than) with @code{gr}.
@item
-[Anything else? --ttn, 2000/01/16 15:17:28]
+Prefix with @code{scm_}.
@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
-@subsection 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}.
-
-
-@node C Only
-@section Elements Available Only in C
-
-For C this is usually a matter of better performance (e.g. the
-@code{SCM_CONSP} macro) or of accepting C language types rather than the
-generic @code{SCM}.
-
-
-@node Scheme Only
-@section Elements Available Only in Scheme
-
-
-@node Reference Layout
-@section Reference Material Layout
-
-This part of the reference manual documents all of Guile's core
-Scheme-level language and features in functionally-related groups.
-Where a particular section of the manual includes both R5RS-compliant
-parts and Guile-specific extensions, the text indicates which parts of
-the documentation describe R5RS behaviour and which parts describe Guile
-extensions.
-
-For a quick way of identifying the parts of Guile that implement
-R5RS-compliant features, see the R5RS index: @ref{R5RS Index}.
+@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.