doc/ref/api-snarf.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Guile Reference Manual.
   3 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7
   8 @node Snarfing Macros
   9 @section Snarfing Macros
  10 @cindex guile-snarf recognized macros
  11 @cindex guile-snarf deprecated macros
  12
  13 The following macros do two different things: when compiled normally,
  14 they expand in one way; when processed during snarfing, they cause the
  15 @code{guile-snarf} program to pick up some initialization code,
  16 @xref{Function Snarfing}.
  17
  18 The descriptions below use the term `normally' to refer to the case
  19 when the code is compiled normally, and `while snarfing' when the code
  20 is processed by @code{guile-snarf}.
  21
  22 @deffn {C Macro} SCM_SNARF_INIT (code)
  23
  24 Normally, @code{SCM_SNARF_INIT} expands to nothing; while snarfing, it
  25 causes @var{code} to be included in the initialization action file,
  26 followed by a semicolon.
  27
  28 This is the fundamental macro for snarfing initialization actions.
  29 The more specialized macros below use it internally.
  30 @end deffn
  31
  32
  33 @deffn {C Macro} SCM_DEFINE (c_name, scheme_name, req, opt, var, arglist, docstring)
  34
  35 Normally, this macro expands into
  36
  37 @smallexample
  38 static const char s_@var{c_name}[] = @var{scheme_name};
  39 SCM
  40 @var{c_name} @var{arglist}
  41 @end smallexample
  42
  43 While snarfing, it causes
  44
  45 @smallexample
  46 scm_c_define_gsubr (s_@var{c_name}, @var{req}, @var{opt}, @var{var},
  47                     @var{c_name});
  48 @end smallexample
  49
  50 to be added to the initialization actions.  Thus, you can use it to
  51 declare a C function named @var{c_name} that will be made available to
  52 Scheme with the name @var{scheme_name}.
  53
  54 Note that the @var{arglist} argument must have parentheses around it.
  55 @end deffn
  56
  57 @deffn {C Macro} SCM_SYMBOL (c_name, scheme_name)
  58 @deffnx {C Macro} SCM_GLOBAL_SYMBOL (c_name, scheme_name)
  59 Normally, these macros expand into
  60
  61 @smallexample
  62 static SCM @var{c_name}
  63 @end smallexample
  64
  65 or
  66
  67 @smallexample
  68 SCM @var{c_name}
  69 @end smallexample
  70
  71 respectively.  While snarfing, they both expand into the
  72 initialization code
  73
  74 @smallexample
  75 @var{c_name} = scm_permanent_object (scm_from_locale_symbol (@var{scheme_name}));
  76 @end smallexample
  77
  78 Thus, you can use them declare a static or global variable of type
  79 @code{SCM} that will be initialized to the symbol named
  80 @var{scheme_name}.
  81 @end deffn
  82
  83 @deffn {C Macro} SCM_KEYWORD (c_name, scheme_name)
  84 @deffnx {C Macro} SCM_GLOBAL_KEYWORD (c_name, scheme_name)
  85 Normally, these macros expand into
  86
  87 @smallexample
  88 static SCM @var{c_name}
  89 @end smallexample
  90
  91 or
  92
  93 @smallexample
  94 SCM @var{c_name}
  95 @end smallexample
  96
  97 respectively.  While snarfing, they both expand into the
  98 initialization code
  99
 100 @smallexample
 101 @var{c_name} = scm_permanent_object (scm_c_make_keyword (@var{scheme_name}));
 102 @end smallexample
 103
 104 Thus, you can use them declare a static or global variable of type
 105 @code{SCM} that will be initialized to the keyword named
 106 @var{scheme_name}.
 107 @end deffn
 108
 109 @deffn {C Macro} SCM_VARIABLE (c_name, scheme_name)
 110 @deffnx {C Macro} SCM_GLOBAL_VARIABLE (c_name, scheme_name)
 111 These macros are equivalent to @code{SCM_VARIABLE_INIT} and
 112 @code{SCM_GLOBAL_VARIABLE_INIT}, respectively, with a @var{value} of
 113 @code{SCM_BOOL_F}.
 114 @end deffn
 115
 116 @deffn {C Macro} SCM_VARIABLE_INIT (c_name, scheme_name, value)
 117 @deffnx {C Macro} SCM_GLOBAL_VARIABLE_INIT (c_name, scheme_name, value)
 118
 119 Normally, these macros expand into
 120
 121 @smallexample
 122 static SCM @var{c_name}
 123 @end smallexample
 124
 125 or
 126
 127 @smallexample
 128 SCM @var{c_name}
 129 @end smallexample
 130
 131 respectively.  While snarfing, they both expand into the
 132 initialization code
 133
 134 @smallexample
 135 @var{c_name} = scm_permanent_object (scm_c_define (@var{scheme_name}, @var{value}));
 136 @end smallexample
 137
 138 Thus, you can use them declare a static or global C variable of type
 139 @code{SCM} that will be initialized to the object representing the
 140 Scheme variable named @var{scheme_name} in the current module.  The
 141 variable will be defined when it doesn't already exist.  It is always
 142 set to @var{value}.
 143 @end deffn