guile18/examples/box-module/README

   1                                                                -*- outline -*-
   2
   3 * Overview
   4
   5 This directory includes an example program for extending Guile with a
   6 new (and even useful) data type.
   7
   8 The `box' program created by this example is nearly identical to the
   9 one produced in directory ../box, with one (important) difference: The
  10 interpreter in this directory will place all defined primitive
  11 procedures in a module called (box-module).  That means that this
  12 module must be used before the primitives can be accessed.
  13
  14
  15 * Build Instructions
  16
  17 To build the example, simply type
  18
  19   make box
  20
  21 in this directory.
  22
  23 The resulting `box' program is a Guile interpreter which has one
  24 additional data type called `box'.
  25
  26
  27 * The Box Data Type
  28
  29 A box is simply an object for storing one other object in.  It can be
  30 used for passing parameters by reference, for example.  You simply
  31 store an object into a box, pass it to another procedure which can
  32 store a new object into it and thus return a value via the box.
  33
  34
  35 ** Usage
  36
  37 Box objects are created with `make-box', set with `box-set!' and
  38 examined with `box-ref'.  Note that these procedures are placed in a
  39 module called (box-module) and can thus only be accessed after using
  40 this module.  See the following example session for usage details:
  41
  42
  43 ** Example Session
  44
  45 $ ./box
  46 guile> (use-modules (box-module))
  47 guile> (define b (make-box))
  48 guile> b
  49 #<box #f>
  50 guile> (box-set! b '(list of values))
  51 guile> b
  52 #<box (list of values)>
  53 guile> (box-ref b)
  54 (list of values)
  55 guile> (quit)
  56 $