source: project/wiki/new-chapter1 @ 8639

Last change on this file since 8639 was 8639, checked in by svnwiki, 12 years ago

Changes applied for Vincent Manis (24.84.33.56) through svnwiki:

Proposed new Chapter 1 of the Chicken manual.

File size: 20.9 KB
Line 
1== Getting started with Chicken
2
3TODO: this page is a revision and expansion of the existing Chapter 1
4of the Chicken manual. The goal is to give an overview of the whole
5system, and to give the new user some recipes for common use cases.
6I know this is somewhat verbose, and would be happy to eliminate
7unnecessary verbiage, but I do think the content shown here is
8worthwhile. Your mileage, of course, might vary :-) -- vincent
9
10''(This document describes version 3.0.0)'' TODO: the version number
11should be moved from here to the cover or index page.
12
13'''Chicken is a compiler that translates Scheme source files into
14C''', which in turn can be fed to a C compiler to generate a
15standalone executable.  An interpreter is also available and can be
16used as a scripting environment or for testing programs before
17compilation.
18
19This chapter is designed to get you started with Chicken programming,
20describing what it is and what it will do for you, and covering basic
21use of the system. With almost everything discussed here, there is
22more to the story, which the remainder of the manual reveals. Here, we
23only cover enough to get you started. Nonetheless, someone who knows
24Scheme already should be able to use this chapter as the basis for
25writing and running small Chicken programs.
26
27=== Scheme
28
29Scheme is a member of the Lisp family of languages, of which Common
30Lisp and Emacs Lisp are the other two widely-known members. As with
31Lisp dialects, Scheme features
32
33* a wide variety of programming paradigms, including imperative,
34  functional, and object-oriented
35* a very simple syntax, based upon nested parenthesization
36* the ability to extend the language in meaningful and useful ways
37
38In contrast to Common Lisp, Scheme is very minimal, and tries to
39include only those features absolutely necessary in programming. In
40contrast to Emacs Lisp, Scheme is not anchored into any one program
41(Emacs), and has a somewhat more modern language design.
42
43Scheme is defined in a document called ''Revised Revised Revised
44Revised Revised Report on the Algorithmic Language Scheme'', referred
45to---for obvious reasons---as ``R5RS''. A newer report, ``R6RS'' was
46released in 2007, but this report has attracted considerable
47controversy, and not all Scheme implementations will be made compliant
48with it. Chicken essentially complies with R5RS.
49
50Even though Scheme is consciously minimalist, it is recognized that a
51language must be more than a minimal core in order to be
52useful. Accordingly, the Scheme community uses a process known as
53`Scheme Requests For Implementation' (SRFI, pronounced `SUR-fee') to
54define new language features. A typical Scheme system therefore
55complies with one of the Scheme reports plus some or all of the
56accepted SRFIs.
57
58A good starting point for Scheme knowledge is
59[[http://www.schemers.org]]. There you will find the defining reports,
60FAQs, lists of useful books and other resources, and the SRFIs.
61
62The Chicken community is at present developing tutorials for
63programmers who are new to Scheme but experienced with Python, Ruby,
64or other languages. These can be found on the Chicken wiki.
65
66=== Chicken
67
68Chicken is an implementation of Scheme that has many advantages.
69
70<blockquote>
71Chicken Scheme combines an optimising compiler with a reasonably fast
72interpreter.  It supports almost all of R5RS and the important SRFIs.
73The compiler generates portable C code that supports tail recursion,
74first-class continuations, and lightweight threads, and the interface to
75and from C libraries is flexible, efficient, and easy to use.  There are
76hundreds of contributed Chicken libraries that make the programmer's
77task easier.  The interpreter allows interactive use, fast prototyping,
78debugging, and scripting.  The active and helpful Chicken community
79fixes bugs and provides support.  Extensive documentation is supplied.
80</blockquote>
81
82Chicken includes
83
84* a Scheme interpreter that supports almost all of  R5RS Scheme, with
85  only a few relatively minor omissions, and with many extensions
86* a compatible compiler whose target is C, thus making porting to new
87  machines and architectures relatively straightforward
88** the C support allows Scheme code to include `embedded' C code,
89  thus making it relatively easy to invoke host OS or library
90  functions
91* a framework for language extensions, library modules that broaden
92  the functionality of the system
93
94This package is distributed under the '''BSD license''' and as such is free
95to use and modify.
96
97Scheme cognoscenti will appreciate the method of compilation and the
98design of the runtime-system, which follow closely Henry Baker's
99[[http://home.pipeline.com/~hbaker1/CheneyMTA.html|CONS Should Not
100CONS Its Arguments, Part II: Cheney on the M.T.A.]] paper and expose a
101number of interesting properties.
102
103* Consing (creation of data on the heap) is relatively inexpensive,
104  because a generational garbage collection scheme is used, in which
105  short-lived data structures are reclaimed extremely quickly.
106
107* Moreover, {{call-with-current-continuation}} is practically for free
108  and Chicken does not suffer under any performance penalties if
109  first-class continuations are used in complex ways.
110
111The generated C code is fully tail-recursive.
112
113Some of the features supported by Chicken:
114
115* SRFIs 0, 1, 2, 4, 6-19, 23, 25-31, 37-40, 42, 43, 45, 47, 55, 57,
116  60-63, 66, 69, 72, 78, 85 and 95.
117* Lightweight threads based on first-class continuations
118* Pattern matching with Andrew Wright's {{match}} package
119* Record structures
120* Extended comment- and string-literal syntaxes
121* Libraries for regular expressions, string handling
122* UNIX system calls and extended data structures
123* Create interpreted or compiled shell scripts written in Scheme for
124  UNIX or Windows
125* Compiled C files can be easily distributed
126* Allows the creation of fully self-contained statically linked executables
127* On systems that support it, compiled code can be loaded dynamically
128
129Chicken has been used in many environments ranging from embedded
130systems through desktop machines to large-scale server deployments. 
131The number of language extensions, or '''eggs''', will soon reach 400,
132including
133
134* extended language features
135* development tools, such as documentation generators, debugging, and
136  automated testing libraries
137* interfaces to other languages such as Java, Python, and Objective-C
138* interfaces to database systems, GUIs, and other large-scale
139  libraries,
140* network applications, such as servers and clients for ftp,
141  smtp/pop3, irc, and http 
142* web servers and related tools, including URL parsing, HTML
143  generation, AJAX, and HTTP session management
144* data formats, including XML, JSON, and Unicode support
145
146Chicken is supported by SWIG (Simplified Wrapper and Interface
147Generator), a tool that produces quick-and-dirty interface modules
148for C libraries ([[http://www.swig.org]]).
149
150This chapter provides you with an overview of the entire system, with
151enough information to get started writing and running small Scheme
152programs. Subsequent chapters cover
153
154* [[Basic mode of operation]]: Compiling Scheme files.
155
156* [[Using the compiler]]: Explains how to use Chicken to compile
157  programs and execute them.
158
159* [[Using the interpreter]]: Invocation and usage of {{csi}}, the
160  Chicken interpreter
161
162* [[Supported language]]: The language implemented by Chicken
163  (deviations from the standard and extensions).
164
165* [[Interface to external functions and variables]]: Accessing C and
166  C++ code and data.
167
168* [[chicken-setup]]: Packaging and installing extension libraries.
169
170* [[Data representation]]: How Scheme data is internally represented.
171
172* [[Bugs and limitations]]: Yes, there are some.
173
174* [[FAQ]]: A list of Frequently Asked Questions about Chicken (and
175  their answers!).
176
177* [[Acknowledgements]]: A list of some of the people that have
178  contributed to make Chicken what it is.
179
180* [[Bibliography]]: Links to documents that may be of interest.
181
182=== Installing Chicken
183
184Chicken is available in binary form for Windows and Linux/x86
185systems, and in source form for all other platforms. Refer to the
186{{README}} file in the distribution for instructions on installing it
187on your system.
188
189Because it compiles to C, Chicken requires that a C compiler be
190installed on your system. (If you're not writing embedded C code, you
191can pretty much ignore the C compiler once you have installed it.)
192
193* On a Linux system, the GNU Compiler Collection ({{gcc}}) should be
194  installed
195  as part of the basic operating system.
196* On Macintosh OS X, you will need the XCode tools, which are shipped
197  on the OS X DVD with recent versions of the operating system.
198* On Windows, you have three choices.
199** Cygwin ([[http://sources.redhat.com/cygwin]]) provides a
200  relatively full-featured Unix environment for Windows.
201** The GNU Compiler Collection has been ported to Windows, in the
202  MinGW system ([[http://mingw.sourceforge.net]]). Unlike Cygwin,
203  executables produced with MinGW do not need the Cygwin DLLs in order
204  to run.
205** Microsoft Visual Studio will soon be supported, including the
206  Express edition, which is a non-free but no-cost compiler suite
207  available from Microsoft
208  ([[http://www.microsoft.com/express/vc]]). Chicken supports
209  command-line building using the Microsoft C/C++ compiler.
210  Visual Studio users will want to install the Unix Utilities,
211  available at
212  [[http://www.call-with-current-continuation.org/tarballs/UnxUtils.zip]],
213  in order to get suitable versions of {{make}}, {{tar}}, {{gzip}},
214  and similar commands.
215
216TODO: what's the least we can possibly say about PATH,
217CHICKEN_INCLUDE_PATH, DYLD_LIBRARY_PATH, etc?
218
219=== Development environments
220
221The simplest development environment is a text editor and terminal
222window (Windows: Command Prompt, OSX: Terminal, Linux/Unix: xterm). If
223you install the {{readline}} egg (TODO: insert xref), you have all the
224benefits of command history and reentry, Emacs or vi-compatible line
225editing, and customization.
226
227You will need a text editor that knows Scheme; it's just too painful
228with editors that don't do parenthesis matching and proper
229indentation. Some editors allow you to execute Scheme code directly in
230the editor. This makes programming very interactive: you can type in a
231function and then try it right away. This feature is very highly
232recommended.
233
234As programmers have very specific tastes about editors, the editors
235listed here are shown in alphabetic order. We aren't about to tell you
236which editor to use, and there may be editors not shown here that
237might satisfy your needs.
238
239* Emacs ([[http://www.gnu.org/software/emacs]]) is available for
240  Linux/Unix, Macintosh, and Windows systems;
241  CHICKEN provides Emacs support out of the box, with the {{hen.el}}
242  Emacs Lisp file. Consult the ``Emacs Guide for Chicken Users''
243  (TODO: this document doesn't exist yet) for information on setting
244  up and using Emacs with Chicken.
245
246* Epsilon ([[http://www.lugaru.com]]) is a commercial text editor
247  whose design was   inspired by Emacs. Although Scheme support isn't
248  provided,  a Lisp mode is available on Lugaru's FTP site, and could
249  with some work be made to duplicate the Emacs support.
250
251* {{vim}} ([[http://www.vim.org]]) is a descendant of the venerable
252  {{vi}} editor first included with Berkeley versions of Unix.
253  TODO: say more about using vim with Chicken, all I know about vi is
254  that you can get out by typing :q! .
255
256TODO: other editors? Slick? Multi-Edit? Visual Studio? Eclipse? TextMate?
257Please fill in anything you know about. Has somebody done a
258SchemeScript for Chicken?
259
260=== Using the interpreter
261
262In the rest of this chapter, we'll assume that you are using a
263terminal window.
264
265To invoke the interpreter, you use the {{csi}} command.
266
267 $ csi
268 CHICKEN
269 (c)2000-2007 Felix L. Winkelmann
270 (c)2008 The Chicken Team
271 Version 3.0.1 - macosx-unix-gnu-x86    [ manyargs dload ptables applyhook ]
272 SVN rev. 8489  compiled 2008-02-15 on argyre.local (Darwin)
273 #;1>
274
275This brings up a brief banner, and then the prompt. You can use this
276pretty much like any other Scheme system, e.g.,
277
278 #;1> (define (twice f) (lambda (x) (f (f x))))
279 #;2> ((twice (lambda (n) (* n 10))) 3)
280 300
281
282Suppose  we have already created a file {{fact.scm}} containing a
283function definition.
284
285 (define (fact n)
286   (if (= n 0)
287       1
288       (* n (fact (- n 1)))))
289
290We can now load this file and try out the function.
291
292 #;3> (load "fact.scm")
293 ; loading fact.scm ...
294 #;4> (fact 3)
295 6
296
297The '''read-eval-print loop''' ('''REPL''') is the component of the
298Scheme system that ''reads'' a Scheme expression, ''eval''uates it,
299and ''prints'' out the result. The REPL's prompt can be customized
300(TODO: xref),
301but the default prompt, showing the number of the form, is quite
302convenient.
303
304The REPL also supports debugging commands:
305input lines beginning with a {{,}} (comma) are treated as special
306commands. (TODO: insert cross-reference to full list) We can
307'''trace''' {{fact}} to see how it works.
308
309 #;5> ,tr fact
310 #;5> (fact 3)
311 |(fact 3)
312 | (fact 2)
313 |  (fact 1)
314 |   (fact 0)
315 |   fact -> 1
316 |  fact -> 1
317 | fact -> 2
318 |fact -> 6
319 6
320
321The command number didn't increment, because the {{tr}} command isn't
322actually a Scheme ''form''.
323
324==== Scripts
325
326You can use the interpreter to run a Scheme program from the command
327line. Here we create a program that does a quick search-and-replace on
328an input file; the arguments are a regular expression and a
329replacement string.
330
331 $ cat quickrep.dat
332 xyzabcghi
333 abxawxcgh
334 foonly
335 $ csi -ss quickrep.scm <quickrep.dat 'a.*c' A
336 xyzAghi
337 Agh
338 foonly
339
340The {{-ss}} option sets several options that work smoothly together to
341execute a script. You can make the command directly executable from
342the shell by inserting a `shebang line' at the beginning of the
343program (TODO: insert xref).
344
345The program itself uses one of the libraries included with Chicken,
346the regular expression library, {{regex}}.
347
348 (use regex)
349 (define (process-line line re rplc)
350   (string-substitute re rplc line 'all))
351 (define (quickrep re rplc)
352   (let ((line (read-line)))
353     (if (not (eof-object? line))
354         (begin
355           (display (process-line line re rplc))
356           (newline)
357           (quickrep re rplc)))))
358 ;;; Does a lousy job of error checking!
359 (define (main args)
360   (quickrep (regexp (car args)) (cadr args)))
361
362The {{-ss}} option arranges to call a procedure named {{main}}, with
363the command line arguments, packed in a list, as its arguments. (There
364are a number of ways this program could be made more idiomatic Chicken
365Scheme, see the rest of the manual for details.)
366
367=== The compiler
368
369There are several reasons you might want to compile your code.
370
371* Compiled code executes substantially more quickly than interpreted
372  code.
373* You might want to deploy an application onto machines where the
374  users aren't expected to have Chicken installed: compiled
375  applications can be self-contained.
376
377The Chicken compiler is provided as the command {{chicken}}, but in
378almost all cases, you will want to use the {{csc}} command
379instead. {{csc}} is a convenient driver that automates compiling
380Scheme programs into C, compiling C code into object code, and linking
381the results into an executable file. (Note: in a Windows environment
382with Visual Studio, you may find that {{csc}} refers to Microsoft's
383C\# compiler. There are a number of ways of sorting this out, of which
384the simplest is to make a Windows batch file named {{cshc.bat}} which
385invokes the Chicken compiler, and organize your {{PATH}} accordingly.)
386
387Compiled code can be intermixed with interpreted code on systems that
388support dynamic loading, which includes modern versions of *BSD,
389Linux, Mac OS X, Solaris, and Windows.
390
391We can compile our factorial function, producing a file named
392{{fact.so}} (`shared object' in Linux-ese, the same file type is used
393in OS X and Windows).
394
395 chicken$ csc -dynamic fact.scm
396 chicken$ csi -quiet
397 #;1> (load "fact.so")
398 ; loading fact.so ...
399 #;2> (fact 6)
400 720
401
402On any system, we can just compile a program directly into an
403executable. Here's a program that tells you whether its argument is a
404palindrome.
405
406 (define (palindrome? x)
407   (define (check left right)
408     (if (>= left right)
409         #t
410         (and (char=? (string-ref x left) (string-ref x right))
411              (check (add1 left) (sub1 right)))))
412   (check 0 (sub1 (string-length x))))
413 (let ((arg (car (command-line-arguments))))
414   (display
415    (string-append arg
416                   (if (palindrome? arg)
417                       " is a palindrome\n"
418                       " isn't a palindrome\n"))))
419 
420We can compile this program using {{csc}}, creating an executable
421named {{palindrome}}.
422
423 $ csc -o palindrome palindrome.scm
424 $ ./palindrome level
425 level is a palindrome
426 $ ./palindrome liver
427 liver isn't a palindrome
428
429Chicken supports separate compilation, using some extensions to
430Scheme. Let's divide our palindrome program into a library module
431({{pal-proc.scm}}) and a client module ({{pal-user.scm}}).
432
433Here's the external library. We {{declare}} that {{pal-proc}} is a
434``unit'', which is the basis of separately-compiled modules in
435Chicken. (Units deal with separate compilation, but don't involve
436separated namespaces; namespaced module systems are available as
437eggs.)
438
439 ;;; Library pal-proc.scm
440 (declare (unit pal-proc))
441 (define (palindrome? x)
442   (define (check left right)
443     (if (>= left right)
444         #t
445         (and (char=? (string-ref x left) (string-ref x right))
446              (check (add1 left) (sub1 right)))))
447   (check 0 (sub1 (string-length x))))
448
449Next we have some  client code that `uses' this separately-compiled
450module. 
451
452 ;;; Client pal-user.scm
453 (declare (uses pal-proc))
454 (let ((arg (car (command-line-arguments))))
455   (display
456    (string-append arg
457                   (if (palindrome? arg)
458                       " is a palindrome\n"
459                       " isn't a palindrome\n"))))
460
461Now we can compile and link everything together. (We show the compile
462and link operations separately, but they can of course be combined
463into one command.)
464
465 $ csc -c pal-proc.scm
466 $ csc -c pal-user.scm
467 $ csc -o pal-separate pal-proc.o pal-user.o
468 $ ./pal-separate level
469 level is a palindrome
470
471=== Installing an egg
472
473Installing eggs is quite straightforward on systems that support
474dynamic loading (again, that would include *BSD, Linux, Mac OS X,
475Solaris, and Windows).  The command {{chicken-setup}} will fetch an
476egg from the master Chicken repository, and install it on your local
477system.
478
479In this example, we install the {{uri}} egg, for parsing Uniform
480Resource Identifiers. The installation produces a lot of output, which
481we have edited for space reasons.
482
483 $ chicken-setup uri
484
485 The extension uri does not exist.
486 Do you want to download it ? (yes/no/abort) [yes] yes
487 downloading uri.egg from (www.call-with-current-continuation.org eggs/3 80)
488   gzip -d -c ../uri.egg | tar xf -
489 .  /Users/vmanis/local/bin/csc -feature compiling-extension
490      -s -O2 -d1 uri.scm -o uri.so -check-imports -emit-exports uri.exports
491 ... (lots of stuff elided)
492 .  rm -fr /Users/vmanis/project/chicken/uri.egg
493
494First, {{chicken-setup}} asks us if we want to download the egg. It
495then uncompresses the egg, compiles the code, and installs the egg in
496the local Chicken repository.
497
498Now we can use our new egg.
499
500 #;1> (use uri)
501 ; loading /Users/vmanis/local/lib/chicken/3/uri.so ...
502 ; loading /Users/vmanis/local/lib/chicken/3/coerce-support.so ...
503 ; loading /Users/vmanis/local/lib/chicken/3/misc-extn-list-support.so ...
504 ; loading /Users/vmanis/local/lib/chicken/3/synch-support.so ...
505 ; loading /Users/vmanis/local/lib/chicken/3/lookup-table.so ...
506 ; loading /Users/vmanis/local/lib/chicken/3/misc-extn-control-support.so ...
507 #;2> (uri-host (uri "http://www.foobar.org/blah"))
508 "www.foobar.org"
509
510=== Accessing C libraries
511
512Because Chicken compiles to C, and because a foreign function
513interface is built into the compiler, interfacing to a C library is
514quite straightforward. This means that nearly any facility available
515on the host system is accessible from Chicken, with more or less
516work.
517
518Let's create a simple C library, to demonstrate how this
519works. Here we have a function that will compute and return the '''n'''th
520Fibonacci number. (This isn't a particularly good use of C here,
521because we could write this function just as easily in Scheme, but a
522real example would take far too much space here.)
523
524 int fib(int n) {
525   int prev = 0, curr = 1;
526   int next;
527   int i;
528   for (i = 0; i < n; i++) {
529     next = prev + curr;
530     prev = curr;
531     curr = next;
532   }
533   return curr;
534 }
535
536Now we can call this function from Chicken.
537
538 #>
539   extern fib(int n);
540 <#
541 (define xfib (foreign-lambda int "fib" int))
542 (do ((i 0 (+ i 1))) ((> i 10))
543   (printf "~A " (xfib i)))
544 (newline)
545
546The syntax {{#>...<#}} allows you to include literal C (typically
547external declarations) in your Chicken code. We access {{fib}} by
548defining a {{foreign-lambda}} for it, in this case saying that the
549function takes one integer argument (the {{int}} after the function
550name), and that it returns an integer result. Now we can invoke
551{{xfib}} as though it were an ordinary Scheme function.
552
553 $ gcc -c fib.c
554 $ csc -o fib-user fib.o fib-user.scm
555 $ ./fib-user
556 0 1 1 2 3 5 8 13 21 34 55
557
558Those who are interfacing to substantial C libraries should consider using the
559easyffi egg, or SWIG.
Note: See TracBrowser for help on using the repository browser.