diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index d77e48653..69b8a4847 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -1,3 +1,16 @@ +2001-12-07 Neil Jerram + + * 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 * scheme-procedures.texi (Optional Arguments): Typo fix: wither -> diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index ca21c17c2..7761cffb7 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -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 diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi index 09da686c6..8b786fe47 100644 --- a/doc/ref/intro.texi +++ b/doc/ref/intro.texi @@ -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{} provides declarations for all of Guile's functions and constants. You should @code{#include} it at the diff --git a/doc/ref/program.texi b/doc/ref/program.texi index e9c3dccd4..4f5ff2e1d 100644 --- a/doc/ref/program.texi +++ b/doc/ref/program.texi @@ -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 diff --git a/doc/ref/scheme-ideas.texi b/doc/ref/scheme-ideas.texi index 7de9d9376..3ef2afe32 100644 --- a/doc/ref/scheme-ideas.texi +++ b/doc/ref/scheme-ideas.texi @@ -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 diff --git a/doc/ref/scm.texi b/doc/ref/scm.texi index 948823afb..5e5e521bd 100644 --- a/doc/ref/scm.texi +++ b/doc/ref/scm.texi @@ -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 . @@ -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