guile18/examples/box-dynamic-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, putting it into a shared library, so it
   7 can be called from an unmodified guile interpreter. Further, the shared
   8 library defines a new guile module.
   9
  10
  11 * Build Instructions
  12
  13 To build the example, simply type
  14
  15   make libbox-module
  16
  17 in this directory.
  18
  19
  20 * The Box Data Type
  21
  22 A box is simply an object for storing one other object in.  It can be
  23 used for passing parameters by reference, for example.  You simply
  24 store an object into a box, pass it to another procedure which can
  25 store a new object into it and thus return a value via the box.
  26
  27
  28 ** Usage
  29
  30 Box objects are created with `make-box', set with `box-set!' and
  31 examined with `box-ref'.  Note that these procedures are placed in a
  32 module called (box-module) and can thus only be accessed after using
  33 this module.  See the following example session for usage details.
  34
  35
  36 ** The Module (box-module)
  37
  38 Extend your LD_LIBRARY_PATH variable (or equivalent) to include . and
  39 .libs and make sure that your current working directory is the one
  40 this file is contained in.
  41
  42 $ guile
  43 guile> (use-modules (box-module))
  44 guile> (define b (make-box))
  45 guile> b
  46 #<box #f>
  47 guile> (box-set! b '(list of values))
  48 guile> b
  49 #<box (list of values)>
  50 guile> (box-ref b)
  51 (list of values)
  52 guile> (quit)
  53 $
  54
  55
  56 ** The Module (box-mixed)
  57
  58 The following example uses the module (box-mixed), also included in
  59 this directory.  It uses the shared library libbox-module like the
  60 module (box-module) above, but does not export the procedures from
  61 that module.  It only implements some procedures for dealing with box
  62 objects.
  63
  64 $ guile
  65 guile> (use-modules (box-mixed))
  66 guile> (define bl  (make-box-list 1 2 3))
  67 guile> bl
  68 (#<box 1> #<box 2> #<box 3>)
  69 guile> (box-map 1+ bl)
  70 (#<box 2> #<box 3> #<box 4>)
  71 guile> (quit)
  72 $
  73
  74 If you like this example so much that you want to have it available
  75 for normal usage, install the dynamic libraries in the .libs directory
  76 to the directory $(prefix)/lib and the scheme file `box-module.scm' in
  77 a directory in your GUILE_LOAD_PATH.