5 This reference manual documents Guile, GNU's Ubiquitous Intelligent
6 Language for Extensions. It describes how to use Guile in many useful
9 This is edition @value{MANUAL_EDITION} of the reference manual, and
10 corresponds to Guile version @value{VERSION}.
15 @section The Guile License
20 @chapter The Guile License
23 The license of Guile consists of the GNU GPL plus a special statement
24 giving blanket permission to link with non-free software. This is the
25 license statement as found in any individual file that it applies to:
28 This program is free software; you can redistribute it and/or modify it
29 under the terms of the GNU General Public License as published by the
30 Free Software Foundation; either version 2, or (at your option) any
33 This program is distributed in the hope that it will be useful, but
34 WITHOUT ANY WARRANTY; without even the implied warranty of
35 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
36 General Public License for more details.
38 You should have received a copy of the GNU General Public License along
39 with this software; see the file COPYING. If not, write to the Free
40 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
43 As a special exception, the Free Software Foundation gives permission
44 for additional uses of the text contained in its release of GUILE.
46 The exception is that, if you link the GUILE library with other files to
47 produce an executable, this does not by itself cause the resulting
48 executable to be covered by the GNU General Public License. Your use of
49 that executable is in no way restricted on account of linking the GUILE
52 This exception does not however invalidate any other reasons why the
53 executable file might be covered by the GNU General Public License.
55 This exception applies only to the code released by the Free Software
56 Foundation under the name GUILE. If you copy code from other Free
57 Software Foundation releases into a copy of GUILE, as the General Public
58 License permits, the exception does not apply to the code that you add
59 in this way. To avoid misleading anyone as to the status of such
60 modified files, you must delete this exception notice from them.
62 If you write modifications of your own for GUILE, it is your choice
63 whether to permit this exception to apply to your modifications. If you
64 do not wish that, delete this exception notice.
69 @section Layout of this Manual
74 @chapter Layout of this Manual
77 The manual is divided into three parts.
79 @strong{Part I: Introduction to Guile} provides an overview of what
80 Guile is and how you can use it. A whirlwind tour shows how Guile can
81 be used interactively and as a script interpreter, how to link Guile
82 into your own applications, and how to write modules of interpreted and
83 compiled code for use with Guile. Everything introduced here is
84 documented again and in full by the later parts of the manual. This
85 part also explains how to obtain and install new versions of Guile, and
86 how to report bugs effectively.
88 @strong{Part II: Programming with Guile} documents all aspects of
89 practical programming using Guile. This covers both the Scheme level
90 --- where we provide an introduction to the key ideas of the Scheme
91 language --- and use of Guile's @code{scm} interface to write new
92 primitives and objects in C, and to incorporate Guile into a C
93 application. It also covers the use of Guile as a POSIX compliant
94 script interpreter, and how to use the Guile debugger.
96 @c @strong{Part V: Extending Applications Using Guile} explains the options
97 @c available for using Guile as a application extension language. At the
98 @c simpler end of the scale, an application might use Guile to define some
99 @c application-specific primitives in C and then load an application Scheme
100 @c file. In this case most of the application code is written on the
101 @c Scheme level, and uses the application-specific primitives as an
102 @c extension to standard Scheme. At the other end of the scale, an
103 @c application might be predominantly written in C --- with its main
104 @c control loop implemented in C --- but make occasional forays into Scheme
105 @c to, say, read configuration data or run user-defined customization code.
106 @c This part of the manual covers the complete range of application
107 @c extension options.
109 @strong{Part III: Guile API Reference} documents Guile's core API. Most
110 of the variables and procedures in Guile's core programming interface
111 are available in both Scheme and C, and are related systematically such
112 that the C interface can be inferred from the Scheme interface and vice
113 versa. Therefore this part of the manual documents the Guile API in
114 functionality-based groups with the Scheme and C interfaces presented
115 side by side. Where the Scheme and C interfaces for a particular
116 functional area do differ --- which is sometimes inevitable, given the
117 differences in the structure of the two languages --- this is pointed
118 out and explained. In all cases the overriding principle is that all
119 the reference documentation for a given functional area is grouped
122 @c the core Scheme language and features that Guile implements. Although
123 @c the basis for this is the Scheme language described in R5RS, this part
124 @c of the manual does not assume any prior familiarity with R5RS in
125 @c particular, or with Scheme in general. Basic Scheme concepts, standard
126 @c aspects of the Scheme language and Guile extensions on top of R5RS are
127 @c all documented from scratch, and organized by functionality rather than
128 @c by the defining standards.
130 @strong{Part IV: Guile Modules} describes some important modules,
131 distributed as part of the Guile distribution, that extend the
132 functionality provided by the Guile Scheme core. Two important examples
137 the POSIX module, which provides Scheme level procedures for system and
138 network programming that conform to the POSIX standard
141 the SLIB module, which makes Aubrey Jaffer's portable Scheme library
142 available for use in Guile.
147 @section Manual Conventions
151 @node Manual Conventions
152 @chapter Conventions used in this Manual
155 We use some conventions in this manual.
160 For some procedures, notably type predicates, we use @dfn{iff} to
161 mean `if and only if'. The construct is usually something like:
162 `Return @var{val} iff @var{condition}', where @var{val} is usually
163 `@code{#t}' or `non-@code{#f}'. This typically means that @var{val}
164 is returned if @var{condition} holds, and that @samp{#f} is returned
169 In examples and procedure descriptions and all other places where the
170 evaluation of Scheme expression is shown, we use some notation for
171 denoting the output and evaluation results of expressions.
173 The symbol @code{@result{}} is used to tell which value is returned by
182 Some procedures produce some output besides returning a value. This
183 is denoted by the symbol @code{@print{}}.
186 (begin (display 1) (newline) 'hooray)
192 @c Add other conventions here.
198 @c TeX-master: "guile.texi"