]>
Commit | Line | Data |
---|---|---|
1 | Index: Source/Modules/python.cxx | |
2 | =================================================================== | |
3 | RCS file: /cvsroot/SWIG/Source/Modules/python.cxx,v | |
4 | retrieving revision 1.39 | |
5 | diff -u -4 -r1.39 python.cxx | |
6 | --- Source/Modules/python.cxx 22 Jan 2004 22:42:17 -0000 1.39 | |
7 | +++ Source/Modules/python.cxx 22 Jan 2004 23:39:03 -0000 | |
8 | @@ -50,8 +50,17 @@ | |
9 | static int have_constructor; | |
10 | static int have_repr; | |
11 | static String *real_classname; | |
12 | ||
13 | +/* flags for the make_autodoc function */ | |
14 | +enum autodoc_t { | |
15 | + AUTODOC_CLASS, | |
16 | + AUTODOC_CTOR, | |
17 | + AUTODOC_DTOR, | |
18 | + AUTODOC_STATICFUNC, | |
19 | + AUTODOC_FUNC | |
20 | +}; | |
21 | + | |
22 | static const char *usage = (char *)"\ | |
23 | Python Options (available with -python)\n\ | |
24 | -ldflags - Print runtime libraries to link with\n\ | |
25 | -globals <name> - Set <name> used to access C global variable [default: 'cvar']\n\ | |
26 | @@ -417,17 +426,23 @@ | |
27 | * functions. | |
28 | * ------------------------------------------------------------ */ | |
29 | ||
30 | void emitFunctionShadowHelper(Node *n, File *f_dest, String *name, int kw) { | |
31 | - if ( ! have_addtofunc(n) ) { | |
32 | - /* If there is no addtofunc directive then just assign from the extension module */ | |
33 | + if ( ! have_addtofunc(n) && ! have_docstring(n) ) { | |
34 | + /* If there is no addtofunc or docstring directive then just assign from the extension module */ | |
35 | Printv(f_dest, "\n", name, " = ", module, ".", name, "\n", NIL); | |
36 | } else { | |
37 | /* Otherwise make a wrapper function to insert the code into */ | |
38 | Printv(f_dest, "\ndef ", name, "(*args", (kw ? ", **kwargs" : ""), "):\n", NIL); | |
39 | - Printv(f_dest, tab4, "val = ", funcCallHelper(name, kw), "\n", NIL); | |
40 | - Printv(f_dest, tab4, addtofunc(n), "\n", NIL); | |
41 | - Printv(f_dest, tab4, "return val\n", NIL); | |
42 | + if ( have_docstring(n) ) | |
43 | + Printv(f_dest, tab4, docstring(n, AUTODOC_FUNC, tab4), "\n", NIL); | |
44 | + if ( have_addtofunc(n) ) { | |
45 | + Printv(f_dest, tab4, "val = ", funcCallHelper(name, kw), "\n", NIL); | |
46 | + Printv(f_dest, tab4, addtofunc(n), "\n", NIL); | |
47 | + Printv(f_dest, tab4, "return val\n", NIL); | |
48 | + } else { | |
49 | + Printv(f_dest, tab4, "return ", funcCallHelper(name, kw), "\n", NIL); | |
50 | + } | |
51 | } | |
52 | } | |
53 | ||
54 | ||
55 | @@ -441,8 +456,256 @@ | |
56 | } | |
57 | ||
58 | ||
59 | /* ------------------------------------------------------------ | |
60 | + * have_docstring() | |
61 | + * Check if there is a docstring directive and it has text, | |
62 | + * or there is an autodoc flag set | |
63 | + * ------------------------------------------------------------ */ | |
64 | + | |
65 | + bool have_docstring(Node *n) { | |
66 | + String* str = Getattr(n, "feature:docstring"); | |
67 | + return (str != NULL && Len(str) > 0) || | |
68 | + (Getattr(n,"feature:autodoc") && !Getattr(n, "feature:noautodoc")); | |
69 | + } | |
70 | + | |
71 | + /* ------------------------------------------------------------ | |
72 | + * docstring() | |
73 | + * Get the docstring text, stripping off {} if neccessary, | |
74 | + * and enclose in triple double quotes. If autodoc is also | |
75 | + * set then it will build a combined docstring. | |
76 | + * ------------------------------------------------------------ */ | |
77 | + | |
78 | + String *docstring(Node *n, autodoc_t ad_type, const String* indent) { | |
79 | + String* str = Getattr(n, "feature:docstring"); | |
80 | + bool have_ds = (str != NULL && Len(str) > 0); | |
81 | + bool have_auto = (Getattr(n,"feature:autodoc") && !Getattr(n, "feature:noautodoc")); | |
82 | + char* triple_double = "\"\"\""; | |
83 | + String* autodoc = NULL; | |
84 | + String* doc = NULL; | |
85 | + | |
86 | + if ( have_ds ) { | |
87 | + char* t = Char(str); | |
88 | + if (*t == '{') { | |
89 | + Delitem(str ,0); | |
90 | + Delitem(str,DOH_END); | |
91 | + } | |
92 | + } | |
93 | + | |
94 | + if ( have_auto ) { | |
95 | + autodoc = make_autodoc(n, ad_type); | |
96 | + have_auto = (autodoc != NULL && Len(autodoc) > 0); | |
97 | + } | |
98 | + | |
99 | +// if ( have_auto && have_ds ) | |
100 | +// doc = NewStringf("%s%s\n\n%s%s", triple_double, autodoc, str, triple_double); | |
101 | +// else if ( !have_auto && have_ds ) | |
102 | +// doc = NewStringf("%s%s%s", triple_double, str, triple_double); | |
103 | +// else | |
104 | +// doc = NewStringf("%s%s%s", triple_double, autodoc, triple_double); | |
105 | + | |
106 | + | |
107 | + // If there is more than one line then make docstrings like this: | |
108 | + // | |
109 | + // """ | |
110 | + // This is line1 | |
111 | + // And here is line2 followed by the rest of them | |
112 | + // """ | |
113 | + // | |
114 | + // otherwise, put it all on a single line | |
115 | + // | |
116 | + if ( have_auto && have_ds ) { // Both autodoc and docstring are present | |
117 | + doc = NewString(""); | |
118 | + Printv(doc, triple_double, "\n", | |
119 | + pythoncode(autodoc, indent), "\n", | |
120 | + pythoncode(str, indent), | |
121 | + indent, triple_double, NIL); | |
122 | + } | |
123 | + else if ( !have_auto && have_ds ) { // only docstring | |
124 | + if (Strchr(str, '\n') == NULL) { | |
125 | + doc = NewStringf("%s%s%s", triple_double, str, triple_double); | |
126 | + } | |
127 | + else { | |
128 | + doc = NewString(""); | |
129 | + Printv(doc, triple_double, "\n", | |
130 | + pythoncode(str, indent), | |
131 | + indent, triple_double, NIL); | |
132 | + } | |
133 | + } | |
134 | + else if ( have_auto && !have_ds ) { // only autodoc | |
135 | + if (Strchr(autodoc, '\n') == NULL) { | |
136 | + doc = NewStringf("%s%s%s", triple_double, autodoc, triple_double); | |
137 | + } | |
138 | + else { | |
139 | + doc = NewString(""); | |
140 | + Printv(doc, triple_double, "\n", | |
141 | + pythoncode(autodoc, indent), | |
142 | + indent, triple_double, NIL); | |
143 | + } | |
144 | + } | |
145 | + else | |
146 | + doc = NewString(""); | |
147 | + | |
148 | + // Save the generated strings in the parse tree in case they are used later | |
149 | + // by post processing tools | |
150 | + Setattr(n, "python:docstring", doc); | |
151 | + Setattr(n, "python:autodoc", autodoc); | |
152 | + return doc; | |
153 | + } | |
154 | + | |
155 | + | |
156 | + /* ------------------------------------------------------------ | |
157 | + * make_autodoc() | |
158 | + * Build a docstring for the node, using parameter and other | |
159 | + * info in the parse tree. If the value of the autodoc | |
160 | + * attribute is "0" then do not include parameter types, if | |
161 | + * it is "1" (the default) then do. If it has some other | |
162 | + * value then assume it is supplied by the extension writer | |
163 | + * and use it directly. | |
164 | + * ------------------------------------------------------------ */ | |
165 | + | |
166 | + String* make_autodoc(Node *n, autodoc_t ad_type) { | |
167 | + | |
168 | + if (ad_type == AUTODOC_CLASS) | |
169 | + return NULL; // No function call to document in this case | |
170 | + | |
171 | + // If the function is overloaded then this funciton is called | |
172 | + // for the last one. Rewind to the first so the docstrings are | |
173 | + // in order. | |
174 | + while ( Getattr(n, "sym:previousSibling") ) | |
175 | + n = Getattr(n, "sym:previousSibling"); | |
176 | + | |
177 | + String* doc = NewString(""); | |
178 | + while (n) { | |
179 | + bool showTypes = false; | |
180 | + bool skipAuto = false; | |
181 | + | |
182 | + // check how should the parameters be rendered? | |
183 | + String* autodoc = Getattr(n, "feature:autodoc"); | |
184 | + if (Strcmp(autodoc, "0") == 0) | |
185 | + showTypes = false; | |
186 | + else if (Strcmp(autodoc, "1") == 0) | |
187 | + showTypes = true; | |
188 | + else { | |
189 | + // if not "0" or "1" then autodoc is already the string that should be used | |
190 | + Printf(doc, "%s", autodoc); | |
191 | + skipAuto = true; | |
192 | + } | |
193 | + | |
194 | + if (!skipAuto) { | |
195 | + String* symname = Getattr(n, "sym:name"); | |
196 | + SwigType* type = Getattr(n, "type"); | |
197 | + | |
198 | + if (type) { | |
199 | + if (Strcmp(type, "void") == 0) | |
200 | + type = NULL; | |
201 | + else { | |
202 | + SwigType* qt = SwigType_typedef_resolve_all(type); | |
203 | + if (SwigType_isenum(qt)) | |
204 | + type = NewString("int"); | |
205 | + else { | |
206 | + type = SwigType_base(type); | |
207 | + Node* lookup = Swig_symbol_clookup(type, 0); | |
208 | + if (lookup) | |
209 | + type = Getattr(lookup, "sym:name"); | |
210 | + } | |
211 | + } | |
212 | + } | |
213 | + | |
214 | + switch ( ad_type ) { | |
215 | + case AUTODOC_CTOR: | |
216 | + if ( Strcmp(class_name, symname) == 0) | |
217 | + Printf(doc, "__init__(%s) -> %s", make_autodocParmList(n, showTypes), class_name); | |
218 | + else | |
219 | + Printf(doc, "%s(%s) -> %s", symname, make_autodocParmList(n, showTypes), class_name); | |
220 | + break; | |
221 | + | |
222 | + case AUTODOC_DTOR: | |
223 | + Printf(doc, "__del__()"); | |
224 | + break; | |
225 | + | |
226 | + case AUTODOC_STATICFUNC: | |
227 | + Printf(doc, "%s(%s)", symname, make_autodocParmList(n, showTypes)); | |
228 | + if (type) Printf(doc, " -> %s", type); | |
229 | + break; | |
230 | + | |
231 | + case AUTODOC_FUNC: | |
232 | + Printf(doc, "%s(%s)", symname, make_autodocParmList(n, showTypes)); | |
233 | + if (type) Printf(doc, " -> %s", type); | |
234 | + break; | |
235 | + } | |
236 | + } | |
237 | + | |
238 | + // if it's overloaded then get the next decl and loop around again | |
239 | + n = Getattr(n, "sym:nextSibling"); | |
240 | + if (n) | |
241 | + Printf(doc, "\n"); | |
242 | + } | |
243 | + | |
244 | + return doc; | |
245 | + } | |
246 | + | |
247 | + | |
248 | + String* make_autodocParmList(Node* n, bool showTypes) { | |
249 | + String* doc = NewString(""); | |
250 | + ParmList* plist = Getattr(n,"parms"); | |
251 | + Parm* p; | |
252 | + Node* lookup; | |
253 | + int lines = 0; | |
254 | + const int maxwidth = 50; | |
255 | + | |
256 | + | |
257 | + for (p = plist; p; p = nextSibling(p)) { | |
258 | + String* name = Getattr(p, "name"); | |
259 | + String* value = Getattr(p, "value"); | |
260 | + | |
261 | + if ( Len(doc) ) { | |
262 | + // add a comma to the previous one if any | |
263 | + Printf(doc, ", "); | |
264 | + | |
265 | + // Do we need to wrap a long line? | |
266 | + if ((Len(doc) - lines*maxwidth) > maxwidth) { | |
267 | + Printf(doc, "\n%s", tab4); | |
268 | + lines += 1; | |
269 | + } | |
270 | + } | |
271 | + | |
272 | + // Do the param type too? | |
273 | + if (showTypes) { | |
274 | + SwigType* type = SwigType_base(Getattr(p, "type")); | |
275 | + SwigType* qt = SwigType_typedef_resolve_all(type); | |
276 | + if (SwigType_isenum(qt)) | |
277 | + type = NewString("int"); | |
278 | + else { | |
279 | + lookup = Swig_symbol_clookup(type, 0); | |
280 | + if (lookup) | |
281 | + type = Getattr(lookup, "sym:name"); | |
282 | + } | |
283 | + Printf(doc, "%s ", type); | |
284 | + } | |
285 | + | |
286 | + if (name) | |
287 | + Printf(doc, "%s", name); | |
288 | + else | |
289 | + Printf(doc, "??"); | |
290 | + | |
291 | + if (value) { | |
292 | + if (Strcmp(value, "NULL") == 0) | |
293 | + value = NewString("None"); | |
294 | + else { | |
295 | + lookup = Swig_symbol_clookup(value, 0); | |
296 | + if (lookup) | |
297 | + value = Getattr(lookup, "sym:name"); | |
298 | + } | |
299 | + Printf(doc, "=%s", value); | |
300 | + } | |
301 | + } | |
302 | + | |
303 | + return doc; | |
304 | + } | |
305 | + | |
306 | + | |
307 | + /* ------------------------------------------------------------ | |
308 | * have_addtofunc() | |
309 | * Check if there is a %addtofunc directive and it has text | |
310 | * ------------------------------------------------------------ */ | |
311 | ||
312 | @@ -1698,9 +1961,11 @@ | |
313 | Printf(f_shadow, modern ? "(object)" : "(_object)"); | |
314 | } | |
315 | } | |
316 | Printf(f_shadow,":\n"); | |
317 | - | |
318 | + if ( Getattr(n, "feature:docstring") ) // don't use have_docstring in this case because autodoc doesn't apply | |
319 | + Printv(f_shadow, tab4, docstring(n, AUTODOC_CLASS, tab4), "\n", NIL); | |
320 | + | |
321 | if (!modern) { | |
322 | Printv(f_shadow,tab4,"__swig_setmethods__ = {}\n",NIL); | |
323 | if (Len(base_class)) { | |
324 | Printf(f_shadow,"%sfor _s in [%s]: __swig_setmethods__.update(_s.__swig_setmethods__)\n",tab4,base_class); | |
325 | @@ -1833,16 +2098,22 @@ | |
326 | Delete(pyaction); | |
327 | Printv(f_shadow,pycode,"\n",NIL); | |
328 | } else { | |
329 | ||
330 | - Printv(f_shadow, tab4, "def ", symname, "(*args", (allow_kwargs ? ", **kwargs" : ""), "): ", NIL); | |
331 | - if ( have_addtofunc(n) ) { | |
332 | - Printv(f_shadow, "\n", NIL); | |
333 | - Printv(f_shadow, tab8, "val = ", funcCallHelper(Swig_name_member(class_name,symname), allow_kwargs), "\n", NIL); | |
334 | - Printv(f_shadow, tab8, addtofunc(n), "\n", NIL); | |
335 | - Printv(f_shadow, tab8, "return val\n", NIL); | |
336 | + Printv(f_shadow, tab4, "def ", symname, "(*args", (allow_kwargs ? ", **kwargs" : ""), "):", NIL); | |
337 | + if ( ! have_addtofunc(n) && ! have_docstring(n)) { | |
338 | + Printv(f_shadow, " return ", funcCallHelper(Swig_name_member(class_name,symname), allow_kwargs), "\n", NIL); | |
339 | } else { | |
340 | - Printv(f_shadow, "return ", funcCallHelper(Swig_name_member(class_name,symname), allow_kwargs), "\n", NIL); | |
341 | + Printv(f_shadow, "\n", NIL); | |
342 | + if ( have_docstring(n) ) | |
343 | + Printv(f_shadow, tab8, docstring(n, AUTODOC_FUNC, tab8), "\n", NIL); | |
344 | + if ( have_addtofunc(n) ) { | |
345 | + Printv(f_shadow, tab8, "val = ", funcCallHelper(Swig_name_member(class_name,symname), allow_kwargs), "\n", NIL); | |
346 | + Printv(f_shadow, tab8, addtofunc(n), "\n", NIL); | |
347 | + Printv(f_shadow, tab8, "return val\n\n", NIL); | |
348 | + } else { | |
349 | + Printv(f_shadow, tab8, "return ", funcCallHelper(Swig_name_member(class_name,symname), allow_kwargs), "\n\n", NIL); | |
350 | + } | |
351 | } | |
352 | } | |
353 | ||
354 | } | |
355 | @@ -1857,14 +2128,20 @@ | |
356 | virtual int staticmemberfunctionHandler(Node *n) { | |
357 | String *symname = Getattr(n,"sym:name"); | |
358 | Language::staticmemberfunctionHandler(n); | |
359 | if (shadow) { | |
360 | - if ( !classic && have_addtofunc(n) ) { | |
361 | + if ( !classic && (have_addtofunc(n) || have_docstring(n)) ) { | |
362 | int kw = (check_kwargs(n) && !Getattr(n,"sym:overloaded")) ? 1 : 0; | |
363 | Printv(f_shadow, tab4, "def ", symname, "(*args", (kw ? ", **kwargs" : ""), "):\n", NIL); | |
364 | - Printv(f_shadow, tab8, "val = ", funcCallHelper(Swig_name_member(class_name, symname), kw), "\n", NIL); | |
365 | - Printv(f_shadow, tab8, addtofunc(n), "\n", NIL); | |
366 | - Printv(f_shadow, tab8, "return val\n", NIL); | |
367 | + if ( have_docstring(n) ) | |
368 | + Printv(f_shadow, tab8, docstring(n, AUTODOC_STATICFUNC, tab8), "\n", NIL); | |
369 | + if ( have_addtofunc(n) ) { | |
370 | + Printv(f_shadow, tab8, "val = ", funcCallHelper(Swig_name_member(class_name, symname), kw), "\n", NIL); | |
371 | + Printv(f_shadow, tab8, addtofunc(n), "\n", NIL); | |
372 | + Printv(f_shadow, tab8, "return val\n\n", NIL); | |
373 | + } else { | |
374 | + Printv(f_shadow, tab8, "return ", funcCallHelper(Swig_name_member(class_name, symname), kw), "\n\n", NIL); | |
375 | + } | |
376 | Printv(f_shadow, tab4, modern ? "" : "if _newclass:", symname, | |
377 | " = staticmethod(", symname, ")\n", NIL); | |
378 | ||
379 | if (!modern) { | |
380 | @@ -1949,8 +2226,10 @@ | |
381 | } | |
382 | ||
383 | Printv(f_shadow, tab4, "def __init__(self, *args", | |
384 | (allow_kwargs ? ", **kwargs" : ""), "):\n", NIL); | |
385 | + if ( have_docstring(n) ) | |
386 | + Printv(f_shadow, tab8, docstring(n, AUTODOC_CTOR, tab8), "\n", NIL); | |
387 | Printv(f_shadow, pass_self, NIL); | |
388 | if (!modern) { | |
389 | Printv(f_shadow, tab8, "_swig_setattr(self, ", rclassname, ", 'this', ", | |
390 | funcCallHelper(Swig_name_construct(symname), allow_kwargs), ")\n", NIL); | |
391 | @@ -1964,9 +2243,9 @@ | |
392 | Printv(f_shadow, tab8, "self.thisown = 1\n", NIL); | |
393 | Printv(f_shadow, tab8, "del newobj.thisown\n", NIL); | |
394 | } | |
395 | if ( have_addtofunc(n) ) | |
396 | - Printv(f_shadow, tab8, addtofunc(n), "\n", NIL); | |
397 | + Printv(f_shadow, tab8, addtofunc(n), "\n\n", NIL); | |
398 | Delete(pass_self); | |
399 | } | |
400 | have_constructor = 1; | |
401 | } else { | |
402 | @@ -1982,8 +2261,10 @@ | |
403 | } else { | |
404 | ||
405 | Printv(f_shadow_stubs, "\ndef ", symname, "(*args", | |
406 | (allow_kwargs ? ", **kwargs" : ""), "):\n", NIL); | |
407 | + if ( have_docstring(n) ) | |
408 | + Printv(f_shadow_stubs, tab4, docstring(n, AUTODOC_CTOR, tab4), "\n", NIL); | |
409 | Printv(f_shadow_stubs, tab4, "val = ", | |
410 | funcCallHelper(Swig_name_construct(symname), allow_kwargs), "\n", NIL); | |
411 | Printv(f_shadow_stubs, tab4, "val.thisown = 1\n", NIL); | |
412 | if ( have_addtofunc(n) ) | |
413 | @@ -2015,13 +2296,15 @@ | |
414 | Delete(pyaction); | |
415 | Printv(f_shadow,pycode,"\n", NIL); | |
416 | } else { | |
417 | Printv(f_shadow, tab4, "def __del__(self, destroy=", module, ".", Swig_name_destroy(symname), "):\n", NIL); | |
418 | + if ( have_docstring(n) ) | |
419 | + Printv(f_shadow, tab8, docstring(n, AUTODOC_DTOR, tab8), "\n", NIL); | |
420 | if ( have_addtofunc(n) ) | |
421 | Printv(f_shadow, tab8, addtofunc(n), "\n", NIL); | |
422 | Printv(f_shadow, tab8, "try:\n", NIL); | |
423 | - Printv(f_shadow, tab4, tab8, "if self.thisown: destroy(self)\n", NIL); | |
424 | - Printv(f_shadow, tab8, "except: pass\n", NIL); | |
425 | + Printv(f_shadow, tab8, tab4, "if self.thisown: destroy(self)\n", NIL); | |
426 | + Printv(f_shadow, tab8, "except: pass\n\n", NIL); | |
427 | } | |
428 | } | |
429 | return SWIG_OK; | |
430 | } |