1 \input texinfo @c -*-texinfo-*-
3 @setfilename guile-tut.info
4 @settitle Guile Tutorial
9 @dircategory The Algorithmic Language Scheme
11 * Guile Tutorial: (guile-tut). The Guile tutorial.
14 @setchapternewpage off
15 @c Choices for setchapternewpage are {on,off,odd}.
21 @c DL: lose the egregious vertical whitespace, esp. around examples
22 @c but paras in @defun-like things don't have parindent
28 @subtitle For use with Guile @value{VERSION}
29 @subtitle Last updated @value{UPDATED}
32 @author Cygnus Solutions and Los Alamos National Laboratory
33 @author @email{rosalia@@nis.lanl.gov}
36 @vskip 0pt plus 1filll
37 Copyright @copyright{} 1997, 1998, 2004, 2006 Free Software Foundation
39 Permission is granted to make and distribute verbatim copies of
40 this manual provided the copyright notice and this permission notice
41 are preserved on all copies.
43 Permission is granted to copy and distribute modified versions of this
44 manual under the conditions for verbatim copying, provided that the entire
45 resulting derived work is distributed under the terms of a permission
46 notice identical to this one.
48 Permission is granted to copy and distribute translations of this manual
49 into another language, under the above conditions for modified versions,
50 except that this permission notice may be stated in a translation approved
61 This file gives a tutorial introduction to Guile.
63 Copyright (C) 1997, 2004, 2006 Free Software Foundation
65 Permission is granted to make and distribute verbatim copies of
66 this manual provided the copyright notice and this permission notice
67 are preserved on all copies.
70 Permission is granted to process this file through TeX and print the
71 results, provided the printed document carries copying permission
72 notice identical to this one except for the removal of this paragraph
73 (this paragraph not being relevant to the printed manual).
76 Permission is granted to copy and distribute modified versions of this
77 manual under the conditions for verbatim copying, provided that the entire
78 resulting derived work is distributed under the terms of a permission
79 notice identical to this one.
81 Permission is granted to copy and distribute translations of this manual
82 into another language, under the above conditions for modified versions,
83 except that this permission notice may be stated in a translation approved
91 * Using Guile to program in Scheme::
92 * Guile in a Library::
93 * Regular Expression Support::
94 * UNIX System Programming::
95 * Where to find more Guile/Scheme resources::
97 * Procedure and Macro Index::
107 Before giving an overview of Guile, I present some simple commands and
108 programs that you can type to get going immediately.
110 Start by invoking the Guile interpreter. Usually you do this by just
111 typing @code{guile}. Then type (or paste) the following expressions at
112 the prompt; the interpreter's response is preceded (in this manual) by
121 (define (recursive-factorial n)
124 (* n (recursive-factorial (- n 1)))))
125 (recursive-factorial 5)
130 In this example we did some simple arithmetic @code{(+ 20 35)} and got
131 the answer @code{55}. Then we coded the classic (and rather wasteful)
132 factorial algorithm and computed the factorial of @code{55}. Finally we
133 quit with @code{(quit)}.
136 We can find out about some of Scheme's nice features by asking for the
137 factorial of some big number, say @code{500}. On some systems the
138 correct answer will be returned (I do not indicate calling and leaving
139 the guile session anymore).
142 (recursive-factorial 500)
143 @result{} 1220136825991110068701238785423046926253574342803192842192413588
144 3858453731538819976054964475022032818630136164771482035841633787
145 2207817720048078520515932928547790757193933060377296085908627042
146 9174547882424912726344305670173270769461062802310452644218878789
147 4657547771498634943677810376442740338273653974713864778784954384
148 8959553753799042324106127132698432774571554630997720278101456108
149 1188373709531016356324432987029563896628911658974769572087926928
150 8712817800702651745077684107196243903943225364226052349458501299
151 1857150124870696156814162535905669342381300885624924689156412677
152 5654481886506593847951775360894005745238940335798476363944905313
153 0623237490664450488246650759467358620746379251842004593696929810
154 2226397195259719094521782333175693458150855233282076282002340262
155 6907898342451712006207714640979456116127629145951237229913340169
156 5523638509428855920187274337951730145863575708283557801587354327
157 6888868012039988238470215146760544540766353598417443048012893831
158 3896881639487469658817504506926365338175055478128640000000000000
159 0000000000000000000000000000000000000000000000000000000000000000
160 00000000000000000000000000000000000000000000000
163 The result is an example of Scheme's @emph{bignumbers}. However, there
164 are operating environments that provide (by default) too little stack
165 space. They will instead produce an error message like this:
168 (recursive-factorial 500)
170 ERROR: Stack overflow
171 ABORT: (stack-overflow)
174 Rather than enlarging the system's stack, we can implement the algorithm
175 such that it does not consume increasing stack space. This is called a
176 @emph{tail recursive} implementation. The following definition is tail
177 recursive and so should work on all systems.
180 (define (tail-recursive-factorial n)
183 (loop (- k 1) (* k l))))
186 (tail-recursive-factorial 500)
187 @result{} 1220136825991110068701238785423046926253574342803192842192413588
191 This is the most basic use of Guile: a simple Scheme interpreter. In
192 the rest of this tutorial I will show you how Guile has many facets: it
193 is also an @emph{extensible} interpreter (to which many features can be
194 easilly added) and an @emph{embeddable} interpreter (which can be
195 invoked from your C programs).
199 @chapter Introduction
202 @dfn{Guile} (which can stand for @emph{GNU Ubiquitous Intelligent
203 Language Extension}) is the GNU extension language. It started out as
204 an embeddable Scheme interpreter, and has rapidly evolved into a
205 kitchen-sink package including a standalone Scheme interpreter, an
206 embeddable Scheme interpreter, several graphics options, other languages
207 that can be used along with Scheme (for now just @emph{ctax} and
208 @emph{Tcl}), and hooks for much more.
212 * What are scripting and extension languages::
213 * History of Guile and its motivations::
214 * How to characterize Guile::
217 @node What are scripting and extension languages
218 @section What are scripting and extension languages
219 @cindex scripting languages
220 @cindex extension languages
222 A @dfn{scripting language} is a programming language which serves as
223 glue between other system programs. In the UNIX world, the traditional
224 scripting language is the @emph{Bourne shell}, which allows many UNIX
225 commands to be executed in sequence, or in a pipeline. Traditional UNIX
226 commands are cleverly written to work well when put together in a
229 Other examples of UNIX scripting languages are AWK, Perl, Scsh (the
230 Scheme Shell: a Scheme interpreter enhanced to do good scripting),
231 Python, Tcl, Java @dots{}
232 @cindex scripting languages - examples
234 UNIX programmers noticed, more than 25 years ago, that scripting
235 languages can do serious work, so the Bourne shell was written to have
236 variables, operators and control structures, just like a full-featured
237 programming language.
240 What scripting languages have, that traditional programming languages do
241 not, is the ability to easily run an external program (or a pipeline of
242 external programs) and use the returned values and output from that
243 program in useful ways.
245 An @dfn{extension language} is a programming language interpreter
246 offered by an application program, so that users can write macros or
247 even full-fledged programs to extend the original application.
248 Extension languages have a C interface (it is usually C, but it could be
249 any other compiled language), and can be given access to the C data
250 structures. Likewise, there are C routines to access the extension
251 language data structures.
253 Extension languages abound in the software world, even though the name
254 @emph{extension language} is seldom used. Examples are:
255 @cindex extension languages - examples
259 Emacs Lisp, the language used to program and customize GNU Emacs.
263 Tcl, John Ousterhout's general-purpose scripting and extension language.
267 The Lotus 1-2-3 macro language (any spreadsheet macro language,
268 really). I mention this one first because it is a classic, even though
269 it is seldom used any more.
273 Other spreadsheet and database macro languages.
276 The Dominion empire-style game's @emph{exec} files.
280 Any syntax for a ".*rc" file you might have used. Almost all programs
281 end up parsing some kind of startup or configuration file. The syntax
282 for those can get pretty involved, thus justifying calling them
283 "extension languages". The @emph{fvwm} window manager, for example,
284 parses a rather elaborate @file{.fvwmrc} file.
287 Brent Benson's libscheme.a, an embeddable Scheme interpreter.
288 @cindex Benson, Brent
292 Guile, the GNU extension language, which is the subject of this
297 One lesson we can learn from looking at classical large software
298 applications is that "writers of large programs" always end up throwing
299 in some kind of parser for configuration or scripting.
301 Of the examples listed above, Emacs Lisp, Tcl, Libscheme and Guile have
302 an important property: they are not added as an afterthought for a
303 specific application. They are general-purpose languages which a user
304 can learn (even in college courses) and then use to customize the
307 This is a recent and (in my opinion) very exciting direction in
308 large-program software engineering: program designers can link in the
309 Guile or Tcl library from the very beginning, and tell their users "You
310 want to customize this program? Just use Scheme (or Tcl, or whatever
311 language), which you already know!"
312 @cindex large programs
315 @node History of Guile and its motivations
316 @section History of Guile and its motivations
318 A few separate threads of events led to the development of Guile.
320 In the fall of 1994, Richard Stallman, director of the GNU project,
321 posted an article with the subject "Why you should not use Tcl", in
322 which he argued that Tcl is inadequate as an extension language. This
323 generated a flurry of flames (available in the hypermail archive
324 (@url{http://www.vanderburg.org/Tcl/war/}) @strong{The Tcl War}).
325 @cindex Stallman, Richard
329 The result was that Stallman then proposed his design for the GNU
330 Extension Language, first called GEL and then renamed Guile. The
331 discussion triggered by that article is also available in a hypermail
332 archive, @url{http://www.vanderburg.org/Tcl/war2/}.
334 One interesting feature of this GNU Extension Language plan was that
335 users should have a @emph{choice} of languages to use in extending their
336 program. The basic language would be a slightly modified Scheme, and
337 translators would be written to convert other languages (like Tcl,
338 Python, Perl, C-like languages @dots{}) into Scheme.
340 Tom Lord started working on this project immediately, taking Aubrey
341 Jaffer's small and portable implementation of Scheme, SCM, and making it
342 into an embeddable interpreter: callable from C and allowing new Scheme
343 procedures to be written in C.
345 @cindex Jaffer, Aubrey
347 In the spring of 1995, the guile-ii snapshot was released. This made it
348 possible to start writing code in C and Scheme using the guile
351 The guile-iii snapshot was released the summer of 1995, and it had fixed
352 enough problems so that the access to Scheme data structures from C was
355 After this, Cygnus Support added many features to Guile and finished
356 implementing others, so that Guile acquired thread support, a regular
357 expression matcher, a Tk interface, an interface to the SGI OpenGL
358 graphics system, an @emph{applet} formalism, and some other packages.
359 This was all in the Cygnus Guile r0.3 and r0.4 releases.
360 @cindex Cygnus Support
362 Meanwhile, Tom Lord left the project after having produced a divergent
363 version of Guile: 1.0b2. The Free Software Foundation hired Jim Blandy
364 to coordinate Guile development. The FSF released its first version of
365 Guile in January 1997. In the future, many of the Cygnus packages will
366 be re-integrated into Guile.
368 @cindex Free Software Foundation
372 @node How to characterize Guile
373 @section How to characterize Guile
375 I have already mentioned that Guile has become a kitchen sink package;
376 here you can see how Guile freely takes new commands and constructs from
377 the portable Scheme library @emph{slib}, the @emph{Tk} widget set, a
378 posix library (useful for UNIX systems programming), the regular
379 expression library @emph{rx}, and many more @dots{}
386 So Guile has many more primitive procedures available to it than those
387 specified in @ref{Standard Procedures, Revised(5) Report on the
388 Algorithmic Language Scheme, , r5rs, Revised(5) Report on the
389 Algorithmic Language Scheme}. On top of that, Guile will interpret
390 almost all standard Scheme programs. The only incompatible difference
391 between the basic Guile language and R5RS Scheme is that Guile is case
392 sensitive, whereas R5RS is case insensitive. We hope that few people
393 have written Scheme programs that depend on case insensitivity.
394 @cindex case sensitivity
395 @cindex Revised(5) Report on the Algorithmic Language Scheme
396 @cindex report on Scheme
397 @cindex Scheme language - report
398 @cindex Scheme language - definition
400 Here is a possible view of the @emph{sum of the parts} in Guile:
401 @cindex extensions to standard Scheme
402 @cindex extensions to R5RS
403 @cindex Scheme extensions
405 guile = standard Scheme (R5RS)
406 PLUS extensions to R5RS offered by SCM
407 PLUS some extra primitives offered by Guile (catch/throw)
408 PLUS portable Scheme library (SLIB)
409 PLUS embeddable Scheme interpreter library (libguile)
413 @c PLUS OpenGL library (mesa)
414 @c PLUS OpenGL toolkit (glut)
415 PLUS Regular expression library (rx)
416 @c PLUS Applet formalism
421 @node Using Guile to program in Scheme
422 @chapter Using Guile to program in Scheme
423 @cindex Scheme programming tutorial
424 @cindex tutorial on Scheme programming
426 In this section I give a tutorial introduction to programming in Scheme,
427 with a slant toward the interesting things that can be done in Guile.
429 @c Applets are so @emph{chic} that they get their own section, but this
430 This section will try to touch on many of the interesting and cool
431 aspects of Guile, showing you how new types of problems can be solved
432 with Guile. Note that using Guile as a library with @code{libguile.a}
433 is described in its own chapter (@pxref{Guile in a Library}). Also note
434 that some small examples are given in @ref{Jump Start}.
436 To get started you need to know how to program in @dfn{Scheme} (a
437 dialect of LISP). Fortunately Scheme is a small, clean language and is
438 not hard to learn. It is also used in many undergraduate courses to
439 introduce computer programming.
440 @cindex lisp dialects
442 I will not try to teach you Scheme here (although you might end up
443 learning by example), since there are many good books on the subject,
444 listed in @ref{Where to find more Guile/Scheme resources}. @footnote{To
445 get started, look at the books @cite{Simply Scheme} and @cite{The Little
446 Schemer} from that list.}
449 @subsection Hello World
452 Our first program is the typical Scheme "hello world" program. Put the
453 following code in a file called @code{hello.scm} (this can be find in
454 @file{examples/scheme/hello.scm}).
457 #!/usr/local/bin/guile -s
460 (display "hello world")
464 Then run guile on it. One way to do so is to start up guile and load
468 <shell-prompt> @kbd{guile}
469 guile> @kbd{(load "hello")}
472 Another way is to make the file executable and execute it directly.
473 Notice how Guile recognizes a @code{-s} option which tells it to run a
474 script and then exit. Guile also has a new type of block comment
475 enclosed by @code{#!} and @code{!#}, so that you can make executable
476 Scheme scripts with the standard UNIX @code{#!} mechanism.
478 In the given example, the first line is used to invoke the Guile
479 interpreter (make sure you correct the path if you installed Guile in
480 something other than /usr/local/bin). Once Guile is invoked on this
481 file, it will understand that the first line is a comment. The comment
482 is then terminated with @code{!#} on the second line so as to not
483 interfere with the execution mechanism.
486 @subsection A bunch of operations in Scheme
488 Here is some code you can type at the @code{guile>} prompt to see some
489 of the Scheme data types at work (mostly lists and vectors). I have
490 inserted brief comments @emph{before} each line of code explaining what
494 ;; @r{make a list and bind it to the symbol @code{ls}}
495 guile> @kbd{(define ls (list 1 2 3 4 5 6 7))}
497 ;; @r{display the list}
499 @result{} (1 2 3 4 5 6 7)
500 ;; @r{ask if @code{ls} is a vector; @code{#f} means it is not}
501 guile> @kbd{(vector? ls)}
503 ;; @r{ask if @code{ls} is a list; @code{#t} means it is}
504 guile> @kbd{(list? ls)}
506 ;; @r{ask for the length of @code{ls}}
507 guile> @kbd{(length ls)}
509 ;; @r{pick out the first element of the list}
510 guile> @kbd{(car ls)}
512 ;; @r{pick the rest of the list without the first element}
513 guile> @kbd{(cdr ls)}
514 @result{} (2 3 4 5 6 7)
515 ;; @r{this should pick out the 3rd element of the list}
516 guile> @kbd{(car (cdr (cdr ls)))}
518 ;; @r{a shorthand for doing the same thing}
519 guile> @kbd{(caddr ls)}
521 ;; @r{append the given list onto @code{ls}, print the result}
522 ;; @r{@strong{NOTE:} the original list @code{ls} is @emph{not} modified}
523 guile> @kbd{(append ls (list 8 9 10))}
524 @result{} (1 2 3 4 5 6 7 8 9 10)
525 guile> @kbd{(reverse ls)}
526 @result{} (7 6 5 4 3 2 1)
527 ;; @r{ask if 12 is in the list --- it obviously is not}
528 guile> @kbd{(memq 12 ls)}
530 ;; @r{ask if 4 is in the list --- returns the list from 4 on.}
531 ;; @r{Notice that the result will behave as true in conditionals}
532 guile> @kbd{(memq 4 ls)}
534 ;; @r{an @code{if} statement using the aforementioned result}
535 guile> @kbd{(if (memq 4 ls)
536 (display "hey, it's true!\n")
537 (display "dude, it's false\n"))}
538 @print{hey, it's true!}
540 guile> @kbd{(if (memq 12 ls)
541 (display "hey, it's true!\n")
542 (display "dude, it's false\n"))}
543 @print{dude, it's false}
545 guile> @kbd{(memq 4 (reverse ls))}
547 ;; @r{make a smaller list @code{ls2} to work with}
548 guile> @kbd{(define ls2 (list 2 3 4))}
549 ;; @r{make a list in which the function @code{sin} has been}
550 ;; @r{applied to all elements of @code{ls2}}
551 guile> @kbd{(map sin ls2)}
552 @result{} (0.909297426825682 0.141120008059867 -0.756802495307928)
553 ;; @r{make a list in which the squaring function has been}
554 ;; @r{applied to all elements of @code{ls}}
555 guile> @kbd{(map (lambda (n) (* n n)) ls)}
556 @result{} (1 4 9 16 25 36 49)
560 ;; @r{make a vector and bind it to the symbol @code{v}}
561 guile> @kbd{(define v '#(1 2 3 4 5 6 7))}
563 @result{} #(1 2 3 4 5 6 7)
564 guile> @kbd{(vector? v)}
566 guile> @kbd{(list? v)}
568 guile> @kbd{(vector-length v)}
570 ;; @r{vector-ref allows you to pick out elements by index}
571 guile> @kbd{(vector-ref v 2)}
573 ;; @r{play around with the vector: make it into a list, reverse}
574 ;; @r{the list, go back to a vector and take the second element}
575 guile> @kbd{(vector-ref (list->vector (reverse (vector->list v))) 2)}
577 ;; @r{this demonstrates that the entries in a vector do not have}
578 ;; @r{to be of uniform type}
579 guile> @kbd{(vector-set! v 4 "hi there")}
582 @result{} #(1 2 3 4 "hi there" 6 7)
586 @subsection Using recursion to process lists
588 @cindex list processing
590 Here are some typical examples of using recursion to process a list.
593 ;; @r{this is a rather trivial way of reversing a list}
594 (define (my-reverse l)
597 (append (my-reverse (cdr l)) (list (car l)))))
598 (my-reverse '(27 32 33 40))
599 @result{} (40 33 32 27)
603 @subsection Processing matrices
605 Suppose you have a matrix represented as a list of lists:
610 (list 7 2 1 3 2 8 5 3 6)
611 (list 4 1 1 1 3 8 9 8 1)
612 (list 5 5 4 8 1 8 2 2 4)))
615 Then you could apply a certain function to each element of the matrix in
616 the following manner:
618 ;; @r{apply the function func to the matrix m element-by-element;}
619 ;; @r{return a matrix with the result.}
620 (define (process-matrix m func)
625 Notice that I have used the Scheme @code{map} procedure because I am
626 interested in the matrix that results from the application of
627 @code{func}, rather than in the side effects associated with applying
630 This could be invoked with @code{(process-matrix m sin)} or
631 @code{(process-matrix m (lambda (x) (* x x)))}; for example:
634 (process-matrix m (lambda (x) (* x x)))
635 @result{} ((49 4 1 9 4 64 25 9 36) (16 1 1 1 9 64 81 64 1) (25 25 16 64 1 64 4 4 16))
638 To print a representation of the matrix, we could define a generalized
641 ;; @r{proc is a procedure to represent the single element,}
642 ;; @r{row-proc is a procedure that is invoked after each row.}
643 ;; @r{Example: proc could be (lambda (x) (begin (display x) (display " ")))}
644 ;; @r{and row-proc could be (lambda (l) (display "\n"))}
645 (define (represent-matrix m proc row-proc)
646 (for-each (lambda (l)
652 @findex represent-matrix
654 And then invoke it with
657 (lambda (x) (begin (display x) (display " ")))
658 (lambda (l) (begin (display "\n"))))
659 @print{7 2 1 3 2 8 5 3 6}
660 @print{4 1 1 1 3 8 9 8 1}
661 @print{5 5 4 8 1 8 2 2 4}
666 Now we write a helper routine that uses Scheme @dfn{closures} to make
667 objects with state that then receive messages to draw little squares.
669 @cindex syntactic closures
671 But let us take it one step at a time. I will start by showing you a
672 simple example of object in Scheme. The object I make here represents a
673 cell, which could be a cell in a matrix. The cell responds to commands
674 to draw itself, to return the next cell, and so forth. @emph{Guile does
675 not currently have a Tk interface, so I will leave the hooks for
676 graphical rendering. In a future release of Guile I will add graphical
677 rendering messages to the cell object.}
680 ;; @r{cell-object.scm: routines for creating and manipulating cell objects}
682 ;; @r{(the-x, the-y) is the initial position of the cell.}
683 ;; @r{the-color is a string representing a color; must be something Tk can grok.}
684 ;; @r{square-size is the size of the square that gets drawn.}
685 ;; @r{(sizex, sizey) is the size of the matrix.}
686 (define (MAKE-CELL the-x the-y the-color square-size sizex sizey)
687 (define (get-x) the-x)
688 (define (get-y) the-y)
690 (define (set-x! new-x)
693 (define (set-y! new-y)
696 (define (get-color) the-color)
697 (define (set-color! new-color)
698 (set! the-color new-color)
701 (set! the-x (+ the-x 1))
705 (set! the-y (+ the-y 1))))
708 (display "CELL next!: value of y is too big; not changing it\n")
709 (set! the-y (- the-y 1))))
712 (let* ((x0 (* the-x square-size))
713 (y0 (* the-y square-size))
714 (x1 (+ x0 square-size))
715 (y1 (+ y0 square-size)))
716 (display "I should draw a ")
718 (display " rectangle with corners at ")
719 (display x0) (display y0) (display x1) (display y1)
722 ;; self is the dispatch procedure
723 (define (self message)
730 ((set-color!) set-color!)
733 (else (error "CELL: Unknown message -> " message))))
734 ;; and now return the dispatch procedure
741 What does this procedure do? It returns another procedure
742 (@code{self}) which receives a message (x, y, set-x!, set-y!, @dots{})
743 and takes an action to return or modify its state. The state consists
744 of the values of variables @code{the-x}, @code{the-y}, @code{the-color}
747 Here are some examples of how to use MAKE-CELL and the cell object it
750 (define c (MAKE-CELL 0 0 "red" 10 7 9))
752 ;; @r{retrieve the x and y coordinates}
757 ;; @r{change the x coordinate}
762 ;; @r{change the color}
765 ((c 'set-color!) "green")
769 ;; @r{now use the next! message to move to the next cell}
776 ;; @r{now make things wrap around}
789 You will notice that expressions like @code{(c 'next)} return procedures
790 that do the job, so we have to use extra parentheses to make the job
791 happen. This syntax is rather awkward; one way around it is to define a
792 @code{send} procedure:
795 ;; @r{send makes object syntax a bit easier; instead of saying}
796 ;; @r{ ((my-cell 'set-x!) 4)}
798 ;; @r{ (send my-cell 'set-x! 4)}
799 (define (send obj . args)
800 (let ((first-eval (apply obj (list (car args)))))
801 (if (null? (cdr args))
803 (apply first-eval (cdr args)))))
807 You can see that @code{send} passes the message to the object, making
808 sure that things are evaluated the proper number of times. You can now
812 (define c2 (MAKE-CELL 0 0 "red" 10 7 9))
819 (send c2 'set-color! "green")
829 @cindex object-based programming
830 @cindex object-oriented programming
832 This is the simplest way of implementing objects in Scheme, but it does
833 not really allow for full @emph{object-oriented programming} (for
834 example, there is no inheritance). But it is useful for
835 @emph{object-based programming}.
837 Guile comes with a couple more complete object-oriented extensions to
838 Scheme: these are part of slib (@pxref{Object, , , slib, SLIB: the
839 portable Scheme library} and @pxref{Yasos, , , slib, SLIB: the portable
842 @node Guile in a Library
843 @chapter Guile in a Library
848 In the previous chapters Guile was used to write programs entirely in
849 Scheme, and no C code was seen; but I have been claiming @emph{ad
850 nauseam} that Guile is an @emph{extension} language. Here we see how
851 that is done, and how that can be useful.
853 @cindex extending C programs
859 * How to get started with libguile::
860 * More interesting programming with libguile::
864 @node Two world views
865 @section Two world views
868 In this manual, I usually jump into examples and explain them as you
869 type in the code; here I will digress and ramble for a few paragraphs to
870 set some concepts straight, and then let you type (or paste) in fun
873 In 1995, I implemented a large program, @dfn{Gnudl}, using Guile quite
874 extensively. In the design phase of Gnudl, I found I had to make a
875 choice: should the fundamental data structures be C or Scheme data
878 @cindex GNU Data Language
879 @cindex Galassi, Mark
881 Guile allows C to see its data structures (scalar types, lists, vectors,
882 strings @dots{}). C also allows Guile to see its data structures. As a
883 large program designer, you have to decide which of those capabilities
884 to use. You have two main choices:
888 You can write your software mostly in Scheme. In this case, your C
889 software will mostly parse the Scheme code with Guile calls, and provide
890 some new primitive procedures to be used by Scheme. This is what Gnudl
894 You can write your software mostly in C, occasionally allowing Scheme
895 code to be parsed by Guile, either to allow the user to modify data
896 structures, or to parse a configuration file, @dots{}
899 Mixing the two approaches seems unwise: the overall layout would be
900 confusing. But who knows? There might be problems that are best solved
901 by a hybrid approach. Please let me know if you think of such a
904 If you use the former approach, we will say that the @dfn{master world}
905 is Scheme, and the C routines serve Scheme and access Scheme data
906 structures. In the latter case, the master world is C, and Scheme
907 routines serve the C code and access C data structures.
909 In both approaches the @code{libguile.a} library is the same, but a
910 predominantly different set of routines will be used. When we go
911 through examples of libguile use, we will point out which is the master
912 world in order to clarify these two approaches.
915 @node What is libguile
916 @section What is libguile
919 @cindex scm interface
921 @dfn{Libguile} is the library which allows C programs to start a Scheme
922 interpreter and execute Scheme code. There are also facilities in
923 libguile to make C data structures available to Scheme, and vice versa.
925 The interface provided by the libguile C library is somewhat specific to
926 the implementation of the Scheme interpreter. This low-level libguile
927 interface is usually referred to as the @code{scm_} interface, since its
928 public calls (API) all have the @code{scm_} prefix.
930 There is also a higher-level libguile interface, which is usually
931 referred to as the @code{gh_} interface (libGuile High). Its public
932 calls all have the @code{gh_} prefix. The @code{gh_} library interface
933 is designed to hide the implementation details, thus making it easier to
934 assimilate and portable to other underlying Scheme implementations.
936 People extending Guile by adding bindings to C libraries (like OpenGL or
937 Rx) are encouraged to use the @code{gh_} interface, so their work will
938 be portable to other Scheme systems. The @code{gh_} interface should be
939 more stable, because it is simpler.
941 The @code{scm_} interface is necessary if you want to poke into the
942 innards of Scheme data structures, or do anything else that is not
943 offered by the @code{gh_} interface. It is not covered in this
944 tutorial, but is covered extensively in @ref{Data representation,, Data
945 Representation in Guile, guile, Guile Reference Manual}.
947 This chapter gives a gentle introduction to the @code{gh_} interface,
948 presenting some @emph{hello world}-style programs which I wrote while
949 teaching myself to use libguile.
952 The @cite{Guile Programmer's Manual} gives more examples of programs
953 written using libguile, illustrating diverse applications. You can also
954 consult my @emph{Gnudl} documentation at
955 @url{http://nis-www.lanl.gov/~rosalia/mydocs/} to see a large scale
956 project that uses C and Scheme code together.
959 @node How to get started with libguile
960 @section How to get started with libguile
963 Here is an elementary first program, @code{learn0}, to get going with
964 libguile. The program (which uses Scheme as a master world) is in a
965 single source file, @code{learn0.c}:
968 /* @r{test the new libgh.a (Guile High-level library) with a trivial
973 #include <guile/gh.h>
975 void main_prog(int argc, char *argv[]);
977 main(int argc, char *argv[])
979 gh_enter(argc, argv, main_prog);
982 void main_prog(int argc, char *argv[])
987 gh_eval_str("(display \"hello Guile\")");
988 gh_eval_str("(newline)");
990 /* @r{for fun, evaluate some simple Scheme expressions here} */
991 gh_eval_str("(define (square x) (* x x))");
992 gh_eval_str("(define (fact n) (if (= n 1) 1 (* n (fact (- n 1)))))");
993 gh_eval_str("(square 9)");
995 /* @r{now sit in a Scheme eval loop: I input the expressions, have
996 Guile evaluate them, and then get another expression.} */
998 fputs("learn0> ", stdout);
999 while (fgets(input_str, 199, stdin) != NULL) @{
1000 gh_eval_str(input_str);
1001 fputs("\nlearn0> ", stdout);
1008 If you name this program @code{learn0.c}, it can now be compiled with:
1010 gcc -g -c learn0.c -o learn0.o
1011 gcc -o learn0 learn0.o -lguile -lm
1014 @c @emph{NOTE: If you are in the Guile development tree, you can simply do
1015 @c ``cd doc/examples/c; make; ./learn0''.}
1017 The program is simple: it creates a Scheme interpreter, passes a couple
1018 of strings to it that define new Scheme functions @code{square} and
1019 @code{factorial}, and then a couple of strings that invoke those
1022 It then goes into a read-eval-print-loop (REPL), so you could type
1023 one-line Scheme expressions to it and have them evaluated. For example:
1025 <shell-prompt> ./learn0
1027 learn0> (display (sin 1.3))
1029 learn0> (display (fact 10))
1035 You should notice the key steps involved in this @code{learn0} program:
1040 @code{#include <guile/gh.h>}
1042 You need to invoke the initialization routine @code{gh_enter()}. This
1043 starts up a Scheme interpreter, handling many implementation-specific
1046 Your main() function should be almost empty: the real main program goes
1047 in a separate function main_prog() which is passed to gh_enter(). This
1048 rather arcane convention is due to the way Guile's garbage collector
1049 works: the whole program has to run in the dynamic context of
1052 You pass strings to the Scheme interpreter with the @code{gh_eval_str()}
1055 You link your program with @code{-lguile}.
1060 @node More interesting programming with libguile
1061 @section More interesting programming with libguile
1064 @cindex builtin functions
1066 The @code{learn0} program shows how you can invoke Scheme commands from
1067 a C program. This is not such a great achievement: the same could have
1068 been done by opening a pipe to SCM or any other Scheme interpreter.
1070 A true extension language must allow @dfn{callbacks}. Callbacks allow
1071 you to write C routines that can be invoked as Scheme procedures, thus
1072 adding new primitive procedures to Scheme. This also means that a
1073 Scheme procedure can modify a C data structure.
1075 Guile allows you to define new Scheme procedures in C, and provides a
1076 mechanism to go back and forth between C and Scheme data types.
1078 Here is a second program, @code{learn1}, which demonstrates these
1079 features. It is split into three source files: @code{learn1.c},
1080 @code{c_builtins.h} and @code{c_builtins.c}. I am including the code
1082 @c , but you might just want to look at the online source code and the
1083 @c Makefile.am that come with Guile in the
1084 @c @file{doc/examples/c} directory.
1086 Notice that @code{learn1} uses a Scheme master world, and the C routines
1087 in @code{c_builtins.c} are simply adding new primitives to Scheme.
1093 * What learn1 is doing::
1094 * Compiling and running learn1::
1098 @subsection learn1.c
1100 Here is @file{learn1.c}:
1104 #include <guile/gh.h>
1106 #include "c_builtins.h"
1108 void main_prog(int argc, char *argv[]);
1110 main(int argc, char *argv[])
1112 gh_enter(argc, argv, main_prog);
1115 void main_prog(int argc, char *argv[])
1117 char input_str[200]; /* @r{ugly hack: assume strlen(line) < 200} */
1120 /* @r{for fun, evaluate some simple Scheme expressions here} */
1121 gh_eval_str("(define (square x) (* x x))");
1122 gh_eval_str("(define (fact n) (if (= n 1) 1 (* n (fact (- n 1)))))");
1123 gh_eval_str("(square 9)");
1124 gh_eval_str("(fact 100)");
1126 /* @r{now try to define some new builtins, coded in C, so that they are
1127 available in Scheme.} */
1128 gh_new_procedure1_0("c-factorial", c_factorial);
1129 gh_new_procedure1_0("c-sin", c_sin);
1130 gh_new_procedure1_0("v-t", vector_test);
1132 /* @r{now sit in a Scheme eval loop: I input the expressions, have
1133 Guile evaluate them, and then get another expression.} */
1135 fputs("learn1> ", stdout);
1137 if (gets(input_str) == NULL) @{
1140 gh_eval_str(input_str);
1141 fputs("learn1> ", stdout);
1150 @subsection c_builtins.h
1152 Here is @file{c_builtins.h}:
1154 /* @r{builtin function prototypes} */
1156 #include <guile/gh.h>
1158 SCM c_factorial(SCM n);
1160 SCM vector_test(SCM s_length);
1164 @subsection c_builtins.c
1166 Here is @file{c_builtins.c}:
1171 #include <guile/gh.h>
1173 #include "c_builtins.h"
1175 /* @r{this is a factorial routine in C, made to be callable by Scheme} */
1176 SCM c_factorial(SCM s_n)
1179 unsigned long result = 1, n;
1181 n = gh_scm2ulong(s_n);
1184 for (i = 1; i <= n; ++i) @{
1188 return gh_ulong2scm(result);
1191 /* @r{a sin routine in C, callable from Scheme. it is named c_sin() to
1192 distinguish it from the default Scheme sin function} */
1195 double x = gh_scm2double(s_x);
1197 return gh_double2scm(sin(x));
1200 /* @r{play around with vectors in Guile: this routine creates a vector of
1201 the given length, initializes it all to zero except element 2 which
1203 SCM vector_test(SCM s_length)
1207 c_length = gh_scm2ulong(s_length);
1208 printf("requested length for vector: %ld\n", gh_scm2ulong(s_length));
1210 /* create a vector */
1211 xvec = gh_make_vector(s_length, gh_double2scm(0.0));
1212 /* set the second element in it */
1213 gh_vector_set_x(xvec, gh_int2scm(2), gh_double2scm(1.9));
1219 @node What learn1 is doing
1220 @subsection What learn1 is doing
1221 @cindex registering callbacks
1222 @cindex registering C functions
1223 @cindex primitive procedures
1225 If you compare learn1 to learn0, you will find that learn1 uses a new
1226 Guile construct: the function @code{gh_new_procedure()}, and its
1230 /* @r{now try to define some new builtins, coded in C, so that they are
1231 available in Scheme.} */
1232 gh_new_procedure1_0("c-factorial", c_factorial);
1233 gh_new_procedure1_0("c-sin", c_sin);
1234 gh_new_procedure1_0("v-t", vector_test);
1237 It is clear that @code{gh_new_procedure()} adds a new builtin
1238 routine written in C which can be invoked from Scheme. We can now
1239 revise our checklist for programming with libguile, so it includes
1241 @cindex libguile - step by step
1246 @code{#include <guile/gh.h>}
1248 You need to invoke the initialization routine @code{gh_enter()}. This
1249 starts up a Scheme interpreter, handling many details.
1251 Your main() function should be almost empty: the real main program goes
1252 in a separate function main_prog() which is passed to gh_enter(). This
1253 rather arcane convention is due to the way Guile's garbage collector
1254 works: the whole program has to run in the dynamic context of
1257 You pass strings to the Scheme interpreter with the @code{gh_eval_str()}
1260 @strong{[new]} You can now define new builtin Scheme functions;
1261 i.e. define new builtin Scheme functions, with the
1262 @code{gh_new_procedure()} routine.
1264 You pass strings to the Scheme interpreter with the
1265 @code{gh_eval_str()} routine.
1267 You link your program with @code{-lguile}.
1271 I breezed by the issue of how to write your C routines that are
1272 registered to be called from Scheme. This is non-trivial, and is
1273 discussed at length in the @cite{Guile Programmer's Manual}.
1276 @node Compiling and running learn1
1277 @subsection Compiling and running learn1
1280 gcc -g -c learn1.c -o learn1.o
1281 gcc -g -c c_builtins.c -o c_builtins.o
1282 gcc -o learn1 learn1.o c_builtins.o -lguile -lm
1285 If you run @code{learn1}, it will prompt you for a one-line Scheme
1286 expression, just as @code{learn0} did. The difference is that you can
1287 use the new C builtin procedures (@code{c-factorial}, @code{c-sin},
1291 <shell-prompt> ./learn1
1294 learn1> (display (c-factorial 6))
1296 learn1> (display (c-factorial 20))
1298 learn1> (display (c-factorial 100))
1300 learn1> (display (c-sin 1.5))
1302 learn1> (display (v-t 10))
1303 requested length for vector: 10
1304 #(0.0 0.0 1.9 0.0 0.0 0.0 0.0 0.0 0.0 0.0)
1305 learn1> (display (v-t 15))
1306 requested length for vector: 15
1307 #(0.0 0.0 1.9 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0)
1312 As you see, taking @code{(c-factorial 100)} does not use bignumbers and
1313 returns a bogus answer.
1315 @node Further examples
1316 @section Further examples
1318 Further ``idealized'' examples are included in the @code{doc/examples/c}
1319 distribution. They include programs to:
1321 @c [FIXME: still have to write some of these; then I will revise the list.]
1325 Parse a startup file (C is the master world).
1327 Set up initial conditions for an n-body simulation (C is the master
1330 Implement a Scheme interpreter with all of Guile's goodies, @emph{plus}
1331 the readline library @emph{and} a fast Fourier transform routine
1332 provided in C (Scheme is the master world).
1335 @node Regular Expression Support
1336 @chapter Regular Expression Support
1338 @node UNIX System Programming
1339 @chapter UNIX System Programming
1341 @node Where to find more Guile/Scheme resources
1342 @chapter Where to find more Guile/Scheme resources
1346 @unnumbered Concept Index
1350 @node Procedure and Macro Index
1351 @unnumbered Procedure and Macro Index
1353 This is an alphabetical list of all the procedures and macros in Dominion.
1357 @node Variable Index
1358 @unnumbered Variable Index
1360 This is an alphabetical list of the major global variables in Dominion.
1365 @unnumbered Type Index
1367 This is an alphabetical list of the major data structures in Dominion.