doc/Guile.notes

   1
   2 Notes on the adding guile as the extension language to gwave.
   3
   4
   5
   6
   7 For my first attempt at SMOBifying GWDataFile, I'll try this model:
   8
   9 The allocation and destruction of the structure stays as-is in C.
  10
  11 Add a "guile has a pointer" flag to the GWDataFile structure.  Set the
  12 flag whenever we give guile a pointer to the structure.  If guile
  13 calls the free_GWDataFile() routine and we want to keep the structure,
  14 (usual case), just clear the flag.
  15
  16 If delete_wave_file() is called and guile-has-pointer is set, we don't
  17 actually g_free() the structure, but rather just mark it as invalid.
  18 (in this case, by freeing and setting to NULL the WaveFile pointer.
  19
  20 NOTE!! this only works so long as we only ever create one SMOB for each
  21 GWDataFile.  We should call SGT_NEWCELL_SMOB once, and then keep a copy of it.
  22
  23 -----------------------------------------------------------------------------
  24
  25 Adding a simple primitive to guile - this has been borrowed from SCWM
  26
  27 SCWM_PROC(fname,primname, req, opt, var, ARGLIST)
  28 #define FUNC_NAME s_fname
  29
  30 fname - name of C function
  31 primname - guileified version of fname, underscores become dashes, etc.
  32 req, opt, var - passed to scm_make_gsubr
  33         req - number of required args
  34         opt - number of optional args
  35         var - number of rest args??
  36
  37 ARGLIST - actual list of parameters to C function decl;
  38         must be a parenthesized list.
  39
  40 FUNC_NAME define must be s_ prepended to fname (the guile symbol variable name)
  41
  42 Inside the body of the function, use the VALIDATE_ macros to check
  43 each argument to make sure it is the right type before using it. These
  44 will throw a guile error if the type doesn't match.
  45
  46 -----------------------------------------------------------------------------
  47 Turning a C structure into a SMOB in N easy steps:
  48
  49 Remember this: You hand off to guile a pointer to your allocated C structure.
  50 guile may copy that pointer about, but it never fiddles with what's inside;
  51 it especialy doesn't try copying the contents of your structure.
  52
  53
  54
  55 1. to SMOBify a data structure GwDataFIle:
  56 In appropriate header file, add:
  57
  58 declaration for guile's object-type-ID tag:
  59         EXTERN long scm_tc16_scwm_GWDataFile;
  60
  61 The test cast macros:
  62
  63 #define GWDataFile_P(X) (SCM_NIMP(X) && gh_car(X) == (SCM)scm_tc16_scwm_GWDataFile)
  64 #define GWDataFile(X)  ((GWDataFile *)gh_cdr(X))
  65 #define SAFE_GWDataFile(X)  (GWDataFile_P((X))? GWDataFile((X)) : NULL)
  66
  67 Whatever validation macros are needed for the ways you'll use the thing:
  68
  69 #define VALIDATE_ARG_GWDataFile(pos,scm) \
  70
  71 2. In the appropriate.c file, say wavelist.c:
  72
  73 2a. Write the three SMOB-required functions,
  74         free, mark, and print
  75
  76 2b. Write the test-predicate function, GWDataFile?.
  77 Just copy and modify an existing one; it really just calls GWDataFile_P
  78
  79 2a. right before the wavelist_init() function, add:
  80         MAKE_SMOBFUNS(GWDataFile);
  81
  82 2b. add to wavelist_init() function:
  83         REGISTER_SCWMSMOBFUNS(GWDataFile);