This is guile.info, produced by makeinfo version 4.3 from guile.texi. INFO-DIR-SECTION The Algorithmic Language Scheme START-INFO-DIR-ENTRY * Guile Reference: (guile). The Guile reference manual. END-INFO-DIR-ENTRY 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.  File: guile.info, Node: Chaining, Next: Lexical Scope, Prev: Local Variables, Up: About Closure 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.  File: guile.info, Node: Lexical Scope, Next: Closure, Prev: Chaining, Up: About Closure 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. * Menu: * Scoping Example:: An example of non-lexical scoping.  File: guile.info, Node: Scoping Example, Up: Lexical Scope 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.  File: guile.info, Node: Closure, Next: Serial Number, Prev: Lexical Scope, Up: About Closure 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.  File: guile.info, Node: Serial Number, Next: Shared Variable, Prev: Closure, Up: About Closure 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.  File: guile.info, Node: Shared Variable, Next: Callback Closure, Prev: Serial Number, Up: About Closure 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.  File: guile.info, Node: Callback Closure, Next: OO Closure, Prev: Shared Variable, Up: About Closure 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 () ... ...)) (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.  File: guile.info, Node: OO Closure, Prev: Callback Closure, Up: About Closure 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 => # 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.  File: guile.info, Node: Further Reading, Next: Programming Intro, Prev: Basic Ideas, Up: Top Further Reading *************** * The website is a good starting point for all things Scheme. * Dorai Sitaram's online Scheme tutorial, "Teach Yourself Scheme in Fixnum Days", at . 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 . 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.  File: guile.info, Node: Programming Intro, Next: Libguile Intro, Prev: Further Reading, Up: Top 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 (*note Part IV -- Guile API Reference: Reference Intro.).  File: guile.info, Node: Libguile Intro, Next: Programming Overview, Prev: Programming Intro, Up: Top 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 *Note 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 (*note 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.  File: guile.info, Node: Programming Overview, Next: Data Representation, Prev: Libguile Intro, Up: Top 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. * Menu: * Extending Dia:: How one might extend Dia using Guile. * Scheme vs C:: Why Scheme is more hackable than C. * Testbed Example:: Example: using Guile in a testbed. * Programming Options:: Options for Guile programming. * User Programming:: How about application users?  File: guile.info, Node: Extending Dia, Next: Scheme vs C, Up: Programming Overview 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. * Menu: * Dia Objective:: Deciding why you want to add Guile. * Dia Steps:: Four steps required to add Guile. * Dia Smobs:: How to represent Dia data in Scheme. * Dia Primitives:: Writing Guile primitives for Dia. * Dia Hook:: Providing a hook for Scheme evaluation. * Dia Structure:: Overall structure for adding Guile. * Dia Advanced:: Going further with Dia and Guile.  File: guile.info, Node: Dia Objective, Next: Dia Steps, Up: Extending Dia 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)))))  File: guile.info, Node: Dia Steps, Next: Dia Smobs, Prev: Dia Objective, Up: Extending Dia 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.  File: guile.info, Node: Dia Smobs, Next: Dia Primitives, Prev: Dia Steps, Up: Extending Dia 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 *Note Defining New Types (Smobs)::.  File: guile.info, Node: Dia Primitives, Next: Dia Hook, Prev: Dia Smobs, Up: Extending Dia 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 (*note Dia Structure::).  File: guile.info, Node: Dia Hook, Next: Dia Structure, Prev: Dia Primitives, Up: Extending Dia 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 ` :', 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.  File: guile.info, Node: Dia Structure, Next: Dia Advanced, Prev: Dia Hook, Up: Extending Dia 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.  File: guile.info, Node: Dia Advanced, Prev: Dia Structure, Up: Extending Dia 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 ...  File: guile.info, Node: Scheme vs C, Next: Testbed Example, Prev: Extending Dia, Up: Programming Overview 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 -- *note About Closure::) and for iteration (*note 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.  File: guile.info, Node: Testbed Example, Next: Programming Options, Prev: Scheme vs C, Up: Programming Overview 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.  File: guile.info, Node: Programming Options, Next: User Programming, Prev: Testbed Example, Up: Programming Overview 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. * Menu: * Available Functionality:: What functionality is already available? * Basic Constraints:: Functional and performance constraints. * Style Choices:: Your preferred programming style. * Program Control:: What controls program execution?