4 Guile is an interpreter for Scheme, a clean, economical programming
5 language in the Lisp family. You can invoke Guile from the shell to
6 evaluate Scheme expressions interactively, or use it as an interpreter
7 for script files. However, Guile is also packaged as a library, to be
8 embedded as an extension language into other applications. The
9 application can supplement the base language with special-purpose
10 functions and datatypes, allowing the user to customize and extend it by
13 In its simplest form, Guile is an ordinary interpreter. The
14 @code{guile} program can read and evaluate Scheme expressions entered
15 from the terminal. Here is a sample interaction between Guile and a
16 user; the user's input appears after the @code{$} and @code{guile>}
21 guile> (+ 1 2 3) ; add some numbers
23 guile> (define (factorial n) ; define a function
24 (if (zero? n) 1 (* n (factorial (- n 1)))))
27 guile> (getpwnam "jimb") ; find my entry in /etc/passwd
28 #("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
29 "/usr/local/bin/bash")
34 Guile can also interpret script files. For example, here is a Guile script
35 containing a script which displays the
39 supplement the base language with its own functions, datatypes and
40 syntax, allowing the user to extend and
46 application the Guile interpreter to allow
50 applications to incorporate the Scheme interpreter for customization
53 [[script interpreter]]
57 The concept of an extension language library does not originate with
58 Guile. However, Guile is the first to offer users a choice of languages
62 Guile currently supports Scheme and Ctax , and we expect to support Emacs Lisp in the near future.
65 Scheme is powerful enough that other languages can be
66 conveniently translated into it,
68 However, unlike other extension packages, Guile gives users a choice of
69 languages to program in. Guile can
72 In this sense, Guile resembles the Tcl and Python packages, providing
73 both an ordinary interpreter and an extension language library.
74 However, unlike those packages, Guile supports more than one programming
78 write Scheme code to control and customize applications which
81 , adding their own functions,
82 datatypes, and syntax, to allow the user to programm
85 link it into your own programs to make them
89 Guile is a library containing an interpreter for Scheme, a complete but
90 economical programming language, which the developer can customize to
91 suit the application at hand by adding new functions, data types, and
92 control structures. These may be implemented in C, and then
93 ``exported'' for use by the interpreted code. Because Guile already
94 provides a full-featured interpreter, the developer need not neglect the
95 language's design in order to concentrate on code relevant to the task.
96 In this way, Guile provides a framework for the construction of
97 domain-specific languages.
99 Guile provides first-class functions, a rich set of data types,
100 exception handling, a module system, and a powerful macro facility.
101 Guile also supports dynamic linking and direct access to Unix system
102 calls. Releases in the near future will support a source-level
103 debugger and bindings for the Tk user interface toolkit.
107 Guile is a framework for writing applications controlled by specialized
108 languages. In its simplest form, Guile is an interpreter for Scheme, a
109 clean, economical programming language in the Lisp family. However,
110 Guile is packaged as a library, allowing applications to link against it
111 and use Scheme as their extension language. The application can add
112 primitive functions to the language, implement new data types, and even
113 adjust the language's syntax.
117 [the introduction is probably not what Jim has in mind; I just took the
118 one I had in earlier, since the file had the same name intro.texi]
120 Guile is an implementation of the Scheme programming language, but, like
121 other modern implementations of Scheme, it adds many features that the
122 community of Scheme programmers considers necessary for an ``industrial
125 Examples of extensions to Scheme are the module system
126 (@pxref{Modules}), the Unix system programming tools (@pxref{POSIX
127 system calls and networking} and @pxref{The Scheme shell (scsh)}), an
128 interface to @emph{libtool} to make it easier to add C libraries as
129 primitives (@pxref{Linking Guile with your code}), and (FIXME add more).
131 On top of these extensions, which many other Scheme implementations
132 provide, Guile also offers the possibility of writing routines in other
133 languages and running them simultaneously with Scheme. The desire to
134 implement other languages (in particular Emacs Lisp) on top of Scheme is
135 responsible for Guile's only deviation from the R4RS @footnote{R4RS is
136 the Revised^4 Report on the Algorithmic Language Scheme, the closest
137 thing to a standard Scheme specification today} Scheme standard
138 (@cite{r4rs}): Guile is case sensitive, whereas ``standard'' Scheme is
141 But even more fundamentally, Guile is meant to be an @emph{embeddable}
142 Scheme interpreter. This means that a lot of work has gone into
143 packaging the interpreter as a C library (@pxref{A Portable C to Scheme Interface} and @pxref{Scheme data representation}).
145 This reference manual is mainly driven by the need to document all the
146 features that go beyond standard Scheme.
150 * Guile feature list::
151 * What you need to use Guile::
152 * Roadmap to the Manual::
153 * Motivation for Guile::
157 @node Getting started
158 @section Getting started
160 We assume that you know how to program in Scheme, although we do not
161 assume advanced knowledge. If you don't know Scheme, there are many
162 good books on Scheme at all levels, and the Guile Tutorial might give
163 you a good enough feel for the language. We also assume that you know
164 how to program in C, since there will be many examples of how to program
165 in C using Guile as a library.
167 Many diverse topics from the world of Unix hacking will be covered here,
168 such as shared libraries, socket programming, garbage collection, and so
169 forth. If at any time you feel you don't have enough background on a
170 given topic, just go up a level or two in the manual, and you will find
171 that the chapter begins with a few paragraphs that introduce the topic.
172 If you are still lost, read through the Guile tutorial and then come
173 back to this reference manual.
175 To run the core Guile interpreter and extension library you need no more
176 than a basically configured GNU/Unix system and the Guile sources. You
177 should download and install the Guile sources (@pxref{Obtaining and
181 @node Guile feature list
182 @section Guile feature list
184 In a reductionist view, Guile could be regarded as:
187 An R4RS-compliant Scheme interpreter.
190 Some Scheme features that go beyond the R4RS standard, notably a module
191 system, exception handling primitives and an interface to Aubrey
195 A symbolic debugger for Scheme, and gdb extensions to facilitate
196 debugging libguile programs.
199 An embeddable version of the same interpreter, called @emph{libguile}.
202 A portable high level API on top of libguile (the @code{gh_} interface).
205 A collection of bundled C libraries with a Guile API. As we write, this
210 a regular expression library.
213 a low-level interface to the POSIX system calls, socket library
214 and other Unix system services.
217 an interface to John Ousterhout's Tk toolkit.
222 A set of tools for implementing other languages @emph{on top of Scheme},
223 and an example implementation of a language called @emph{Ctax}.
229 @node What you need to use Guile
230 @section What you need to use Guile
233 @node Roadmap to the Manual
234 @section Roadmap to the Manual
236 @node Motivation for Guile
237 @section Motivation for Guile
239 @node History of Guile
240 @section History of Guile
246 [I think that this might go in the appendix in Jim's view of the manual]
250 @appendix Invoking Guile
251 --- mentions read-eval-print loops
252 --- both the SCSH and GAWK manuals relegate invocation details
253 to an appendix. We can give examples in the introduction.
258 Display a helpful message.
261 Display the current version.
263 To be used for emacs editing support.
265 Process @var{file} as a script then quit. This is a terminating option:
266 any further command line arguments can be accessed by the script using
267 the @code{(program-arguments)} procedure.
269 An executable script can start with the following:
276 Note the @code{!#} token on the second line. It is very important
277 to include this token when writing Guile scripts. Guile and SCSH,
278 the Scheme shell, share the convention that @code{#!} and
279 @code{!#} may be used to mark block comments (@pxref{Block
280 comments and interpreter triggers}). If the closing @code{!#}
281 token is not included, then Guile will consider the block comment
282 to be unclosed, and the script will probably not compile
285 It is also important to include the @samp{-s} option at the
286 beginning of the Guile script, so that Guile knows not to behave
287 in an interactive fashion.