Commit | Line | Data |
---|---|---|
028321d4 NJ |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
3 | @setfilename guile-tut.info | |
4 | @settitle Guile Tutorial | |
5 | ||
6 | @include version.texi | |
7 | ||
8 | @dircategory The Algorithmic Language Scheme | |
9 | @direntry | |
10 | * Guile Tutorial: (guile-tut). The Guile tutorial. | |
11 | @end direntry | |
12 | ||
13 | @setchapternewpage off | |
14 | @c Choices for setchapternewpage are {on,off,odd}. | |
15 | @paragraphindent 2 | |
16 | @c %**end of header | |
17 | ||
18 | @iftex | |
19 | @finalout | |
20 | @c DL: lose the egregious vertical whitespace, esp. around examples | |
21 | @c but paras in @defun-like things don't have parindent | |
22 | @parskip 4pt plus 1pt | |
23 | @end iftex | |
24 | ||
25 | @titlepage | |
26 | @title Guile Tutorial | |
27 | @subtitle For use with Guile @value{VERSION} | |
28 | @subtitle Last updated @value{UPDATED} | |
29 | @author Mark Galassi | |
30 | @author Cygnus Solutions and | |
31 | @author Los Alamos National Laboratory | |
32 | @author @email{rosalia@@nis.lanl.gov} | |
33 | ||
34 | @page | |
35 | @vskip 0pt plus 1filll | |
36 | Copyright @copyright{} 1997, 1998 Free Software Foundation | |
37 | ||
38 | Permission is granted to make and distribute verbatim copies of | |
39 | this manual provided the copyright notice and this permission notice | |
40 | are preserved on all copies. | |
41 | ||
42 | Permission is granted to copy and distribute modified versions of this | |
43 | manual under the conditions for verbatim copying, provided that the entire | |
44 | resulting derived work is distributed under the terms of a permission | |
45 | notice identical to this one. | |
46 | ||
47 | Permission is granted to copy and distribute translations of this manual | |
48 | into another language, under the above conditions for modified versions, | |
49 | except that this permission notice may be stated in a translation approved | |
50 | by the author. | |
51 | @end titlepage | |
52 | ||
53 | ||
54 | @ifinfo | |
55 | @node Top | |
56 | @top Guile Tutorial | |
57 | @end ifinfo | |
58 | ||
59 | @ifinfo | |
60 | This file gives a tutorial introductionto Guile. | |
61 | ||
62 | Copyright (C) 1997 Free Software Foundation | |
63 | ||
64 | Permission is granted to make and distribute verbatim copies of | |
65 | this manual provided the copyright notice and this permission notice | |
66 | are preserved on all copies. | |
67 | ||
68 | @ignore | |
69 | Permission is granted to process this file through TeX and print the | |
70 | results, provided the printed document carries copying permission | |
71 | notice identical to this one except for the removal of this paragraph | |
72 | (this paragraph not being relevant to the printed manual). | |
73 | ||
74 | @end ignore | |
75 | Permission is granted to copy and distribute modified versions of this | |
76 | manual under the conditions for verbatim copying, provided that the entire | |
77 | resulting derived work is distributed under the terms of a permission | |
78 | notice identical to this one. | |
79 | ||
80 | Permission is granted to copy and distribute translations of this manual | |
81 | into another language, under the above conditions for modified versions, | |
82 | except that this permission notice may be stated in a translation approved | |
83 | by the author. | |
84 | @end ifinfo | |
85 | ||
86 | ||
87 | @menu | |
88 | * Jump Start:: | |
89 | * Introduction:: | |
90 | * Using Guile to program in Scheme:: | |
91 | * Guile in a Library:: | |
92 | * Regular Expression Support:: | |
93 | * UNIX System Programming:: | |
94 | * Where to find more Guile/Scheme resources:: | |
95 | * Concept Index:: | |
96 | * Procedure and Macro Index:: | |
97 | * Variable Index:: | |
98 | * Type Index:: | |
99 | @end menu | |
100 | ||
101 | @node Jump Start | |
102 | @chapter Jump Start | |
103 | ||
104 | @noindent | |
105 | Before giving an overview of Guile, I present some simple commands and | |
106 | programs that you can type to get going immediately. | |
107 | ||
108 | Start by invoking the Guile interpreter (usually you do this by just | |
109 | typing @code{guile}). Then type (or paste) the following expressions at | |
110 | the prompt; the interpreter's response is preceded (in this manual) by | |
111 | @result{}. | |
112 | ||
113 | @example | |
114 | <shell-prompt> guile | |
115 | @end example | |
116 | @lisp | |
117 | (+ 20 35) | |
118 | @result{} 55 | |
119 | (define (recursive-factorial n) | |
120 | (if (= n 0) | |
121 | 1 | |
122 | (* n (recursive-factorial (- n 1))))) | |
123 | (recursive-factorial 5) | |
124 | @result{} 120 | |
125 | (recursive-factorial 500) | |
126 | @result{} 1220136825991110068701238785423046926253574342803192842192413588 | |
127 | 3858453731538819976054964475022032818630136164771482035841633787 | |
128 | 2207817720048078520515932928547790757193933060377296085908627042 | |
129 | 9174547882424912726344305670173270769461062802310452644218878789 | |
130 | 4657547771498634943677810376442740338273653974713864778784954384 | |
131 | 8959553753799042324106127132698432774571554630997720278101456108 | |
132 | 1188373709531016356324432987029563896628911658974769572087926928 | |
133 | 8712817800702651745077684107196243903943225364226052349458501299 | |
134 | 1857150124870696156814162535905669342381300885624924689156412677 | |
135 | 5654481886506593847951775360894005745238940335798476363944905313 | |
136 | 0623237490664450488246650759467358620746379251842004593696929810 | |
137 | 2226397195259719094521782333175693458150855233282076282002340262 | |
138 | 6907898342451712006207714640979456116127629145951237229913340169 | |
139 | 5523638509428855920187274337951730145863575708283557801587354327 | |
140 | 6888868012039988238470215146760544540766353598417443048012893831 | |
141 | 3896881639487469658817504506926365338175055478128640000000000000 | |
142 | 0000000000000000000000000000000000000000000000000000000000000000 | |
143 | 00000000000000000000000000000000000000000000000 | |
144 | <control-D> | |
145 | @end lisp | |
146 | ||
147 | In this example we did some simple arithmetic @code{(+ 20 35)} and got | |
148 | the answer @code{55}. Then we coded the classic (and rather wasteful) | |
149 | factorial algorithm, and got a glimpse of Scheme's nice | |
150 | @emph{bignumbers} by asking for the factorial of 1000. Then we quit | |
151 | with @code{(quit)}. | |
152 | @cindex bignumbers | |
153 | ||
154 | This is the most basic use of Guile: a simple Scheme interpreter. In | |
155 | the rest of this tutorial I will show you how Guile has many facets: it | |
156 | is also an @emph{extensible} interpreter (to which many features can be | |
157 | easilly added) and an @emph{embeddable} interpreter (which can be | |
158 | invoked from your C programs). | |
159 | ||
160 | ||
161 | @node Introduction | |
162 | @chapter Introduction | |
163 | ||
164 | @noindent | |
165 | @dfn{Guile} (which can stand for @emph{GNU Ubiquitous Intelligent | |
166 | Language Extension}) is the GNU extension language. It started out as | |
167 | an embeddable Scheme interpreter, and has rapidly evolved into a | |
168 | kitchen-sink package including a standalone Scheme interpreter, an | |
169 | embeddable Scheme interpreter, several graphics options, other languages | |
170 | that can be used along with Scheme (for now just @emph{ctax} and | |
171 | @emph{Tcl}), and hooks for much more. | |
172 | ||
173 | ||
174 | @menu | |
175 | * What are scripting and extension languages:: | |
176 | * History of Guile and its motivations:: | |
177 | * How to characterize Guile:: | |
178 | @end menu | |
179 | ||
180 | @node What are scripting and extension languages | |
181 | @section What are scripting and extension languages | |
182 | @cindex scripting languages | |
183 | @cindex extension languages | |
184 | ||
185 | A @dfn{scripting language} is a programming language which serves as | |
186 | glue between other system programs. In the UNIX world, the traditional | |
187 | scripting language is the @emph{Bourne shell}, which allows many UNIX | |
188 | commands to be executed in sequence, or in a pipeline. Traditional UNIX | |
189 | commands are cleverly written to work well when put together in a | |
190 | script. | |
191 | ||
192 | Other examples of UNIX scripting languages are AWK, Perl, Scsh (the | |
193 | Scheme Shell: a Scheme interpreter enhanced to do good scripting), | |
194 | Python, Tcl, Java @dots{} | |
195 | @cindex scripting languages - examples | |
196 | ||
197 | UNIX programmers noticed, more than 25 years ago, that scripting | |
198 | languages can do serious work, so the Bourne shell was written to have | |
199 | variables, operators and control structures, just like a full-featured | |
200 | programming language. | |
201 | @cindex Bourne shell | |
202 | ||
203 | What scripting languages have, that traditional programming languages do | |
204 | not, is the ability to easily run an external program (or a pipeline of | |
205 | external programs) and use the returned values and output from that | |
206 | program in useful ways. | |
207 | ||
208 | An @dfn{extension language} is a programming language interpreter | |
209 | offered by an application program, so that users can write macros or | |
210 | even full-fledged programs to extend the original application. | |
211 | Extension languages have a C interface (it is usually C, but it could be | |
212 | any other compiled language), and can be given access to the C data | |
213 | structures. Likewise, there are C routines to access the extension | |
214 | language data structures. | |
215 | ||
216 | Extension languages abound in the software world, even though the name | |
217 | @emph{extension language} is seldom used. Examples are: | |
218 | @cindex extension languages - examples | |
219 | ||
220 | @itemize @bullet | |
221 | @item | |
222 | Emacs Lisp, the language used to program and customize GNU Emacs. | |
223 | @cindex Emacs Lisp | |
224 | ||
225 | @item | |
226 | Tcl, John Ousterhout's general-purpose scripting and extension language. | |
227 | @cindex Tcl | |
228 | ||
229 | @item | |
230 | The Lotus 1-2-3 macro language (any spreadsheet macro language, | |
231 | really). I mention this one first because it is a classic, even though | |
232 | it is seldom used any more. | |
233 | @cindex Lotus 1-2-3 | |
234 | ||
235 | @item | |
236 | Other spreadsheet and database macro languages. | |
237 | ||
238 | @item | |
239 | The Dominion empire-style game's @emph{exec} files. | |
240 | @cindex Dominion | |
241 | ||
242 | @item | |
243 | Any syntax for a ".*rc" file you might have used. Almost all programs | |
244 | end up parsing some kind of startup or configuration file. The syntax | |
245 | for those can get pretty involved, thus justifying calling them | |
246 | "extension languages". The @emph{fvwm} window manager, for example, | |
247 | parses a rather elaborate @file{.fvwmrc} file. | |
248 | ||
249 | @item | |
250 | Brent Benson's libscheme.a, an embeddable Scheme interpreter. | |
251 | @cindex Benson, Brent | |
252 | @cindex libscheme | |
253 | ||
254 | @item | |
255 | Guile, the GNU extension language, which is the subject of this | |
256 | tutorial. | |
257 | ||
258 | @end itemize | |
259 | ||
260 | One lesson we can learn from looking at classical large software | |
261 | applications is that "writers of large programs" always end up throwing | |
262 | in some kind of parser for configuration or scripting. | |
263 | ||
264 | Of the examples listed above, Emacs Lisp, Tcl, Libscheme and Guile have | |
265 | an important property: they are not added as an afterthought for a | |
266 | specific application. They are general-purpose languages which a user | |
267 | can learn (even in college courses) and then use to customize the | |
268 | application program. | |
269 | ||
270 | This is a recent and (in my opinion) very exciting direction in | |
271 | large-program software engineering: program designers can link in the | |
272 | Guile or Tcl library from the very beginning, and tell their users "You | |
273 | want to customize this program? Just use Scheme (or Tcl, or whatever | |
274 | language), which you already know!" | |
275 | @cindex large programs | |
276 | ||
277 | ||
278 | @node History of Guile and its motivations | |
279 | @section History of Guile and its motivations | |
280 | ||
281 | A few separate threads of events led to the development of Guile. | |
282 | ||
283 | In the fall of 1994, Richard Stallman, director of the GNU project, | |
284 | posted an article with the subject "Why you should not use Tcl", in | |
285 | which he argued that Tcl is inadequate as an extension language. This | |
286 | generated a flurry of flames (available in the hypermail archive | |
287 | (@url{http://www.utdallas.edu/acc/glv/Tcl/war/}) @strong{The Tcl War}). | |
288 | @cindex Stallman, Richard | |
289 | @cindex GNU project | |
290 | @cindex Tcl | |
291 | ||
292 | The result was that Stallman then proposed his design for the GNU | |
293 | Extension Language, first called GEL and then renamed Guile. The | |
294 | discussion triggered by that article is also available in a hypermail | |
295 | archive, @url{http://www.utdallas.edu/acc/glv/Tcl/war2/}. | |
296 | ||
297 | One interesting feature of this GNU Extension Language plan was that | |
298 | users should have a @emph{choice} of languages to use in extending their | |
299 | program. The basic language would be a slightly modified Scheme, and | |
300 | translators would be written to convert other languages (like Tcl, | |
301 | Python, Perl, C-like languages @dots{}) into Scheme. | |
302 | ||
303 | Tom Lord started working on this project immediately, taking Aubrey | |
304 | Jaffer's small and portable implementation of Scheme, SCM, and making it | |
305 | into an embeddable interpreter: callable from C and allowing new Scheme | |
306 | procedures to be written in C. | |
307 | @cindex Lord, Tom | |
308 | @cindex Jaffer, Aubrey | |
309 | ||
310 | In the spring of 1995, the guile-ii snapshot was released. This made it | |
311 | possible to start writing code in C and Scheme using the guile | |
312 | facilities. | |
313 | ||
314 | The guile-iii snapshot was released the summer of 1995, and it had fixed | |
315 | enough problems so that the access to Scheme data structures from C was | |
316 | almost complete. | |
317 | ||
318 | After this, Cygnus Support added many features to Guile and finished | |
319 | implementing others, so that Guile acquired thread support, a regular | |
320 | expression matcher, a Tk interface, an interface to the SGI OpenGL | |
321 | graphics system, an @emph{applet} formalism, and some other packages. | |
322 | This was all in the Cygnus Guile r0.3 and r0.4 releases. | |
323 | @cindex Cygnus Support | |
324 | ||
325 | Meanwhile, Tom Lord left the project after having produced a divergent | |
326 | version of Guile: 1.0b2. The Free Software Foundation hired Jim Blandy | |
327 | to coordinate Guile development. The FSF released its first version of | |
328 | Guile in January 1997. In the future, many of the Cygnus packages will | |
329 | be re-integrated into Guile. | |
330 | @cindex Blandy, Jim | |
331 | @cindex Free Software Foundation | |
332 | ||
333 | ||
334 | ||
335 | @node How to characterize Guile | |
336 | @section How to characterize Guile | |
337 | ||
338 | I have already mentioned that Guile has become a kitchen sink package; | |
339 | here you can see how Guile freely takes new commands and constructs from | |
340 | the portable Scheme library @emph{slib}, the @emph{Tk} widget set, a | |
341 | posix library (useful for UNIX systems programming), the regular | |
342 | expression library @emph{rx}, and many more @dots{} | |
343 | @cindex slib | |
344 | @cindex Tk | |
345 | @cindex POSIX | |
346 | @c @cindex OpenGL | |
347 | @cindex rx | |
348 | ||
349 | So Guile has many more primitive procedures available to it than those | |
8c34cf5b NJ |
350 | specified in @ref{Standard Procedures, Revised(5) Report on the |
351 | Algorithmic Language Scheme, , r5rs, Revised(5) Report on the | |
028321d4 NJ |
352 | Algorithmic Language Scheme}. On top of that, Guile will interpret |
353 | almost all standard Scheme programs. The only incompatible difference | |
8c34cf5b NJ |
354 | between the basic Guile language and R5RS Scheme is that Guile is case |
355 | sensitive, whereas R5RS is case insensitive. We hope that few people | |
028321d4 NJ |
356 | have written Scheme programs that depend on case insensitivity. |
357 | @cindex case sensitivity | |
8c34cf5b | 358 | @cindex Revised(5) Report on the Algorithmic Language Scheme |
028321d4 NJ |
359 | @cindex report on Scheme |
360 | @cindex Scheme language - report | |
361 | @cindex Scheme language - definition | |
362 | ||
363 | Here is a possible view of the @emph{sum of the parts} in Guile: | |
364 | @cindex extensions to standard Scheme | |
8c34cf5b | 365 | @cindex extensions to R5RS |
028321d4 NJ |
366 | @cindex Scheme extensions |
367 | @example | |
8c34cf5b NJ |
368 | guile = standard Scheme (R5RS) |
369 | PLUS extensions to R5RS offered by SCM | |
028321d4 NJ |
370 | PLUS some extra primitives offered by Guile (catch/throw) |
371 | PLUS portable Scheme library (SLIB) | |
372 | PLUS embeddable Scheme interpreter library (libguile) | |
373 | PLUS Tk toolkit | |
374 | PLUS threads | |
375 | PLUS Posix library | |
376 | @c PLUS OpenGL library (mesa) | |
377 | @c PLUS OpenGL toolkit (glut) | |
378 | PLUS Regular expression library (rx) | |
379 | @c PLUS Applet formalism | |
380 | PLUS Tcl library | |
381 | @end example | |
382 | ||
383 | ||
384 | @node Using Guile to program in Scheme | |
385 | @chapter Using Guile to program in Scheme | |
386 | @cindex Scheme programming tutorial | |
387 | @cindex tutorial on Scheme programming | |
388 | ||
389 | In this section I give a tutorial introduction to programming in Scheme, | |
390 | with a slant toward the interesting things that can be done in Guile. | |
391 | ||
392 | @c Applets are so @emph{chic} that they get their own section, but this | |
393 | This section will try to touch on many of the interesting and cool | |
394 | aspects of Guile, showing you how new types of problems can be solved | |
395 | with Guile. Note that using Guile as a library with @code{libguile.a} | |
396 | is described in its own chapter (@pxref{Guile in a Library}). Also note | |
397 | that some small examples are given in @ref{Jump Start}. | |
398 | ||
399 | To get started you need to know how to program in @dfn{Scheme} (a | |
400 | dialect of LISP). Fortunately Scheme is a small, clean language and is | |
401 | not hard to learn. It is also used in many undergraduate courses to | |
402 | introduce computer programming. | |
403 | @cindex lisp dialects | |
404 | ||
405 | I will not try to teach you Scheme here (although you might end up | |
406 | learning by example), since there are many good books on the subject, | |
407 | listed in @ref{Where to find more Guile/Scheme resources}. @footnote{To | |
408 | get started, look at the books @cite{Simply Scheme} and @cite{The Little | |
409 | Schemer} from that list.} | |
410 | ||
411 | ||
412 | @subsection Hello World | |
413 | @cindex hello world | |
414 | ||
415 | Our first program is the typical Scheme "hello world" program. Put the | |
416 | following code in a file called @code{hello.scm} (this can be find in | |
417 | @file{examples/scheme/hello.scm}). | |
418 | ||
419 | @smalllisp | |
420 | #!/usr/local/bin/guile -s | |
421 | !# | |
422 | ||
423 | (display "hello world") | |
424 | (newline) | |
425 | @end smalllisp | |
426 | ||
427 | Then run guile on it. One way to do so is to start up guile and load | |
428 | this file: | |
429 | ||
430 | @smallexample | |
431 | <shell-prompt> @kbd{guile} | |
432 | guile> @kbd{(load "hello")} | |
433 | @end smallexample | |
434 | ||
435 | Another way is to make the file executable and execute it directly. | |
436 | Notice how Guile recognizes a @code{-s} option which tells it to run a | |
437 | script and then exit. Guile also has a new type of block comment | |
438 | enclosed by @code{#!} and @code{!#}, so that you can make executable | |
439 | Scheme scripts with the standard UNIX @code{#!} mechanism. | |
440 | ||
441 | In the given example, the first line is used to invoke the Guile | |
442 | interpreter (make sure you correct the path if you installed Guile in | |
443 | something other than /usr/local/bin). Once Guile is invoked on this | |
444 | file, it will understand that the first line is a comment. The comment | |
445 | is then terminated with @code{!#} on the second line so as to not | |
446 | interfere with the execution mechanism. | |
447 | ||
448 | ||
449 | @subsection A bunch of operations in Scheme | |
450 | ||
451 | Here is some code you can type at the @code{guile>} prompt to see some | |
452 | of the Scheme data types at work (mostly lists and vectors). I have | |
453 | inserted brief comments @emph{before} each line of code explaining what | |
454 | happens. | |
455 | ||
456 | @smalllisp | |
457 | ;; @r{make a list and bind it to the symbol @code{ls}} | |
458 | guile> @kbd{(define ls (list 1 2 3 4 5 6 7))} | |
459 | @result{} | |
460 | ;; @r{display the list} | |
461 | guile> @kbd{ls} | |
462 | @result{(1 2 3 4 5 6 7)} | |
463 | ;; @r{ask if @code{ls} is a vector; @code{#f} means it is not} | |
464 | guile> @kbd{(vector? ls)} | |
465 | @result{#f} | |
466 | ;; @r{ask if @code{ls} is a list; @code{#t} means it is} | |
467 | guile> @kbd{(list? ls)} | |
468 | @result{#t} | |
469 | ;; @r{ask for the length of @code{ls}} | |
470 | guile> @kbd{(length ls)} | |
471 | @result{7} | |
472 | ;; @r{pick out the first element of the list} | |
473 | guile> @kbd{(car ls)} | |
474 | @result{1} | |
475 | ;; @r{pick the rest of the list without the first element} | |
476 | guile> @kbd{(cdr ls)} | |
477 | @result{(2 3 4 5 6 7} | |
478 | ;; @r{this should pick out the 3rd element of the list} | |
479 | guile> @kbd{(car (cdr (cdr ls)))} | |
480 | @result{3} | |
481 | ;; @r{a shorthand for doing the same thing} | |
482 | guile> @kbd{(caddr ls)} | |
483 | @result{3} | |
484 | ;; @r{append the given list onto @code{ls}, print the result} | |
485 | ;; @r{@strong{NOTE:} the original list @code{ls} is @emph{not} modified} | |
486 | guile> @kbd{(append ls (list 8 9 10))} | |
487 | @result{(1 2 3 4 5 6 7 8 9 10)} | |
488 | guile> @kbd{(reverse ls)} | |
489 | @result{(10 9 8 7 6 5 4 3 2 1)} | |
490 | ;; @r{ask if 12 is in the list --- it obviously is not} | |
491 | guile> @kbd{(memq 12 ls)} | |
492 | @result{#f} | |
493 | ;; @r{ask if 4 is in the list --- returns the list from 4 on.} | |
494 | ;; @r{Notice that the result will behave as true in conditionals} | |
495 | guile> @kbd{(memq 4 ls)} | |
496 | @result{(4 5 6 7)} | |
497 | ;; @r{an @code{if} statement using the aforementioned result} | |
498 | guile> @kbd{(if (memq 4 ls) | |
499 | (display "hey, it's true!\n") | |
500 | (display "dude, it's false\n"))} | |
501 | @print{hey, it's true!} | |
502 | @result{} | |
503 | guile> @kbd{(if (memq 12 ls) | |
504 | (display "hey, it's true!\n") | |
505 | (display "dude, it's false\n"))} | |
506 | @print{dude, it's false} | |
507 | @result{} | |
508 | guile> @kbd{(memq 4 (reverse ls))} | |
509 | @result{(4 3 2 1)} | |
510 | ;; @r{make a smaller list @code{ls2} to work with} | |
511 | guile> @kbd{(define ls2 (list 2 3 4))} | |
512 | ;; @r{make a list in which the function @code{sin} has been} | |
513 | ;; @r{applied to all elements of @code{ls2}} | |
514 | guile> @kbd{(map sin ls2)} | |
515 | @result{(0.909297426825682 0.141120008059867 -0.756802495307928)} | |
516 | ;; @r{make a list in which the squaring function has been} | |
517 | ;; @r{applied to all elements of @code{ls}} | |
518 | guile> @kbd{(map (lambda (n) (expt n n)) ls)} | |
519 | @result{(1 4 27 256 3125 46656 823543)} | |
520 | @end smalllisp | |
521 | ||
522 | @smalllisp | |
523 | ;; @r{make a vector and bind it to the symbol @code{v}} | |
524 | guile> @kbd{(define v #(1 2 3 4 5 6 7))} | |
525 | guile> @kbd{v} | |
526 | @result{#(1 2 3 4 5 6 7)} | |
527 | guile> @kbd{(vector? v)} | |
528 | @result{#t} | |
529 | guile> @kbd{(list? v)} | |
530 | @result{#f} | |
531 | guile> @kbd{(vector-length v)} | |
532 | @result{7} | |
533 | ;; @r{vector-ref allows you to pick out elements by index} | |
534 | guile> @kbd{(vector-ref v 2)} | |
535 | @result{3} | |
536 | ;; @r{play around with the vector: make it into a list, reverse} | |
537 | ;; @r{the list, go back to a vector and take the second element} | |
538 | guile> @kbd{(vector-ref (list->vector (reverse (vector->list v))) 2)} | |
539 | @result{5} | |
540 | ;; @r{this demonstrates that the entries in a vector do not have} | |
541 | ;; @r{to be of uniform type} | |
542 | guile> @kbd{(vector-set! v 4 "hi there")} | |
543 | @result{"hi there"} | |
544 | guile> @kbd{v} | |
545 | @result{#(1 2 3 4 "hi there" 6 7)} | |
546 | @end smalllisp | |
547 | ||
548 | ||
549 | @subsection Using recursion to process lists | |
550 | @cindex recursion | |
551 | @cindex list processing | |
552 | ||
553 | Here are some typical examples of using recursion to process a list. | |
554 | ||
555 | @smalllisp | |
556 | ;; @r{this is a rather trivial way of reversing a list} | |
557 | (define (my-reverse l) | |
558 | (if (null? l) | |
559 | l | |
560 | (append (my-reverse (cdr l)) (list (car l))))) | |
561 | (my-reverse '(27 32 33 40)) | |
562 | @result{(40 33 32 27)} | |
563 | @end smalllisp | |
564 | ||
565 | ||
566 | @subsection Processing matrices | |
567 | ||
568 | Suppose you have a matrix represented as a list of lists: | |
569 | ||
570 | @smalllisp | |
571 | (define m | |
572 | (list | |
573 | (list 7 2 1 3 2 8 5 3 6) | |
574 | (list 4 1 1 1 3 8 9 8 1) | |
575 | (list 5 5 4 8 1 8 2 2 4))) | |
576 | @end smalllisp | |
577 | ||
578 | Then you could apply a certain function to each element of the matrix in | |
579 | the following manner: | |
580 | @smalllisp | |
581 | ;; @r{apply the function func to the matrix m element-by-element;} | |
582 | ;; @r{return a matrix with the result.} | |
583 | (define (process-matrix m func) | |
584 | (map (lambda (l) | |
585 | (map func l)) | |
586 | m)) | |
587 | @end smalllisp | |
588 | Notice that I have used the Scheme @code{map} procedure because I am | |
589 | interested in the matrix that results from the application of | |
590 | @code{func}, rather than in the side effects associated with applying | |
591 | @code{func}. | |
592 | ||
593 | This could be invoked with @code{(process-matrix m sin)} or | |
594 | @code{(process-matrix m (lambda (x) (* x x)))}; for example: | |
595 | ||
596 | @smalllisp | |
597 | (process-matrix m (lambda (x) (* x x))) | |
598 | @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))} | |
599 | @end smalllisp | |
600 | ||
601 | To print a representation of the matrix, we could define a generalized | |
602 | routine: | |
603 | @smalllisp | |
604 | ;; @r{proc is a procedure to represent the single element,} | |
605 | ;; @r{row-proc is a procedure that is invoked after each row.} | |
606 | ;; @r{Example: proc could be (lambda (x) (begin (display x) (display " ")))} | |
607 | ;; @r{and row-proc could be (lambda (l) (display "\n"))} | |
608 | (define (represent-matrix m proc row-proc) | |
609 | (for-each (lambda (l) | |
610 | (begin | |
611 | (for-each proc l) | |
612 | (row-proc l))) | |
613 | m)) | |
614 | @end smalllisp | |
615 | @findex represent-matrix | |
616 | ||
617 | And then invoke it with | |
618 | @smalllisp | |
619 | (represent-matrix m | |
620 | (lambda (x) (begin (display x) (display " "))) | |
621 | (lambda (l) (begin (display "\n")))) | |
622 | @print{7 2 1 3 2 8 5 3 6} | |
623 | @print{4 1 1 1 3 8 9 8 1} | |
624 | @print{5 5 4 8 1 8 2 2 4} | |
625 | @end smalllisp | |
626 | ||
627 | @cindex objects | |
628 | ||
629 | Now we write a helper routine that uses Scheme @dfn{closures} to make | |
630 | objects with state that then receive messages to draw little squares. | |
631 | @cindex closures | |
632 | @cindex syntactic closures | |
633 | ||
634 | But let us take it one step at a time. I will start by showing you a | |
635 | simple example of object in Scheme. The object I make here represents a | |
636 | cell, which could be a cell in a matrix. The cell responds to commands | |
637 | to draw itself, to return the next cell, and so forth. @emph{Guile does | |
638 | not currently have a Tk interface, so I will leave the hooks for | |
639 | graphical rendering. In a future release of Guile I will add graphical | |
640 | rendering messages to the cell object.} | |
641 | ||
642 | @smallexample | |
643 | ;; @r{cell-object.scm: routines for creating and manipulating cell objects} | |
644 | ||
645 | ;; @r{(the-x, the-y) is the initial position of the cell.} | |
646 | ;; @r{the-color is a string representing a color; must be something Tk can grok.} | |
647 | ;; @r{square-size is the size of the square that gets drawn.} | |
648 | ;; @r{(sizex, sizey) is the size of the matrix.} | |
649 | (define (MAKE-CELL the-x the-y the-color square-size sizex sizey) | |
650 | (define (get-x) the-x) | |
651 | (define (get-y) the-y) | |
652 | ||
653 | (define (set-x! new-x) | |
654 | (set! the-x new-x) | |
655 | the-x) | |
656 | (define (set-y! new-y) | |
657 | (set! the-y new-y) | |
658 | the-y) | |
659 | (define (get-color) the-color) | |
660 | (define (set-color! new-color) | |
661 | (set! the-color new-color) | |
662 | the-color) | |
663 | (define (next!) | |
664 | (set! the-x (+ the-x 1)) | |
665 | (if (>= the-x sizex) | |
666 | (begin | |
667 | (set! the-x 0) | |
668 | (set! the-y (+ the-y 1)))) | |
669 | (if (>= the-y sizey) | |
670 | (begin | |
671 | (display "CELL next!: value of y is too big; not changing it\n") | |
672 | (set! the-y (- the-y 1)))) | |
673 | (cons the-x the-y)) | |
674 | (define (draw) | |
675 | (let* ((x0 (* the-x square-size)) | |
676 | (y0 (* the-y square-size)) | |
677 | (x1 (+ x0 square-size)) | |
678 | (y1 (+ y0 square-size))) | |
679 | (display "I should draw a ") | |
680 | (display the-color) | |
681 | (display " rectangle with corners at ") | |
682 | (display x0) (display y0) (display x1) (display y1) | |
683 | )) | |
684 | ||
685 | ;; self is the dispatch procedure | |
686 | (define (self message) | |
687 | (case message | |
688 | ((x) get-x) | |
689 | ((y) get-y) | |
690 | ((set-x!) set-x!) | |
691 | ((set-y!) set-y!) | |
692 | ((color) get-color) | |
693 | ((set-color!) set-color!) | |
694 | ((next!) next!) | |
695 | ((draw) draw) | |
696 | (else (error "CELL: Unknown message -> " message)))) | |
697 | ;; and now return the dispatch procedure | |
698 | self | |
699 | ) | |
700 | @end smallexample | |
701 | @cindex cell-object | |
702 | @findex MAKE-CELL | |
703 | ||
704 | What does this procedure do? It returns another procedure | |
705 | (@code{self}) which receives a message (x, y, set-x!, set-y!, @dots{}) | |
706 | and takes an action to return or modify its state. The state consists | |
707 | of the values of variables @code{the-x}, @code{the-y}, @code{the-color} | |
708 | and so forth. | |
709 | ||
710 | Here are some examples of how to use MAKE-CELL and the cell object it | |
711 | creates: | |
712 | @smallexample | |
713 | (define c (MAKE-CELL 0 0 "red" 10 7 9)) | |
714 | ||
715 | ;; @r{retrieve the x and y coordinates} | |
716 | ((c 'x)) | |
717 | @result{0} | |
718 | ((c 'y)) | |
719 | @result{0} | |
720 | ;; @r{change the x coordinate} | |
721 | ((c 'set-x!) 5) | |
722 | @result{5} | |
723 | ((c 'x)) | |
724 | @result{5} | |
725 | ;; @r{change the color} | |
726 | ((c 'color)) | |
727 | @result{"red"} | |
728 | ((c 'set-color!) "green") | |
729 | @result{"green"} | |
730 | ((c 'color)) | |
731 | @result{"green"} | |
732 | ;; @r{now use the next! message to move to the next cell} | |
733 | ((c 'next!)) | |
734 | @result{(6 . 0)} | |
735 | ((c 'x)) | |
736 | @result{6} | |
737 | ((c 'y)) | |
738 | @result{0} | |
739 | ;; @r{now make things wrap around} | |
740 | ((c 'next!)) | |
741 | @result{(0 . 1)} | |
742 | ((c 'next!)) | |
743 | @result{(1 . 1)} | |
744 | ((c 'next!)) | |
745 | @result{(2 . 1)} | |
746 | ((c 'x)) | |
747 | @result{2} | |
748 | ((c 'y)) | |
749 | @result{1} | |
750 | @end smallexample | |
751 | ||
752 | You will notice that expressions like @code{(c 'next)} return procedures | |
753 | that do the job, so we have to use extra parentheses to make the job | |
754 | happen. This syntax is rather awkward; one way around it is to define a | |
755 | @code{send} procedure: | |
756 | ||
757 | @smallexample | |
758 | ;; @r{send makes object syntax a bit easier; instead of saying} | |
759 | ;; @r{ ((my-cell 'set-x!) 4)} | |
760 | ;; @r{you can say} | |
761 | ;; @r{ (send my-cell 'set-x! 4)} | |
762 | (define (send obj . args) | |
763 | (let ((first-eval (apply obj (list (car args))))) | |
764 | (if (null? (cdr args)) | |
765 | (first-eval) | |
766 | (apply first-eval (cdr args))))) | |
767 | @end smallexample | |
768 | @findex send | |
769 | ||
770 | You can see that @code{send} passes the message to the object, making | |
771 | sure that things are evaluated the proper number of times. You can now | |
772 | type: | |
773 | ||
774 | @smallexample | |
775 | (define c2 (MAKE-CELL 0 0 "red" 10 7 9)) | |
776 | (send c2 'x) | |
777 | @result{0} | |
778 | (send c2 'set-x! 5) | |
779 | @result{5} | |
780 | (send c2 'color) | |
781 | @result{"red"} | |
782 | (send c2 'set-color! "green") | |
783 | @result{"green"} | |
784 | (send c2 'next!) | |
785 | @result{(1 . 0)} | |
786 | (send c2 'x) | |
787 | @result{1} | |
788 | (send c2 'y) | |
789 | @result{0} | |
790 | @end smallexample | |
791 | ||
792 | @cindex object-based programming | |
793 | @cindex object-oriented programming | |
794 | ||
795 | This is the simplest way of implementing objects in Scheme, but it does | |
796 | not really allow for full @emph{object-oriented programming} (for | |
797 | example, there is no inheritance). But it is useful for | |
798 | @emph{object-based programming}. | |
799 | ||
800 | Guile comes with a couple more complete object-oriented extensions to | |
801 | Scheme: these are part of slib (@pxref{Object, , , slib, SLIB: the | |
802 | portable Scheme library} and @pxref{Yasos, , , slib, SLIB: the portable | |
803 | Scheme library}). | |
804 | ||
805 | @node Guile in a Library | |
806 | @chapter Guile in a Library | |
807 | ||
808 | @iftex | |
809 | @nobreak | |
810 | @end iftex | |
811 | In the previous chapters Guile was used to write programs entirely in | |
812 | Scheme, and no C code was seen; but I have been claiming @emph{ad | |
813 | nauseam} that Guile is an @emph{extension} language. Here we see how | |
814 | that is done, and how that can be useful. | |
815 | @cindex libguile | |
816 | @cindex extending C programs | |
817 | ||
818 | ||
819 | @menu | |
820 | * Two world views:: | |
821 | * What is libguile:: | |
822 | * How to get started with libguile:: | |
823 | * More interesting programming with libguile:: | |
824 | * Further examples:: | |
825 | @end menu | |
826 | ||
827 | @node Two world views | |
828 | @section Two world views | |
829 | @cindex master world | |
830 | ||
831 | In this manual, I usually jump into examples and explain them as you | |
832 | type in the code; here I will digress and ramble for a few paragraphs to | |
833 | set some concepts straight, and then let you type (or paste) in fun | |
834 | examples. | |
835 | ||
836 | In 1995, I implemented a large program, @dfn{Gnudl}, using Guile quite | |
837 | extensively. In the design phase of Gnudl, I found I had to make a | |
838 | choice: should the fundamental data structures be C or Scheme data | |
839 | structures? | |
840 | @cindex gnudl | |
841 | @cindex GNU Data Language | |
842 | @cindex Galassi, Mark | |
843 | ||
844 | Guile allows C to see its data structures (scalar types, lists, vectors, | |
845 | strings @dots{}). C also allows Guile to see its data structures. As a | |
846 | large program designer, you have to decide which of those capabilities | |
847 | to use. You have two main choices: | |
848 | ||
849 | @enumerate 1 | |
850 | @item | |
851 | You can write your software mostly in Scheme. In this case, your C | |
852 | software will mostly parse the Scheme code with Guile calls, and provide | |
853 | some new primitive procedures to be used by Scheme. This is what Gnudl | |
854 | does. | |
855 | ||
856 | @item | |
857 | You can write your software mostly in C, occasionally allowing Scheme | |
858 | code to be parsed by Guile, either to allow the user to modify data | |
859 | structures, or to parse a configuration file, @dots{} | |
860 | @end enumerate | |
861 | ||
862 | Mixing the two approaches seems unwise: the overall layout would be | |
863 | confusing. But who knows? There might be problems that are best solved | |
864 | by a hybrid approach. Please let me know if you think of such a | |
865 | problem. | |
866 | ||
867 | If you use the former approach, we will say that the @dfn{master world} | |
868 | is Scheme, and the C routines serve Scheme and access Scheme data | |
869 | structures. In the latter case, the master world is C, and Scheme | |
870 | routines serve the C code and access C data structures. | |
871 | ||
872 | In both approaches the @code{libguile.a} library is the same, but a | |
873 | predominantly different set of routines will be used. When we go | |
874 | through examples of libguile use, we will point out which is the master | |
875 | world in order to clarify these two approaches. | |
876 | ||
877 | ||
878 | @node What is libguile | |
879 | @section What is libguile | |
880 | @cindex libguile | |
881 | @cindex gh interface | |
882 | @cindex scm interface | |
883 | ||
884 | @dfn{Libguile} is the library which allows C programs to start a Scheme | |
885 | interpreter and execute Scheme code. There are also facilities in | |
886 | libguile to make C data structures available to Scheme, and vice versa. | |
887 | ||
888 | The interface provided by the libguile C library is somewhat specific to | |
889 | the implementation of the Scheme interpreter. This low-level libguile | |
890 | interface is usually referred to as the @code{scm_} interface, since its | |
891 | public calls (API) all have the @code{scm_} prefix. | |
892 | ||
893 | There is also a higher-level libguile interface, which is usually | |
894 | referred to as the @code{gh_} interface (libGuile High). Its public | |
895 | calls all have the @code{gh_} prefix. The @code{gh_} library interface | |
896 | is designed to hide the implementation details, thus making it easier to | |
897 | assimilate and portable to other underlying Scheme implementations. | |
898 | ||
899 | People extending Guile by adding bindings to C libraries (like OpenGL or | |
900 | Rx) are encouraged to use the @code{gh_} interface, so their work will | |
901 | be portable to other Scheme systems. The @code{gh_} interface should be | |
902 | more stable, because it is simpler. | |
903 | ||
904 | The @code{scm_} interface is necessary if you want to poke into the | |
905 | innards of Scheme data structures, or do anything else that is not | |
906 | offered by the @code{gh_} interface. It is not covered in this | |
907 | tutorial, but is covered extensively in @ref{Scheme data representation, | |
908 | Guile Reference Manual, guile-ref, Guile Reference Manual}. | |
909 | ||
910 | This chapter gives a gentle introduction to the @code{gh_} interface, | |
911 | presenting some @emph{hello world}-style programs which I wrote while | |
912 | teaching myself to use libguile. | |
913 | @cindex hello world | |
914 | ||
915 | The @cite{Guile Programmer's Manual} gives more examples of programs | |
916 | written using libguile, illustrating diverse applications. You can also | |
917 | consult my @emph{Gnudl} documentation at | |
918 | @url{http://nis-www.lanl.gov/~rosalia/mydocs/} to see a large scale | |
919 | project that uses C and Scheme code together. | |
920 | ||
921 | ||
922 | @node How to get started with libguile | |
923 | @section How to get started with libguile | |
924 | @cindex learn0 | |
925 | ||
926 | Here is an elementary first program, @code{learn0}, to get going with | |
927 | libguile. The program (which uses Scheme as a master world) is in a | |
928 | single source file, @code{learn0.c}: | |
929 | ||
930 | @smallexample | |
931 | /* @r{test the new libgh.a (Guile High-level library) with a trivial | |
932 | program} */ | |
933 | ||
934 | #include <stdio.h> | |
935 | ||
936 | #include <guile/gh.h> | |
937 | ||
938 | void main_prog(int argc, char *argv[]); | |
939 | ||
940 | main(int argc, char *argv[]) | |
941 | @{ | |
942 | gh_enter(argc, argv, main_prog); | |
943 | @} | |
944 | ||
945 | void main_prog(int argc, char *argv[]) | |
946 | @{ | |
947 | int done; | |
948 | char input_str[200]; | |
949 | ||
950 | gh_eval_str("(display \"hello Guile\")"); | |
951 | gh_eval_str("(newline)"); | |
952 | ||
953 | /* @r{for fun, evaluate some simple Scheme expressions here} */ | |
954 | gh_eval_str("(define (square x) (* x x))"); | |
955 | gh_eval_str("(define (fact n) (if (= n 1) 1 (* n (fact (- n 1)))))"); | |
956 | gh_eval_str("(square 9)"); | |
957 | ||
958 | /* @r{now sit in a Scheme eval loop: I input the expressions, have | |
959 | Guile evaluate them, and then get another expression.} */ | |
960 | done = 0; | |
961 | fputs("learn0> ", stdout); | |
962 | while (fgets(input_str, 199, stdin) != NULL) @{ | |
963 | gh_eval_str(input_str); | |
964 | fputs("\nlearn0> ", stdout); | |
965 | @} | |
966 | ||
967 | exit(0); | |
968 | @} | |
969 | @end smallexample | |
970 | ||
971 | If you name this program @code{learn0.c}, it can now be compiled with: | |
972 | @smallexample | |
973 | gcc -g -c learn0.c -o learn0.o | |
974 | gcc -o learn0 learn0.o -lguile -lm | |
975 | @end smallexample | |
976 | ||
977 | @c @emph{NOTE: If you are in the Guile development tree, you can simply do | |
978 | @c ``cd doc/examples/c; make; ./learn0''.} | |
979 | ||
980 | The program is simple: it creates a Scheme interpreter, passes a couple | |
981 | of strings to it that define new Scheme functions @code{square} and | |
982 | @code{factorial}, and then a couple of strings that invoke those | |
983 | functions. | |
984 | ||
985 | It then goes into a read-eval-print-loop (REPL), so you could type | |
986 | one-line Scheme expressions to it and have them evaluated. For example: | |
987 | @smallexample | |
988 | <shell-prompt> ./learn0 | |
989 | hello Guile | |
990 | learn0> (display (sin 1.3)) | |
991 | 963.558185417193e-3 | |
992 | learn0> (display (fact 10)) | |
993 | 3628800 | |
994 | learn0> (quit) | |
995 | <shell-prompt> | |
996 | @end smallexample | |
997 | ||
998 | You should notice the key steps involved in this @code{learn0} program: | |
999 | ||
1000 | @cartouche | |
1001 | @enumerate | |
1002 | @item | |
1003 | @code{#include <guile/gh.h>} | |
1004 | @item | |
1005 | You need to invoke the initialization routine @code{gh_enter()}. This | |
1006 | starts up a Scheme interpreter, handling many implementation-specific | |
1007 | details. | |
1008 | @item | |
1009 | Your main() function should be almost empty: the real main program goes | |
1010 | in a separate function main_prog() which is passed to gh_enter(). This | |
1011 | rather arcane convention is due to the way Guile's garbage collector | |
1012 | works: the whole program has to run in the dynamic context of | |
1013 | @code{gh_enter()}. | |
1014 | @item | |
1015 | You pass strings to the Scheme interpreter with the @code{gh_eval_str()} | |
1016 | routine. | |
1017 | @item | |
1018 | You link your program with @code{-lguile}. | |
1019 | @end enumerate | |
1020 | @end cartouche | |
1021 | ||
1022 | ||
1023 | @node More interesting programming with libguile | |
1024 | @section More interesting programming with libguile | |
1025 | @cindex learn1 | |
1026 | @cindex callback | |
1027 | @cindex builtin functions | |
1028 | ||
1029 | The @code{learn0} program shows how you can invoke Scheme commands from | |
1030 | a C program. This is not such a great achievement: the same could have | |
1031 | been done by opening a pipe to SCM or any other Scheme interpreter. | |
1032 | ||
1033 | A true extension language must allow @dfn{callbacks}. Callbacks allow | |
1034 | you to write C routines that can be invoked as Scheme procedures, thus | |
1035 | adding new primitive procedures to Scheme. This also means that a | |
1036 | Scheme procedure can modify a C data structure. | |
1037 | ||
1038 | Guile allows you to define new Scheme procedures in C, and provides a | |
1039 | mechanism to go back and forth between C and Scheme data types. | |
1040 | ||
1041 | Here is a second program, @code{learn1}, which demonstrates these | |
1042 | features. It is split into three source files: @code{learn1.c}, | |
1043 | @code{c_builtins.h} and @code{c_builtins.c}. I am including the code | |
1044 | here. | |
1045 | @c , but you might just want to look at the online source code and the | |
1046 | @c Makefile.am that come with Guile in the | |
1047 | @c @file{doc/examples/c} directory. | |
1048 | ||
1049 | Notice that @code{learn1} uses a Scheme master world, and the C routines | |
1050 | in @code{c_builtins.c} are simply adding new primitives to Scheme. | |
1051 | ||
1052 | @menu | |
1053 | * learn1.c:: | |
1054 | * c_builtins.h:: | |
1055 | * c_builtins.c:: | |
1056 | * What learn1 is doing:: | |
1057 | * Compiling and running learn1:: | |
1058 | @end menu | |
1059 | ||
1060 | @node learn1.c | |
1061 | @subsection learn1.c | |
1062 | ||
1063 | Here is @file{learn1.c}: | |
1064 | @smallexample | |
1065 | #include <stdio.h> | |
1066 | ||
1067 | #include <guile/gh.h> | |
1068 | ||
1069 | #include "c_builtins.h" | |
1070 | ||
1071 | void main_prog(int argc, char *argv[]); | |
1072 | ||
1073 | main(int argc, char *argv[]) | |
1074 | @{ | |
1075 | gh_enter(argc, argv, main_prog); | |
1076 | @} | |
1077 | ||
1078 | void main_prog(int argc, char *argv[]) | |
1079 | @{ | |
1080 | char input_str[200]; /* @r{ugly hack: assume strlen(line) < 200} */ | |
1081 | int done; | |
1082 | ||
1083 | /* @r{for fun, evaluate some simple Scheme expressions here} */ | |
1084 | gh_eval_str("(define (square x) (* x x))"); | |
1085 | gh_eval_str("(define (fact n) (if (= n 1) 1 (* n (fact (- n 1)))))"); | |
1086 | gh_eval_str("(square 9)"); | |
1087 | gh_eval_str("(fact 100)"); | |
1088 | ||
1089 | /* @r{now try to define some new builtins, coded in C, so that they are | |
1090 | available in Scheme.} */ | |
1091 | gh_new_procedure1_0("c-factorial", c_factorial); | |
1092 | gh_new_procedure1_0("c-sin", c_sin); | |
1093 | gh_new_procedure1_0("v-t", vector_test); | |
1094 | ||
1095 | /* @r{now sit in a Scheme eval loop: I input the expressions, have | |
1096 | Guile evaluate them, and then get another expression.} */ | |
1097 | done = 0; | |
1098 | fputs("learn1> ", stdout); | |
1099 | while (!done) @{ | |
1100 | if (gets(input_str) == NULL) @{ | |
1101 | done = 1; | |
1102 | @} else @{ | |
1103 | gh_eval_str(input_str); | |
1104 | fputs("learn1> ", stdout); | |
1105 | @} | |
1106 | @} | |
1107 | ||
1108 | exit(0); | |
1109 | @} | |
1110 | @end smallexample | |
1111 | ||
1112 | @node c_builtins.h | |
1113 | @subsection c_builtins.h | |
1114 | ||
1115 | Here is @file{c_builtins.h}: | |
1116 | @smallexample | |
1117 | /* @r{builtin function prototypes} */ | |
1118 | ||
1119 | #include <guile/gh.h> | |
1120 | ||
1121 | SCM c_factorial(SCM n); | |
1122 | SCM c_sin(SCM n); | |
1123 | SCM vector_test(SCM s_length); | |
1124 | @end smallexample | |
1125 | ||
1126 | @node c_builtins.c | |
1127 | @subsection c_builtins.c | |
1128 | ||
1129 | Here is @file{c_builtins.c}: | |
1130 | @smallexample | |
1131 | #include <stdio.h> | |
1132 | #include <math.h> | |
1133 | ||
1134 | #include <guile/gh.h> | |
1135 | ||
1136 | #include "c_builtins.h" | |
1137 | ||
1138 | /* @r{this is a factorial routine in C, made to be callable by Scheme} */ | |
1139 | SCM c_factorial(SCM s_n) | |
1140 | @{ | |
1141 | int i; | |
1142 | unsigned long result = 1, n; | |
1143 | ||
1144 | n = gh_scm2ulong(s_n); | |
1145 | ||
1146 | gh_defer_ints(); | |
1147 | for (i = 1; i <= n; ++i) @{ | |
1148 | result = result*i; | |
1149 | @} | |
1150 | gh_allow_ints(); | |
1151 | return gh_ulong2scm(result); | |
1152 | @} | |
1153 | ||
1154 | /* @r{a sin routine in C, callable from Scheme. it is named c_sin() to | |
1155 | distinguish it from the default Scheme sin function} */ | |
1156 | SCM c_sin(SCM s_x) | |
1157 | @{ | |
1158 | double x = gh_scm2double(s_x); | |
1159 | ||
1160 | return gh_double2scm(sin(x)); | |
1161 | @} | |
1162 | ||
1163 | /* @r{play around with vectors in Guile: this routine creates a vector of | |
1164 | the given length, initializes it all to zero except element 2 which | |
1165 | is set to 1.9.} */ | |
1166 | SCM vector_test(SCM s_length) | |
1167 | @{ | |
1168 | SCM xvec; | |
1169 | ||
1170 | c_length = gh_scm2ulong(s_length); | |
1171 | printf("requested length for vector: %ld\n", gh_scm2ulong(s_length)); | |
1172 | ||
1173 | /* create a vector */ | |
1174 | xvec = gh_make_vector(s_length, gh_double2scm(0.0)); | |
1175 | /* set the second element in it */ | |
1176 | gh_vector_set_x(xvec, gh_int2scm(2), gh_double2scm(1.9)); | |
1177 | ||
1178 | return xvec; | |
1179 | @} | |
1180 | @end smallexample | |
1181 | ||
1182 | @node What learn1 is doing | |
1183 | @subsection What learn1 is doing | |
1184 | @cindex registering callbacks | |
1185 | @cindex registering C functions | |
1186 | @cindex primitive procedures | |
1187 | ||
1188 | If you compare learn1 to learn0, you will find that learn1 uses a new | |
1189 | Guile construct: the function @code{gh_new_procedure()}, and its | |
1190 | siblings: | |
1191 | ||
1192 | @smallexample | |
1193 | /* @r{now try to define some new builtins, coded in C, so that they are | |
1194 | available in Scheme.} */ | |
1195 | gh_new_procedure1_0("c-factorial", c_factorial); | |
1196 | gh_new_procedure1_0("c-sin", c_sin); | |
1197 | gh_new_procedure1_0("v-t", vector_test); | |
1198 | @end smallexample | |
1199 | ||
1200 | It is clear that @code{gh_new_procedure()} adds a new builtin | |
1201 | routine written in C which can be invoked from Scheme. We can now | |
1202 | revise our checklist for programming with libguile, so it includes | |
1203 | adding callbacks. | |
1204 | @cindex libguile - step by step | |
1205 | ||
1206 | @cartouche | |
1207 | @enumerate | |
1208 | @item | |
1209 | @code{#include <guile/gh.h>} | |
1210 | @item | |
1211 | You need to invoke the initialization routine @code{gh_enter()}. This | |
1212 | starts up a Scheme interpreter, handling many details. | |
1213 | @item | |
1214 | Your main() function should be almost empty: the real main program goes | |
1215 | in a separate function main_prog() which is passed to gh_enter(). This | |
1216 | rather arcane convention is due to the way Guile's garbage collector | |
1217 | works: the whole program has to run in the dynamic context of | |
1218 | @code{gh_enter()}. | |
1219 | @item | |
1220 | You pass strings to the Scheme interpreter with the @code{gh_eval_str()} | |
1221 | routine. | |
1222 | @item | |
1223 | @strong{[new]} You can now define new builtin Scheme functions; | |
1224 | i.e. define new builtin Scheme functions, with the | |
1225 | @code{gh_new_procedure()} routine. | |
1226 | @item | |
1227 | You pass strings to the Scheme interpreter with the | |
1228 | @code{gh_eval_str()} routine. | |
1229 | @item | |
1230 | You link your program with @code{-lguile}. | |
1231 | @end enumerate | |
1232 | @end cartouche | |
1233 | ||
1234 | I breezed by the issue of how to write your C routines that are | |
1235 | registered to be called from Scheme. This is non-trivial, and is | |
1236 | discussed at length in the @cite{Guile Programmer's Manual}. | |
1237 | ||
1238 | ||
1239 | @node Compiling and running learn1 | |
1240 | @subsection Compiling and running learn1 | |
1241 | ||
1242 | @smallexample | |
1243 | gcc -g -c learn1.c -o learn1.o | |
1244 | gcc -g -c c_builtins.c -o c_builtins.o | |
1245 | gcc -o learn1 learn1.o c_builtins.o -lguile -lm | |
1246 | @end smallexample | |
1247 | ||
1248 | If you run @code{learn1}, it will prompt you for a one-line Scheme | |
1249 | expression, just as @code{learn0} did. The difference is that you can | |
1250 | use the new C builtin procedures (@code{c-factorial}, @code{c-sin}, | |
1251 | @code{v-t}). | |
1252 | ||
1253 | @smallexample | |
1254 | <shell-prompt> ./learn1 | |
1255 | welcome to Guile | |
1256 | hello Guile | |
1257 | learn1> (display (c-factorial 6)) | |
1258 | 720 | |
1259 | learn1> (display (c-factorial 20)) | |
1260 | 2192834560 | |
1261 | learn1> (display (c-factorial 100)) | |
1262 | 0 | |
1263 | learn1> (display (c-sin 1.5)) | |
1264 | 0.997494986604054 | |
1265 | learn1> (display (v-t 10)) | |
1266 | requested length for vector: 10 | |
1267 | #(0.0 0.0 1.9 0.0 0.0 0.0 0.0 0.0 0.0 0.0) | |
1268 | learn1> (display (v-t 15)) | |
1269 | requested length for vector: 15 | |
1270 | #(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) | |
1271 | learn1> (quit) | |
1272 | <shell-prompt> | |
1273 | @end smallexample | |
1274 | ||
1275 | As you see, taking @code{(c-factorial 100)} does not use bignumbers and | |
1276 | returns a bogus answer. | |
1277 | ||
1278 | @node Further examples | |
1279 | @section Further examples | |
1280 | ||
1281 | Further ``idealized'' examples are included in the @code{doc/examples/c} | |
1282 | distribution. They include programs to: | |
1283 | ||
1284 | @c [FIXME: still have to write some of these; then I will revise the list.] | |
1285 | ||
1286 | @itemize @bullet | |
1287 | @item | |
1288 | Parse a startup file (C is the master world). | |
1289 | @item | |
1290 | Set up initial conditions for an n-body simulation (C is the master | |
1291 | world). | |
1292 | @item | |
1293 | Implement a Scheme interpreter with all of Guile's goodies, @emph{plus} | |
1294 | the readline library @emph{and} a fast Fourier transform routine | |
1295 | provided in C (Scheme is the master world). | |
1296 | @end itemize | |
1297 | ||
1298 | @node Regular Expression Support | |
1299 | @chapter Regular Expression Support | |
1300 | ||
1301 | @node UNIX System Programming | |
1302 | @chapter UNIX System Programming | |
1303 | ||
1304 | @node Where to find more Guile/Scheme resources | |
1305 | @chapter Where to find more Guile/Scheme resources | |
1306 | ||
1307 | ||
1308 | @node Concept Index | |
1309 | @unnumbered Concept Index | |
1310 | ||
1311 | @printindex cp | |
1312 | ||
1313 | @node Procedure and Macro Index | |
1314 | @unnumbered Procedure and Macro Index | |
1315 | ||
1316 | This is an alphabetical list of all the procedures and macros in Dominion. | |
1317 | ||
1318 | @printindex fn | |
1319 | ||
1320 | @node Variable Index | |
1321 | @unnumbered Variable Index | |
1322 | ||
1323 | This is an alphabetical list of the major global variables in Dominion. | |
1324 | ||
1325 | @printindex vr | |
1326 | ||
1327 | @node Type Index | |
1328 | @unnumbered Type Index | |
1329 | ||
1330 | This is an alphabetical list of the major data structures in Dominion. | |
1331 | ||
1332 | @printindex tp | |
1333 | ||
1334 | @contents | |
1335 | ||
1336 | @bye |