examples/box-module/README

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