Hello Guile!
============

This chapter presents a quick tour of all the ways that Guile can be used.  There are additional examples in the examples/ directory in the Guile source distribution.

The following examples assume that Guile has been installed in /usr/local/.

Running Guile Interactively
---------------------------

In its simplest form, Guile acts as an interactive interpreter for the Scheme programming language, reading and evaluating Scheme expressions the user enters from the terminal.  Here is a sample interaction between Guile and a user; the user's input appears after the $ and guile> prompts:

     $ guile
     guile> (+ 1 2 3)                ; add some numbers
     6
     guile> (define (factorial n)    ; define a function
              (if (zero? n) 1 (* n (factorial (- n 1)))))
     guile> (factorial 20)
     2432902008176640000
     guile> (getpwnam "jimb")        ; find my entry in /etc/passwd
     #("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
       "/usr/local/bin/bash")
     guile> C-d
     $

Running Guile Scripts
---------------------

Like AWK, Perl, or any shell, Guile can interpret script files.  A Guile script is simply a file of Scheme code with some extra information at the beginning which tells the operating system how to invoke Guile, and then tells Guile how to handle the Scheme code.

Here is a trivial Guile script, for more details see Guile Scripting.

     #!/usr/local/bin/guile -s
     !#
     (display "Hello, world!")
     (newline)

Linking Guile into Programs
---------------------------

The Guile interpreter is available as an object library, to be linked into applications using Scheme as a configuration or extension language.

Here is simple-guile.c, source code for a program that will produce a complete Guile interpreter.  In addition to all usual functions provided by Guile, it will also offer the function my-hostname.

     #include <stdlib.h>
     #include <libguile.h>

     static SCM
     my_hostname (void)
     {
       char *s = getenv ("HOSTNAME");
       if (s == NULL)
         return SCM_BOOL_F;
       else
         return scm_from_locale_string (s);
     }

     static void
     inner_main (void *data, int argc, char **argv)
     {
       scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
       scm_shell (argc, argv);
     }

     int
     main (int argc, char **argv)
     {
       scm_boot_guile (argc, argv, inner_main, 0);
       return 0; /* never reached */
     }

When Guile is correctly installed on your system, the above program can be compiled and linked like this:

     $ gcc -o simple-guile simple-guile.c \
         `pkg-config --cflags --libs guile-2.0`

When it is run, it behaves just like the guile program except that you can also call the new my-hostname function.

     $ ./simple-guile
     guile> (+ 1 2 3)
     6
     guile> (my-hostname)
     "burns"

Writing Guile Extensions
------------------------

You can link Guile into your program and make Scheme available to the users of your program.  You can also link your library into Guile and make its functionality available to all users of Guile.

A library that is linked into Guile is called an extensions, but it really just is an ordinary object library.

The following example shows how to write a simple extension for Guile that makes the j0 function available to Scheme code.

     #include <math.h>
     #include <libguile.h>

     SCM
     j0_wrapper (SCM x)
     {
       return scm_make_real (j0 (scm_num2dbl (x, "j0")));
     }

     void
     init_bessel ()
     {
       scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
     }

This C source file needs to be compiled into a shared library.  Here is how to do it on GNU/Linux:

     gcc -shared -o libguile-bessel.so -fPIC bessel.c

For creating shared libraries portably, we recommend the use of GNU Libtool (see Introduction (GNU Libtool)).

A shared library can be loaded into a running Guile process with the function load-extension.  The j0 is then immediately available:

     $ guile
     guile> (load-extension "./libguile-bessel" "init_bessel")
     guile> (j0 2)
     0.223890779141236

Using the Guile Module System
-----------------------------

Guile has support for dividing a program into modules.  By using modules, you can group related code together and manage the composition of complete programs from largely independent parts.

(Although the module system implementation is in flux, feel free to use it anyway.  Guile will provide reasonable backwards compatibility.)

Details on the module system beyond this introductory material can be found in see Modules.

Using Modules
.............

Guile comes with a lot of useful modules, for example for string processing or command line parsing.  Additionally, there exist many Guile modules written by other Guile hackers, but which have to be installed manually.

Here is a sample interactive session that shows how to use the (ice-9 popen) module which provides the means for communicating with other processes over pipes together with the (ice-9 rdelim) module that provides the function read-line.

     $ guile
     guile> (use-modules (ice-9 popen))
     guile> (use-modules (ice-9 rdelim))
     guile> (define p (open-input-pipe "ls -l"))
     guile> (read-line p)
     "total 30"
     guile> (read-line p)
     "drwxr-sr-x    2 mgrabmue mgrabmue     1024 Mar 29 19:57 CVS"

Writing new Modules
...................

You can create new modules using the syntactic form define-module.  All definitions following this form until the next define-module are placed into the new module.

One module is usually placed into one file, and that file is installed in a location where Guile can automatically find it.  The following session shows a simple example.

     $ cat /usr/local/share/guile/foo/bar.scm

     (define-module (foo bar))
     (export frob)

     (define (frob x) (* 2 x))

     $ guile
     guile> (use-modules (foo bar))
     guile> (frob 12)
     24

Putting Extensions into Modules
...............................

In addition to Scheme code you can also put things that are defined in C into a module.

You do this by writing a small Scheme file that defines the module and call load-extension directly in the body of the module.

     $ cat /usr/local/share/guile/math/bessel.scm

     (define-module (math bessel))
     (export j0)

     (load-extension "libguile-bessel" "init_bessel")

     $ file /usr/local/lib/libguile-bessel.so
     ... ELF 32-bit LSB shared object ...
     $ guile
     guile> (use-modules (math bessel))
     guile> (j0 2)
     0.223890779141236

There is also a way to manipulate the module system from C but only Scheme files can be autoloaded.  Thus, we recommend that you define your modules in Scheme.