   Guile Reference Manual Copyright (C) 1996 Free Software Foundation
Copyright (C) 1997 Free Software Foundation
Copyright (C) 2000 Free Software Foundation
Copyright (C) 2001 Free Software Foundation
Copyright (C) 2002 Free Software Foundation

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

Environment Chaining
--------------------

   In the example of the previous subsection, we glossed over an
important point.  The body of the `let' expression in that example
refers not only to the local variable `s', but also to the top level
variables `a', `b', `c' and `sqrt'.  (`sqrt' is the standard Scheme
procedure for calculating a square root.)  If the body of the `let'
expression is evaluated in the context of the _local_ `let'
environment, how does the evaluation get at the values of these top
level variables?

   The answer is that the local environment created by a `let'
expression automatically has a reference to its containing environment
-- in this case the top level environment -- and that the Scheme
interpreter automatically looks for a variable binding in the containing
environment if it doesn't find one in the local environment.  More
generally, every environment except for the top level one has a
reference to its containing environment, and the interpreter keeps
searching back up the chain of environments -- from most local to top
level -- until it either finds a variable binding for the required
identifier or exhausts the chain.

   This description also determines what happens when there is more than
one variable binding with the same name.  Suppose, continuing the
example of the previous subsection, that there was also a pre-existing
top level variable `s' created by the expression:

     (define s "Some beans, my lord!")

   Then both the top level environment and the local `let' environment
would contain bindings for the name `s'.  When evaluating code within
the `let' body, the interpreter looks first in the local `let'
environment, and so finds the binding for `s' created by the `let'
syntax.  Even though this environment has a reference to the top level
environment, which also has a binding for `s', the interpreter doesn't
get as far as looking there.  When evaluating code outside the `let'
body, the interpreter looks up variable names in the top level
environment, so the name `s' refers to the top level variable.

   Within the `let' body, the binding for `s' in the local environment
is said to "shadow" the binding for `s' in the top level environment.

Lexical Scope
-------------

   The rules that we have just been describing are the details of how
Scheme implements "lexical scoping".  This subsection takes a brief
diversion to explain what lexical scope means in general and to present
an example of non-lexical scoping.

   "Lexical scope" in general is the idea that

   * an identifier at a particular place in a program always refers to
     the same variable location -- where "always" means "every time
     that the containing expression is executed", and that

   * the variable location to which it refers can be determined by
     static examination of the source code context in which that
     identifier appears, without having to consider the flow of
     execution through the program as a whole.

   In practice, lexical scoping is the norm for most programming
languages, and probably corresponds to what you would intuitively
consider to be "normal".  You may even be wondering how the situation
could possibly -- and usefully -- be otherwise.  To demonstrate that
another kind of scoping is possible, therefore, and to compare it
against lexical scoping, the following subsection presents an example
of non-lexical scoping and examines in detail how its behavior differs
from the corresponding lexically scoped code.

An Example of Non-Lexical Scoping
.................................

   To demonstrate that non-lexical scoping does exist and can be
useful, we present the following example from Emacs Lisp, which is a
"dynamically scoped" language.

     (defvar currency-abbreviation "USD")

     (defun currency-string (units hundredths)
       (concat currency-abbreviation
               (number-to-string units)
               "."
               (number-to-string hundredths)))

     (defun french-currency-string (units hundredths)
       (let ((currency-abbreviation "FRF"))
         (currency-string units hundredths)))

   The question to focus on here is: what does the identifier
`currency-abbreviation' refer to in the `currency-string' function?
The answer, in Emacs Lisp, is that all variable bindings go onto a
single stack, and that `currency-abbreviation' refers to the topmost
binding from that stack which has the name "currency-abbreviation".
The binding that is created by the `defvar' form, to the value `"USD"',
is only relevant if none of the code that calls `currency-string'
rebinds the name "currency-abbreviation" in the meanwhile.

   The second function `french-currency-string' works precisely by
taking advantage of this behaviour.  It creates a new binding for the
name "currency-abbreviation" which overrides the one established by the
`defvar' form.

     ;; Note!  This is Emacs Lisp evaluation, not Scheme!
     (french-currency-string 33 44)
     =>
     "FRF33.44"

   Now let's look at the corresponding, _lexically scoped_ Scheme code:

     (define currency-abbreviation "USD")

     (define (currency-string units hundredths)
       (string-append currency-abbreviation
                      (number->string units)
                      "."
                      (number->string hundredths)))

     (define (french-currency-string units hundredths)
       (let ((currency-abbreviation "FRF"))
         (currency-string units hundredths)))

   According to the rules of lexical scoping, the
`currency-abbreviation' in `currency-string' refers to the variable
location in the innermost environment at that point in the code which
has a binding for `currency-abbreviation', which is the variable
location in the top level environment created by the preceding `(define
currency-abbreviation ...)' expression.

   In Scheme, therefore, the `french-currency-string' procedure does
not work as intended.  The variable binding that it creates for
"currency-abbreviation" is purely local to the code that forms the body
of the `let' expression.  Since this code doesn't directly use the name
"currency-abbreviation" at all, the binding is pointless.

     (french-currency-string 33 44)
     =>
     "USD33.44"

   This begs the question of how the Emacs Lisp behaviour can be
implemented in Scheme.  In general, this is a design question whose
answer depends upon the problem that is being addressed.  In this case,
the best answer may be that `currency-string' should be redesigned so
that it can take an optional third argument.  This third argument, if
supplied, is interpreted as a currency abbreviation that overrides the
default.

   It is possible to change `french-currency-string' so that it mostly
works without changing `currency-string', but the fix is inelegant, and
susceptible to interrupts that could leave the `currency-abbreviation'
variable in the wrong state:

     (define (french-currency-string units hundredths)
       (set! currency-abbreviation "FRF")
       (let ((result (currency-string units hundredths)))
         (set! currency-abbreviation "USD")
         result))

   The key point here is that the code does not create any local binding
for the identifier `currency-abbreviation', so all occurrences of this
identifier refer to the top level variable.

Closure
-------

   Consider a `let' expression that doesn't contain any `lambda's:

     (let ((s (/ (+ a b c) 2)))
       (sqrt (* s (- s a) (- s b) (- s c))))

When the Scheme interpreter evaluates this, it

   * creates a new environment with a reference to the environment that
     was current when it encountered the `let'

   * creates a variable binding for `s' in the new environment, with
     value given by `(/ (+ a b c) 2)'

   * evaluates the expression in the body of the `let' in the context of
     the new local environment, and remembers the value `V'

   * forgets the local environment

   * continues evaluating the expression that contained the `let', using
     the value `V' as the value of the `let' expression, in the context
     of the containing environment.

   After the `let' expression has been evaluated, the local environment
that was created is simply forgotten, and there is no longer any way to
access the binding that was created in this environment.  If the same
code is evaluated again, it will follow the same steps again, creating
a second new local environment that has no connection with the first,
and then forgetting this one as well.

   If the `let' body contains a `lambda' expression, however, the local
environment is _not_ forgotten.  Instead, it becomes associated with
the procedure that is created by the `lambda' expression, and is
reinstated every time that that procedure is called.  In detail, this
works as follows.

   * When the Scheme interpreter evaluates a `lambda' expression, to
     create a procedure object, it stores the current environment as
     part of the procedure definition.

   * Then, whenever that procedure is called, the interpreter
     reinstates the environment that is stored in the procedure
     definition and evaluates the procedure body within the context of
     that environment.

   The result is that the procedure body is always evaluated in the
context of the environment that was current when the procedure was
created.

   This is what is meant by "closure".  The next few subsections
present examples that explore the usefulness of this concept.

Example 1: A Serial Number Generator
------------------------------------

   This example uses closure to create a procedure with a variable
binding that is private to the procedure, like a local variable, but
whose value persists between procedure calls.

     (define (make-serial-number-generator)
       (let ((current-serial-number 0))
         (lambda ()
           (set! current-serial-number (+ current-serial-number 1))
           current-serial-number)))

     (define entry-sn-generator (make-serial-number-generator))

     (entry-sn-generator)
     =>
     1

     (entry-sn-generator)
     =>
     2

   When `make-serial-number-generator' is called, it creates a local
environment with a binding for `current-serial-number' whose initial
value is 0, then, within this environment, creates a procedure.  The
local environment is stored within the created procedure object and so
persists for the lifetime of the created procedure.

   Every time the created procedure is invoked, it increments the value
of the `current-serial-number' binding in the captured environment and
then returns the current value.

   Note that `make-serial-number-generator' can be called again to
create a second serial number generator that is independent of the
first.  Every new invocation of `make-serial-number-generator' creates
a new local `let' environment and returns a new procedure object with
an association to this environment.

Example 2: A Shared Persistent Variable
---------------------------------------

   This example uses closure to create two procedures, `get-balance'
and `deposit', that both refer to the same captured local environment
so that they can both access the `balance' variable binding inside that
environment.  The value of this variable binding persists between calls
to either procedure.

   Note that the captured `balance' variable binding is private to
these two procedures: it is not directly accessible to any other code.
It can only be accessed indirectly via `get-balance' or `deposit', as
illustrated by the `withdraw' procedure.

     (define get-balance #f)
     (define deposit #f)

     (let ((balance 0))
       (set! get-balance
             (lambda ()
               balance))
       (set! deposit
             (lambda (amount)
               (set! balance (+ balance amount))
               balance)))

     (define (withdraw amount)
       (deposit (- amount)))

     (get-balance)
     =>
     0

     (deposit 50)
     =>
     50

     (withdraw 75)
     =>
     -25

   An important detail here is that the `get-balance' and `deposit'
variables must be set up by `define'ing them at top level and then
`set!'ing their values inside the `let' body.  Using `define' within
the `let' body would not work: this would create variable bindings
within the local `let' environment that would not be accessible at top
level.

Example 3: The Callback Closure Problem
---------------------------------------

   A frequently used programming model for library code is to allow an
application to register a callback function for the library to call when
some particular event occurs.  It is often useful for the application to
make several such registrations using the same callback function, for
example if several similar library events can be handled using the same
application code, but the need then arises to distinguish the callback
function calls that are associated with one callback registration from
those that are associated with different callback registrations.

   In languages without the ability to create functions dynamically,
this problem is usually solved by passing a `user_data' parameter on the
registration call, and including the value of this parameter as one of
the parameters on the callback function.  Here is an example of
declarations using this solution in C:

     typedef void (event_handler_t) (int event_type,
                                     void *user_data);

     void register_callback (int event_type,
                             event_handler_t *handler,
                             void *user_data);

   In Scheme, closure can be used to achieve the same functionality
without requiring the library code to store a `user-data' for each
callback registration.

     ;; In the library:

     (define (register-callback event-type handler-proc)
       ...)

     ;; In the application:

     (define (make-handler event-type user-data)
       (lambda ()
         ...
         <code referencing event-type and user-data>
         ...))

     (register-callback event-type
                        (make-handler event-type ...))

   As far as the library is concerned, `handler-proc' is a procedure
with no arguments, and all the library has to do is call it when the
appropriate event occurs.  From the application's point of view, though,
the handler procedure has used closure to capture an environment that
includes all the context that the handler code needs -- `event-type'
and `user-data' -- to handle the event correctly.

Example 4: Object Orientation
-----------------------------

   Closure is the capture of an environment, containing persistent
variable bindings, within the definition of a procedure or a set of
related procedures.  This is rather similar to the idea in some object
oriented languages of encapsulating a set of related data variables
inside an "object", together with a set of "methods" that operate on the
encapsulated data.  The following example shows how closure can be used
to emulate the ideas of objects, methods and encapsulation in Scheme.

     (define (make-account)
       (let ((balance 0))
         (define (get-balance)
           balance)
         (define (deposit amount)
           (set! balance (+ balance amount))
           balance)
         (define (withdraw amount)
           (deposit (- amount)))

         (lambda args
           (apply
             (case (car args)
               ((get-balance) get-balance)
               ((deposit) deposit)
               ((withdraw) withdraw)
               (else (error "Invalid method!")))
             (cdr args)))))

   Each call to `make-account' creates and returns a new procedure,
created by the expression in the example code that begins "(lambda
args".

     (define my-account (make-account))

     my-account
     =>
     #<procedure args>

   This procedure acts as an account object with methods `get-balance',
`deposit' and `withdraw'.  To apply one of the methods to the account,
you call the procedure with a symbol indicating the required method as
the first parameter, followed by any other parameters that are required
by that method.

     (my-account 'get-balance)
     =>
     0

     (my-account 'withdraw 5)
     =>
     -5

     (my-account 'deposit 396)
     =>
     391

     (my-account 'get-balance)
     =>
     391

   Note how, in this example, both the current balance and the helper
procedures `get-balance', `deposit' and `withdraw', used to implement
the guts of the account object's methods, are all stored in variable
bindings within the private local environment captured by the `lambda'
expression that creates the account object procedure.

Further Reading
***************

   * The website <http://www.schemers.org> is a good starting point for
     all things Scheme.

   * Dorai Sitaram's online Scheme tutorial, "Teach Yourself Scheme in
     Fixnum Days", at
     <http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html>.
     Includes a nice explanation of continuations.

   * The complete text of "Structure and Interpretation of Computer
     Programs", the classic introduction to computer science and Scheme
     by Hal Abelson, Jerry Sussman and Julie Sussman, is now available
     online at <http://mitpress.mit.edu/sicp/sicp.html>.  This site
     also provides teaching materials related to the book, and all the
     source code used in the book, in a form suitable for loading and
     running.

Part III: Guile as an Extension Language
****************************************

   In this part of the manual, we aim to present a wide ranging picture
of what it means to use Guile as an application extension language, to
provide guidance, practical guidelines and tips for _how_ to program in
Guile, and to document the tools that are available to help you with
your programming.  For detailed reference information on the variables,
functions etc. that make up Guile's application programming interface
(API), please refer to Part IV (see Part IV -- Guile API Reference).

Using Guile as an Extension Language
************************************

   The chapters in this part of the manual explain how to use Guile as a
powerful application extension language.

   An important change for the 1.6.x series of Guile releases is that
the GH interface is now deprecated.  For the reasoning behind this
decision, see GH deprecation.  The GH interface will continue
to be supported for the 1.6.x and 1.8.x release series, but will be
dropped thereafter, so developers are encouraged to switch
progressively to the scm interface.  The last chapter in this part of
the manual (see GH) documents both how to use GH and how to switch
from GH to scm.

   The Guile developers believe that clarification of the GH vs. scm
debate, and the consequent deprecation of the GH interface, are in the
long term interests of the project.  However it does create an
unfortunate situation for developers who want to start a project using
Guile and so read the manual to find out how to proceed.  They will
discover that the GH interface, although quite well documented, is
deprecated, but that there is almost no adequate documentation for its
theoretical replacement, the scm interface.  Moreover, the scm interface
still has the odd few rough edges which need smoothing down.

   Therefore, although deprecated, it is quite OK to continue to use
the GH interface if you feel uncomfortable with the `scm_' interface as
it stands today.  By the time that support for GH is dropped, we plan to
have thoroughly documented the `scm_' interface, and to have enhanced it
such that conversion from GH to the `scm_' interface will be very
straightforward, and probably mostly automated.

   As far as documentation of the scm interface is concerned, the
current position is that it is a bit confused, but that the situation
should improve rapidly once the 1.6.0 release is out.  The plan is to
refocus the bulk of Part II, currently "Guile Scheme", as the "Guile API
Reference" so that it covers both Scheme and C interfaces.  (This makes
sense because almost all of Guile's primitive procedures on the Scheme
level -- e.g. `memq' -- are also available as C level primitives in the
scm interface -- e.g. `scm_memq'.)  There will then remain a certain
amount of Scheme-specific (such as the "Basic Ideas" chapter) and
C-specific documentation (such as SMOB usage and interaction with the
garbage collector) to collect into corresponding chapters.

An Overview of Guile Programming
********************************

   Guile is designed as an extension language interpreter that is
straightforward to integrate with applications written in C (and C++).
The big win here for the application developer is that Guile
integration, as the Guile web page says, "lowers your project's
hacktivation energy."  Lowering the hacktivation energy means that you,
as the application developer, _and your users_, reap the benefits that
flow from being able to extend the application in a high level
extension language rather than in plain old C.

   In abstract terms, it's difficult to explain what this really means
and what the integration process involves, so instead let's begin by
jumping straight into an example of how you might integrate Guile into
an existing program, and what you could expect to gain by so doing.
With that example under our belts, we'll then return to a more general
analysis of the arguments involved and the range of programming options
available.

How One Might Extend Dia Using Guile
====================================

   Dia is a free software program for drawing schematic diagrams like
flow charts and floor plans (REFFIXME).  This section conducts the
thought experiment of adding Guile to Dia.  In so doing, it aims to
illustrate several of the steps and considerations involved in adding
Guile to applications in general.

Deciding Why You Want to Add Guile
----------------------------------

   First off, you should understand why you want to add Guile to Dia at
all, and that means forming a picture of what Dia does and how it does
it.  So, what are the constituents of the Dia application?

   * Most importantly, the "application domain objects" -- in other
     words, the concepts that differentiate Dia from another
     application such as a word processor or spreadsheet: shapes,
     templates, connectors, pages, plus the properties of all these
     things.

   * The code that manages the graphical face of the application,
     including the layout and display of the objects above.

   * The code that handles input events, which indicate that the
     application user is wanting to do something.

(In other words, a textbook example of the "model - view - controller"
paradigm.)

   Next question: how will Dia benefit once the Guile integration is
complete?  Several (positive!) answers are possible here, and the choice
is obviously up to the application developers.  Still, one answer is
that the main benefit will be the ability to manipulate Dia's
application domain objects from Scheme.

   Suppose that Dia made a set of procedures available in Scheme,
representing the most basic operations on objects such as shapes,
connectors, and so on.  Using Scheme, the application user could then
write code that builds upon these basic operations to create more
complex procedures.  For example, given basic procedures to enumerate
the objects on a page, to determine whether an object is a square, and
to change the fill pattern of a single shape, the user can write a
Scheme procedure to change the fill pattern of all squares on the
current page:

     (define (change-squares'-fill-pattern new-pattern)
       (for-each-shape current-page
         (lambda (shape)
           (if (square? shape)
               (change-fill-pattern shape new-pattern)))))

Four Steps Required to Add Guile
--------------------------------

   Assuming this objective, four steps are needed to achieve it.

   First, you need a way of representing your application-specific
objects -- such as `shape' in the previous example -- when they are
passed into the Scheme world.  Unless your objects are so simple that
they map naturally into builtin Scheme data types like numbers and
strings, you will probably want to use Guile's "SMOB" interface to
create a new Scheme data type for your objects.

   Second, you need to write code for the basic operations like
`for-each-shape' and `square?' such that they access and manipulate
your existing data structures correctly, and then make these operations
available as "primitives" on the Scheme level.

   Third, you need to provide some mechanism within the Dia application
that a user can hook into to cause arbitrary Scheme code to be
evaluated.

   Finally, you need to restructure your top-level application C code a
little so that it initializes the Guile interpreter correctly and
declares your "SMOBs" and "primitives" to the Scheme world.

   The following subsections expand on these four points in turn.

How to Represent Dia Data in Scheme
-----------------------------------

   For all but the most trivial applications, you will probably want to
allow some representation of your domain objects to exist on the Scheme
level.  This is where the idea of SMOBs comes in, and with it issues of
lifetime management and garbage collection.

   To get more concrete about this, let's look again at the example we
gave earlier of how application users can use Guile to build
higher-level functions from the primitives that Dia itself provides.

     (define (change-squares'-fill-pattern new-pattern)
       (for-each-shape current-page
         (lambda (shape)
           (if (square? shape)
               (change-fill-pattern shape new-pattern)))))

   Consider what is stored here in the variable `shape'.  For each
shape on the current page, the `for-each-shape' primitive calls
`(lambda (shape) ...)' with an argument representing that shape.
Question is: how is that argument represented on the Scheme level?  The
issues are as follows.

   * Whatever the representation, it has to be decodable again by the C
     code for the `square?' and `change-fill-pattern' primitives.  In
     other words, a primitive like `square?' has somehow to be able to
     turn the value that it receives back into something that points to
     the underlying C structure describing a shape.

   * The representation must also cope with Scheme code holding on to
     the value for later use.  What happens if the Scheme code stores
     `shape' in a global variable, but then that shape is deleted (in a
     way that the Scheme code is not aware of), and later on some other
     Scheme code uses that global variable again in a call to, say,
     `square?'?

   * The lifetime and memory allocation of objects that exist _only_ in
     the Scheme world is managed automatically by Guile's garbage
     collector using one simple rule: when there are no remaining
     references to an object, the object is considered dead and so its
     memory is freed.  But for objects that exist in both C and Scheme,
     the picture is more complicated; in the case of Dia, where the
     `shape' argument passes transiently in and out of the Scheme
     world, it would be quite wrong the *delete* the underlying C shape
     just because the Scheme code has finished evaluation.  How do we
     avoid this happening?

   One resolution of these issues is for the Scheme-level
representation of a shape to be a new, Scheme-specific C structure
wrapped up as a SMOB.  The SMOB is what is passed into and out of
Scheme code, and the Scheme-specific C structure inside the SMOB points
to Dia's underlying C structure so that the code for primitives like
`square?' can get at it.

   To cope with an underlying shape being deleted while Scheme code is
still holding onto a Scheme shape value, the underlying C structure
should have a new field that points to the Scheme-specific SMOB.  When a
shape is deleted, the relevant code chains through to the
Scheme-specific structure and sets its pointer back to the underlying
structure to NULL.  Thus the SMOB value for the shape continues to
exist, but any primitive code that tries to use it will detect that the
underlying shape has been deleted because the underlying structure
pointer is NULL.

   So, to summarize the steps involved in this resolution of the problem
(and assuming that the underlying C structure for a shape is `struct
dia_shape'):

   * Define a new Scheme-specific structure that _points_ to the
     underlying C structure:

          struct dia_guile_shape
          {
            struct dia_shape * c_shape;   /* NULL => deleted */
          }

   * Add a field to `struct dia_shape' that points to its `struct
     dia_guile_shape' if it has one --

          struct dia_shape
          {
            ...
            struct dia_guile_shape * guile_shape;
          }

     -- so that C code can set `guile_shape->c_shape' to NULL when the
     underlying shape is deleted.

   * Wrap `struct dia_guile_shape' as a SMOB type.

   * Whenever you need to represent a C shape onto the Scheme level,
     create a SMOB instance for it, and pass that.

   * In primitive code that receives a shape SMOB instance, check the
     `c_shape' field when decoding it, to find out whether the
     underlying C shape is still there.

   As far as memory management is concerned, the SMOB values and their
Scheme-specific structures are under the control of the garbage
collector, whereas the underlying C structures are explicitly managed in
exactly the same way that Dia managed them before we thought of adding
Guile.

   When the garbage collector decides to free a shape SMOB value, it
calls the "SMOB free" function that was specified when defining the
shape SMOB type.  To maintain the correctness of the `guile_shape' field
in the underlying C structure, this function should chain through to the
underlying C structure (if it still exists) and set its `guile_shape'
field to NULL.

   For full documentation on defining and using SMOB types, see
Defining New Types (Smobs).

Writing Guile Primitives for Dia
--------------------------------

   Once the details of object representation are decided, writing the
primitive function code that you need is usually straightforward.

   A primitive is simply a C function whose arguments and return value
are all of type `SCM', and whose body does whatever you want it to do.
As an example, here is a possible implementation of the `square?'
primitive:

     #define FUNC_NAME "square?"
     static SCM square_p (SCM shape)
     {
       struct dia_guile_shape * guile_shape;

       /* Check that arg is really a shape SMOB. */
       SCM_VALIDATE_SHAPE (SCM_ARG1, shape);

       /* Access Scheme-specific shape structure. */
       guile_shape = SCM_SMOB_DATA (shape);

       /* Find out if underlying shape exists and is a
          square; return answer as a Scheme boolean. */
       return SCM_BOOL (guile_shape->c_shape &&
                        (guile_shape->c_shape->type == DIA_SQUARE));
     }
     #undef FUNC_NAME

   Notice how easy it is to chain through from the `SCM shape'
parameter that `square_p' receives -- which is a SMOB -- to the
Scheme-specific structure inside the SMOB, and thence to the underlying
C structure for the shape.

   In this code, `SCM_SMOB_DATA' and `SCM_BOOL' are macros from the
standard Guile API.  `SCM_VALIDATE_SHAPE' is a macro that you should
define as part of your SMOB definition: it checks that the passed
parameter is of the expected type.  This is needed to guard against
Scheme code using the `square?' procedure incorrectly, as in `(square?
"hello")'; Scheme's latent typing means that usage errors like this
must be caught at run time.

   Having written the C code for your primitives, you need to make them
available as Scheme procedures by calling the `scm_c_define_gsubr'
function.  `scm_c_define_gsubr' (REFFIXME) takes arguments that specify
the Scheme-level name for the primitive and how many required, optional
and rest arguments it can accept.  The `square?' primitive always
requires exactly one argument, so the call to make it available in
Scheme reads like this:

     scm_c_define_gsubr ("square?", 1, 0, 0, square_p);

   For where to put this call, see the subsection after next on the
structure of Guile-enabled code (see Dia Structure).

Providing a Hook for the Evaluation of Scheme Code
--------------------------------------------------

   To make the Guile integration useful, you have to design some kind of
hook into your application that application users can use to cause their
Scheme code to be evaluated.

   Technically, this is straightforward; you just have to decide on a
mechanism that is appropriate for your application.  Think of Emacs, for
example: when you type `<ESC> :', you get a prompt where you can type
in any Elisp code, which Emacs will then evaluate.  Or, again like
Emacs, you could provide a mechanism (such as an init file) to allow
Scheme code to be associated with a particular key sequence, and
evaluate the code when that key sequence is entered.

   In either case, once you have the Scheme code that you want to
evaluate, as a null terminated string, you can tell Guile to evaluate
it by calling the `scm_c_eval_string' function.

Top-level Structure of Guile-enabled Dia
----------------------------------------

   Let's assume that the pre-Guile Dia code looks structurally like
this:

   * `main ()'

        * do lots of initialization and setup stuff

        * enter Gtk main loop

   When you add Guile to a program, one (rather technical) requirement
is that Guile's garbage collector needs to know where the bottom of the
C stack is.  The easiest way to ensure this is to use `scm_boot_guile'
like this:

   * `main ()'

        * do lots of initialization and setup stuff

        * `scm_boot_guile (argc, argv, inner_main, NULL)'

   * `inner_main ()'

        * define all SMOB types

        * export primitives to Scheme using `scm_c_define_gsubr'

        * enter Gtk main loop

   In other words, you move the guts of what was previously in your
`main' function into a new function called `inner_main', and then add a
`scm_boot_guile' call, with `inner_main' as a parameter, to the end of
`main'.

   Assuming that you are using SMOBs and have written primitive code as
described in the preceding subsections, you also need to insert calls to
declare your new SMOBs and export the primitives to Scheme.  These
declarations must happen _inside_ the dynamic scope of the
`scm_boot_guile' call, but also _before_ any code is run that could
possibly use them -- the beginning of `inner_main' is an ideal place
for this.

Going Further with Dia and Guile
--------------------------------

   The steps described so far implement an initial Guile integration
that already gives a lot of additional power to Dia application users.
But there are further steps that you could take, and it's interesting to
consider a few of these.

   In general, you could progressively move more of Dia's source code
from C into Scheme.  This might make the code more maintainable and
extensible, and it could open the door to new programming paradigms that
are tricky to effect in C but straightforward in Scheme.

   A specific example of this is that you could use the guile-gtk
package, which provides Scheme-level procedures for most of the Gtk+
library, to move the code that lays out and displays Dia objects from C
to Scheme.

   As you follow this path, it naturally becomes less useful to
maintain a distinction between Dia's original non-Guile-related source
code, and its later code implementing SMOBs and primitives for the
Scheme world.

   For example, suppose that the original source code had a
`dia_change_fill_pattern' function:

     void dia_change_fill_pattern (struct dia_shape * shape,
                                   struct dia_pattern * pattern)
     {
       /* real pattern change work */
     }

   During initial Guile integration, you add a `change_fill_pattern'
primitive for Scheme purposes, which accesses the underlying structures
from its SMOB values and uses `dia_change_fill_pattern' to do the real
work:

     SCM change_fill_pattern (SCM shape, SCM pattern)
     {
       struct dia_shape * d_shape;
       struct dia_pattern * d_pattern;

       ...

       dia_change_fill_pattern (d_shape, d_pattern);

       return SCM_UNSPECIFIED;
     }

   At this point, it makes sense to keep `dia_change_fill_pattern' and
`change_fill_pattern' separate, because `dia_change_fill_pattern' can
also be called without going through Scheme at all, say because the
user clicks a button which causes a C-registered Gtk+ callback to be
called.

   But, if the code for creating buttons and registering their
callbacks is moved into Scheme (using guile-gtk), it may become true
that `dia_change_fill_pattern' can no longer be called other than
through Scheme.  In which case, it makes sense to abolish it and move
its contents directly into `change_fill_pattern', like this:

     SCM change_fill_pattern (SCM shape, SCM pattern)
     {
       struct dia_shape * d_shape;
       struct dia_pattern * d_pattern;

       ...

       /* real pattern change work */

       return SCM_UNSPECIFIED;
     }

   So further Guile integration progressively _reduces_ the amount of
functional C code that you have to maintain over the long term.

   A similar argument applies to data representation.  In the
discussion of SMOBs earlier, issues arose because of the different
memory management and lifetime models that normally apply to data
structures in C and in Scheme.  However, with further Guile
integration, you can resolve this issue in a more radical way by
allowing all your data structures to be under the control of the
garbage collector, and kept alive by references from the Scheme world.
Instead of maintaining an array or linked list of shapes in C, you
would instead maintain a list in Scheme.

   Rather like the coalescing of `dia_change_fill_pattern' and
`change_fill_pattern', the practical upshot of such a change is that
you would no longer have to keep the `dia_shape' and `dia_guile_shape'
structures separate, and so wouldn't need to worry about the pointers
between them.  Instead, you could change the SMOB definition to wrap
the `dia_shape' structure directly, and send `dia_guile_shape' off to
the scrap yard.  Cut out the middle man!

   Finally, we come to the holy grail of Guile's free software /
extension language approach.  Once you have a Scheme representation for
interesting Dia data types like shapes, and a handy bunch of primitives
for manipulating them, it suddenly becomes clear that you have a bundle
of functionality that could have far-ranging use beyond Dia itself.  In
other words, the data types and primitives could now become a library,
and Dia becomes just one of the many possible applications using that
library -- albeit, at this early stage, a rather important one!

   In this model, Guile becomes just the glue that binds everything
together.  Imagine an application that usefully combined functionality
from Dia, Gnumeric and GnuCash -- it's tricky right now, because no
such application yet exists; but it'll happen some day ...

Why Scheme is More Hackable Than C
==================================

   Underlying Guile's value proposition is the assumption that
programming in a high level language, specifically Guile's
implementation of Scheme, is necessarily better in some way than
programming in C.  What do we mean by this claim, and how can we be so
sure?

   One class of advantages applies not only to Scheme, but more
generally to any interpretable, high level, scripting language, such as
Emacs Lisp, Python, Ruby, or TeX's macro language.  Common features of
all such languages, when compared to C, are that:

   * They lend themselves to rapid and experimental development cycles,
     owing usually to a combination of their interpretability and the
     integrated development environment in which they are used.

   * They free developers from some of the low level bookkeeping tasks
     associated with C programming, notably memory management.

   * They provide high level features such as container objects and
     exception handling that make common programming tasks easier.

   In the case of Scheme, particular features that make programming
easier -- and more fun! -- are its powerful mechanisms for abstracting
parts of programs (closures -- see About Closure) and for iteration
(see while do).

   The evidence in support of this argument is empirical: the huge
amount of code that has been written in extension languages for
applications that support this mechanism.  Most notable are extensions
written in Emacs Lisp for GNU Emacs, in TeX's macro language for TeX,
and in Script-Fu for the Gimp, but there is increasingly now a
significant code eco-system for Guile-based applications as well, such
as Lilypond and GnuCash.  It is close to inconceivable that similar
amounts of functionality could have been added to these applications
just by writing new code in their base implementation languages.

Example: Using Guile for an Application Testbed
===============================================

   As an example of what this means in practice, imagine writing a
testbed for an application that is tested by submitting various
requests (via a C interface) and validating the output received.
Suppose further that the application keeps an idea of its current
state, and that the "correct" output for a given request may depend on
the current application state.  A complete "white box"(1) test plan for
this application would aim to submit all possible requests in each
distinguishable state, and validate the output for all request/state
combinations.

   To write all this test code in C would be very tedious.  Suppose
instead that the testbed code adds a single new C function, to submit an
arbitrary request and return the response, and then uses Guile to export
this function as a Scheme procedure.  The rest of the testbed can then
be written in Scheme, and so benefits from all the advantages of
programming in Scheme that were described in the previous section.

   (In this particular example, there is an additional benefit of
writing most of the testbed in Scheme.  A common problem for white box
testing is that mistakes and mistaken assumptions in the application
under test can easily be reproduced in the testbed code.  It is more
difficult to copy mistakes like this when the testbed is written in a
different language from the application.)

   ---------- Footnotes ----------

   (1) A "white box" test plan is one that incorporates knowledge of
the internal design of the application under test.

A Choice of Programming Options
===============================

   The preceding arguments and example point to a model of Guile
programming that is applicable in many cases.  According to this model,
Guile programming involves a balance between C and Scheme programming,
with the aim being to extract the greatest possible Scheme level benefit
from the least amount of C level work.

   The C level work required in this model usually consists of packaging
and exporting functions and application objects such that they can be
seen and manipulated on the Scheme level.  To help with this, Guile's C
language interface includes utility features that aim to make this kind
of integration very easy for the application developer.  These features
are documented later in this part of the manual: see REFFIXME.

   This model, though, is really just one of a range of possible
programming options.  If all of the functionality that you need is
available from Scheme, you could choose instead to write your whole
application in Scheme (or one of the other high level languages that
Guile supports through translation), and simply use Guile as an
interpreter for Scheme.  (In the future, we hope that Guile will also be
able to compile Scheme code, so lessening the performance gap between C
and Scheme code.)  Or, at the other end of the C-Scheme scale, you
could write the majority of your application in C, and only call out to
Guile occasionally for specific actions such as reading a configuration
file or executing a user-specified extension.  The choices boil down to
two basic questions:

   * Which parts of the application do you write in C, and which in
     Scheme (or another high level translated language)?

   * How do you design the interface between the C and Scheme parts of
     your application?

   These are of course design questions, and the right design for any
given application will always depend upon the particular requirements
that you are trying to meet.  In the context of Guile, however, there
are some generally applicable considerations that can help you when
designing your answers.