mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-10 22:10:21 +02:00
Code Activity

* Various small manual improvements.

Browse source
This commit is contained in:
Neil Jerram 2001-12-07 17:08:19 +00:00
parent de513fa003
commit a7a7bb95eb
6 changed files with 131 additions and 55 deletions
Download patch file Download diff file Expand all files Collapse all files

13
doc/ref/ChangeLog
View file

@ -1,3 +1,16 @@
2001-12-07 Neil Jerram <neil@ossau.uklinux.net>
* scm.texi (Guile API): Renamed from `Scheme Primitives' and
broadened so that this chapter discusses the Guile API as a whole.
* program.texi (Available Functionality): Revise so that text
reads better.
* guile.texi (Programming Intro): New introductory text.
* scheme-ideas.texi (Definition): Reorder reference bullets in
ascending page number order.
2001-12-04 Martin Grabmueller <mg@glug.org>
* scheme-procedures.texi (Optional Arguments): Typo fix: wither ->

11
doc/ref/guile.texi
View file

@ -94,7 +94,7 @@ by the Free Software Foundation.
@sp 10
@comment The title is printed in a large font.
@title Guile Reference Manual
@subtitle $Id: guile.texi,v 1.8 2001-12-01 21:48:30 ossau Exp $
@subtitle $Id: guile.texi,v 1.9 2001-12-07 17:08:19 ossau Exp $
@subtitle For use with Guile @value{VERSION}
@c AUTHORS
@ -216,7 +216,7 @@ Part II: Programming with Guile
* Guile Scripting:: How to write Guile scripts.
* Command Line Handling:: Command line options and arguments.
* Libguile Intro:: Using Guile as an extension language.
* Scheme Primitives:: Writing Scheme primitives in C.
* Guile API:: Overview of the Guile API.
* Data Representation:: Data representation in Guile.
* GH:: The deprecated GH interface.
* Debugger User Interface::
@ -285,7 +285,7 @@ guidelines and tips for @emph{how} to program in Guile, and to document
the tools that are available to help you with your programming. For
detailed reference information on the variables, functions etc. that
make up Guile's application programming interface (API), please refer to
Part III (@pxref{Reference Intro,,Part III: Programming with Guile}).
Part III (@pxref{Reference Intro,,Part III --- Guile API Reference}).
We begin in the first chapter of this part by looking at the programming
options available.
@ -306,6 +306,11 @@ options available.
@node Reference Intro
@unnumbered Part III: Guile API Reference
Guile provides an application programming interface (@dfn{API}) to
developers in two core languages: Scheme and C. This part of the manual
contains reference documentation for all of the functionality that is
available through both Scheme and C interfaces.
@include scheme-data.texi
@include scheme-compound.texi
@include scheme-procedures.texi

4
doc/ref/intro.texi
View file

@ -1,4 +1,4 @@
@c $Id: intro.texi,v 1.4 2001-11-16 15:04:16 ossau Exp $
@c $Id: intro.texi,v 1.5 2001-12-07 17:08:19 ossau Exp $
@page
@ -352,7 +352,7 @@ with Guile on a typical POSIX system.
Parts III and IV of this manual describe the C functions Guile provides.
Furthermore, any Scheme function described in this manual as a
``Primitive'' is also callable from C; see @ref{Scheme Primitives}.
``Primitive'' is also callable from C; see @ref{Primitives}.
The header file @code{<libguile.h>} provides declarations for all of
Guile's functions and constants. You should @code{#include} it at the

28
doc/ref/program.texi
View file

@ -83,24 +83,18 @@ is growing quickly and already includes such useful examples as
Scheme, and @code{(database postgres)}, which provides SQL access to a
Postgres database.
In practice, therefore, it is quite feasible that your application can
be implemented by combining together a selection of pre-existing modules
with new application code written in Scheme, and approach may
suffice for the application that you want to write.
Given the growing collection of pre-existing modules, it is quite
feasible that your application could be implemented by combining a
selection of these modules together with new application code written in
Scheme.
If it does not suffice, because the functionality that your application
needs is not already available in this form (and assuming that it's
impossible or unacceptable for performance reasons to write the new
functionality in Scheme), you will need to write some C code.
@itemize @bullet
@item
If the required function is already written (e.g. in a library), you
only need a little glue to connect it to the world of Guile.
@item
If not, you need to write the basic code as well.
@end itemize
If this approach is not enough, because the functionality that your
application needs is not already available in this form, or because it
is impossible or unacceptable (e.g. for performance reasons) to write
the new functionality in Scheme, you will need to write some C code. If
the required function is already available in C (e.g. in a library), all
you need is a little glue to connect it to the world of Guile. If not,
you need both to write the basic code and to plumb it into Guile.
In either case, two general considerations are important. Firstly, what
is the interface by which the functionality is presented to the Scheme

59
doc/ref/scheme-ideas.texi
View file

@ -177,12 +177,6 @@ about those missing pieces immediately by jumping ahead to the following
references.
@itemize @bullet
@item
@xref{Internal Definitions}, to read about using @code{define} other
than at top level in a Scheme program, including a discussion of when it
works to use @code{define} rather than @code{set!} to change the value
of an existing variable.
@item
@ref{Lambda Alternatives}, to read about an alternative form of the
@code{define} syntax that can be used when defining new procedures.
@ -191,6 +185,12 @@ of an existing variable.
@ref{Procedures with Setters}, to read about an alternative form of the
@code{set!} syntax that helps with changing a single value in the depths
of a compound data structure.)
@item
@xref{Internal Definitions}, to read about using @code{define} other
than at top level in a Scheme program, including a discussion of when it
works to use @code{define} rather than @code{set!} to change the value
of an existing variable.
@end itemize
@ -384,7 +384,7 @@ this:
@end lisp
@noindent
This is a valid procedure invocation expression, whose result is the
This is a valid procedure invocation expression, and its result is the
string @code{"Name=FSF:Address=Cambridge"}.
It it more common, though, to store the procedure value in a variable ---
@ -756,9 +756,9 @@ answers yes.
If the outermost @code{(if @dots{})} expression here was a procedure
invocation expression, the expression @code{(delete-file file)}, whose
effect is to actually delete a file, would already have been executed
before the @code{if} procedure even got invoked! Clearly this is no use
--- the whole point of an @code{if} expression is that the
side effect is to actually delete a file, would already have been
evaluated before the @code{if} procedure even got invoked! Clearly this
is no use --- the whole point of an @code{if} expression is that the
@dfn{consequent} expression is only evaluated if the condition of the
@code{if} expression is ``true''.
@ -815,21 +815,14 @@ expressions, simply so that you will recognize common special syntax
when you see it. For a full description of each of these syntaxes,
follow the appropriate reference.
@code{if} and @code{cond} (@pxref{if cond case}) provide conditional
evaluation of argument expressions depending on whether one or more
conditions evaluate to ``true'' or ``false''.
@code{case} (@pxref{if cond case}) provides conditional evaluation of
argument expressions depending on whether a variable has one of a
specified group of values.
@code{define} (REFFIXME) is used to create a new variable and set its
initial value.
@code{set!} (REFFIXME) is used to modify an existing variable's value.
@code{lambda} (@pxref{Lambda}) is used to construct procedure objects.
@code{define} (@pxref{Top Level}) is used to create a new variable and
set its initial value.
@code{set!} (@pxref{Top Level}) is used to modify an existing variable's
value.
@code{let}, @code{let*} and @code{letrec} (@pxref{Local Bindings})
create an inner lexical environment for the evaluation of a sequence of
expressions, in which a specified set of local variables is bound to the
@ -842,6 +835,14 @@ same as a procedure which returns its last argument, because the
evaluation of a procedure invocation expression does not guarantee to
evaluate the arguments in order.
@code{if} and @code{cond} (@pxref{if cond case}) provide conditional
evaluation of argument expressions depending on whether one or more
conditions evaluate to ``true'' or ``false''.
@code{case} (@pxref{if cond case}) provides conditional evaluation of
argument expressions depending on whether a variable has one of a
specified group of values.
@code{and} (@pxref{and or}) executes a sequence of expressions in order
until either there are no expressions left, or one of them evaluates to
``false''.
@ -1312,12 +1313,12 @@ It can only be accessed indirectly via @code{get-balance} or
-25
@end lisp
A detail here is that the @code{get-balance} and @code{deposit}
variables must be set up by @code{define}ing them at top level and then
@code{set!}ing their values inside the @code{let} body. Using
@code{define} within the @code{let} body would not work: this would
create variable bindings within the local @code{let} environment that
would not be accessible at top level.
An important detail here is that the @code{get-balance} and
@code{deposit} variables must be set up by @code{define}ing them at top
level and then @code{set!}ing their values inside the @code{let} body.
Using @code{define} within the @code{let} body would not work: this
would create variable bindings within the local @code{let} environment
that would not be accessible at top level.
@node Callback Closure

71
doc/ref/scm.texi
View file

@ -1,8 +1,58 @@
@page
@node Scheme Primitives
@node Guile API
@chapter 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.
@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.
@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.
@c @node Scheme Primitives
@c @chapter Writing Scheme primitives in C
@c - according to the menu in guile.texi - NJ 2001/1/26
@chapter Relationship between Scheme and C functions
@c @chapter Relationship between Scheme and C functions
@c Chapter contents contributed by Thien-Thi Nguyen <ttn@gnu.org>.
@ -19,8 +69,9 @@ the convention for passing non-required arguments to this function.
@c * Exceptions to the regularity::
@end menu
@node Transforming Scheme name to C name
@section Transforming Scheme name to C name
@subsection Transforming Scheme name to C name
Normally, the name of a C function can be derived given its Scheme name,
using some simple textual transformations:
@ -93,11 +144,23 @@ Prefix arg non-nil means use \"gh_\" prefix, otherwise use \"scm_\" prefix."
(insert (if use-gh "gh_" "scm_") name))
@end example
@node Structuring argument lists for C functions
@section 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
argumements, 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