Commit | Line | Data |
---|---|---|
07d83abe MV |
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 | |
c310ad4f | 75 | @var{c_name} = scm_permanent_object (scm_from_locale_symbol (@var{scheme_name})); |
07d83abe MV |
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 | |
c310ad4f | 101 | @var{c_name} = scm_permanent_object (scm_c_make_keyword (@var{scheme_name})); |
07d83abe MV |
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 | |
c310ad4f | 135 | @var{c_name} = scm_permanent_object (scm_c_define (@var{scheme_name}, @var{value})); |
07d83abe MV |
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 | |
c310ad4f | 140 | Scheme variable named @var{scheme_name} in the current module. The |
07d83abe MV |
141 | variable will be defined when it doesn't already exist. It is always |
142 | set to @var{value}. | |
143 | @end deffn |