Debian Codegraph @

geanygendoc/src/ggd.c

raw
1 /*
2 *
3 * GeanyGenDoc, a Geany plugin to ease generation of source code documentation
4 * Copyright (C) 2009-2011 Colomban Wendling <[email protected]>
5 *
6 * This program is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program. If not, see <http://www.gnu.org/licenses/>.
18 *
19 */
20
21 #ifdef HAVE_CONFIG_H
22 # include "config.h" /* for the gettext domain */
23 #endif
24
25 #include "ggd.h"
26
27 #include <string.h>
28 #include <ctype.h>
29 #include <glib.h>
30 #include <glib/gi18n-lib.h>
31 #include <ctpl/ctpl.h>
32 #include <geanyplugin.h>
33
34 #include "ggd-file-type.h"
35 #include "ggd-file-type-manager.h"
36 #include "ggd-utils.h"
37 #include "ggd-plugin.h"
38
39
40 /* sci_get_line_indentation() is not in the plugin API for now (API v183), then
41 * implement it -- borrowed from Geany's sciwrappers.c */
42 #ifndef sci_get_line_indentation
43 # define sci_get_line_indentation(sci, line) \
44 (scintilla_send_message (sci, SCI_GETLINEINDENTATION, line, 0))
45 #endif /* sci_get_line_indentation */
46
47
48 /* The value that replace the "cursor" variable in templates, used to find it
49 * and therefore the cursor position. This should be a value that the user never
50 * want to output; otherwise it would behave strangely from the user point of
51 * view, since it is removed from the output. */
52 #define GGD_CURSOR_IDENTIFIER "{cursor}"
53 #define GGD_CURSOR_IDENTIFIER_LEN 8
54
55 /* wrapper for ctpl_parser_parse() that returns a string. Free with g_free() */
56 static gchar *
57 parser_parse_to_string (const CtplToken *tree,
58 CtplEnviron *env,
59 GError **error)
60 {
61 GOutputStream *gostream;
62 CtplOutputStream *ostream;
63 gchar *output = NULL;
64
65 gostream = g_memory_output_stream_new (NULL, 0, g_try_realloc, NULL);
66 ostream = ctpl_output_stream_new (gostream);
67 if (ctpl_parser_parse (tree, env, ostream, error)) {
68 GMemoryOutputStream *memostream = G_MEMORY_OUTPUT_STREAM (gostream);
69 gsize size;
70 gsize data_size;
71
72 output = g_memory_output_stream_get_data (memostream);
73 size = g_memory_output_stream_get_size (memostream);
74 data_size = g_memory_output_stream_get_data_size (memostream);
75 if (size <= data_size) {
76 gpointer newptr;
77
78 newptr = g_try_realloc (output, size + 1);
79 if (newptr) {
80 output = newptr;
81 size ++;
82 } else {
83 /* not enough memory, simulate a memory output stream error */
84 g_set_error (error, G_IO_ERROR, G_IO_ERROR_NO_SPACE,
85 _("Failed to resize memory output stream"));
86 g_free (output);
87 output = NULL;
88 }
89 }
90 if (size > data_size) {
91 output[data_size] = 0;
92 }
93 }
94 ctpl_output_stream_unref (ostream);
95 g_object_unref (gostream);
96
97 return output;
98 }
99
100 /* extracts arguments from @args according to the given filetype */
101 static CtplValue *
102 get_arg_list_from_string (GgdFileType *ft,
103 const gchar *args)
104 {
105 CtplValue *arg_list = NULL;
106
107 g_return_val_if_fail (args != NULL, NULL);
108
109 if (ft->match_function_arguments) {
110 GMatchInfo *match_info;
111
112 /*g_debug ("Trying to match against \"%s\"", args);*/
113 if (! g_regex_match (ft->match_function_arguments, args, 0, &match_info)) {
114 msgwin_status_add (_("Argument parsing regular expression did not match "
115 "(argument list was: \"%s\")"), args);
116 } else {
117 arg_list = ctpl_value_new_array (CTPL_VTYPE_STRING, 0, NULL);
118
119 while (g_match_info_matches (match_info)) {
120 gchar *word = g_match_info_fetch (match_info, 1);
121
122 /*g_debug ("Found arg: '%s'", word);*/
123 if (word) {
124 ctpl_value_array_append_string (arg_list, word);
125 }
126 g_free (word);
127 g_match_info_next (match_info, NULL);
128 }
129 }
130 g_match_info_free (match_info);
131 }
132
133 return arg_list;
134 }
135
136 /* pushes @value into @env as @{symbol}_list */
137 static void
138 hash_table_env_push_list_cb (gpointer symbol,
139 gpointer value,
140 gpointer env)
141 {
142 gchar *symbol_name;
143
144 symbol_name = g_strconcat (symbol, "_list", NULL);
145 ctpl_environ_push (env, symbol_name, value);
146 g_free (symbol_name);
147 }
148
149 /* gets the environment for a particular tag */
150 static CtplEnviron *
151 get_env_for_tag (GgdFileType *ft,
152 GgdDocSetting *setting,
153 GeanyDocument *doc,
154 const TMTag *tag)
155 {
156 CtplEnviron *env;
157 GList *children = NULL;
158 GPtrArray *tag_array = doc->tm_file->tags_array;
159 gboolean returns;
160
161 env = ctpl_environ_new ();
162 ctpl_environ_push_string (env, "cursor", GGD_CURSOR_IDENTIFIER);
163 ctpl_environ_push_string (env, "symbol", tag->name);
164 /* get argument list it it exists */
165 if (tag->arglist) {
166 CtplValue *v;
167
168 v = get_arg_list_from_string (ft, tag->arglist);
169 if (v) {
170 ctpl_environ_push (env, "argument_list", v);
171 ctpl_value_free (v);
172 }
173 }
174 /* get return type -- no matter if the return concept is pointless for that
175 * particular tag, it's up to the rule to use it when it makes sense */
176 returns = ! (tag->var_type != NULL &&
177 /* C-style none return type hack */
178 strcmp ("void", tag->var_type) == 0);
179 ctpl_environ_push_int (env, "returns", returns);
180 /* get direct children tags */
181 children = ggd_tag_find_children (tag_array, tag,
182 FILETYPE_ID (doc->file_type));
183 if (setting->merge_children) {
184 CtplValue *v;
185
186 v = ctpl_value_new_array (CTPL_VTYPE_STRING, 0, NULL);
187 while (children) {
188 TMTag *el = children->data;
189 GList *tmp = children;
190
191 if (el->type & setting->matches) {
192 ctpl_value_array_append_string (v, el->name);
193 }
194
195 children = g_list_next (children);
196 g_list_free_1 (tmp);
197 }
198 ctpl_environ_push (env, "children", v);
199 ctpl_value_free (v);
200 } else {
201 GHashTable *vars;
202
203 vars = g_hash_table_new_full (g_str_hash, g_str_equal,
204 NULL, (GDestroyNotify)ctpl_value_free);
205 while (children) {
206 TMTag *el = children->data;
207 const gchar *type_name = ggd_tag_get_type_name (el);
208 CtplValue *v;
209 GList *tmp = children;
210
211 if (type_name && el->type & setting->matches) {
212 v = g_hash_table_lookup (vars, type_name);
213 if (! v) {
214 v = ctpl_value_new_array (CTPL_VTYPE_STRING, 0, NULL);
215 g_hash_table_insert (vars, (gpointer)type_name, v);
216 }
217 ctpl_value_array_append_string (v, el->name);
218 }
219
220 children = g_list_next (children);
221 g_list_free_1 (tmp);
222 }
223 /* insert children into the environment */
224 g_hash_table_foreach (vars, hash_table_env_push_list_cb, env);
225 g_hash_table_destroy (vars);
226 }
227
228 return env;
229 }
230
231 /* parses the template @tpl with the environment of @tag */
232 static gchar *
233 get_comment (GgdFileType *ft,
234 GgdDocSetting *setting,
235 GeanyDocument *doc,
236 const TMTag *tag,
237 gint *cursor_offset)
238 {
239 gchar *comment = NULL;
240
241 if (setting->template) {
242 GError *err = NULL;
243 CtplEnviron *env;
244
245 env = get_env_for_tag (ft, setting, doc, tag);
246 ctpl_environ_merge (env, ft->user_env, FALSE);
247 if (! ctpl_environ_add_from_string (env, GGD_OPT_environ, &err)) {
248 msgwin_status_add (_("Failed to add global environment, skipping: %s"),
249 err->message);
250 g_clear_error (&err);
251 }
252 comment = parser_parse_to_string (setting->template, env, &err);
253 if (! comment) {
254 msgwin_status_add (_("Failed to build comment: %s"), err->message);
255 g_error_free (err);
256 } else {
257 gchar *cursor_str;
258
259 cursor_str = strstr (comment, GGD_CURSOR_IDENTIFIER);
260 if (cursor_str && cursor_offset) {
261 *cursor_offset = cursor_str - comment;
262 }
263 /* remove the cursor identifier(s) from the final comment */
264 while (cursor_str) {
265 memmove (cursor_str, cursor_str + GGD_CURSOR_IDENTIFIER_LEN,
266 strlen (cursor_str) - GGD_CURSOR_IDENTIFIER_LEN + 1);
267 cursor_str = strstr (cursor_str, GGD_CURSOR_IDENTIFIER);
268 }
269 }
270 }
271
272 return comment;
273 }
274
275 /* Adjusts line where insert a function documentation comment.
276 * This function adjusts start line of a (C) function start to be sure it is
277 * before the return type, even if style places return type in the line that
278 * precede function name.
279 */
280 static gint
281 adjust_function_start_line (ScintillaObject *sci,
282 const gchar *func_name,
283 gint line)
284 {
285 gchar *str;
286 gsize i;
287
288 str = sci_get_line (sci, line);
289 for (i = 0; isspace (str[i]); i++);
290 if (strncmp (&str[i], func_name, strlen (func_name)) == 0) {
291 /* function return type is not in the same line as function name */
292 #if 0
293 /* this solution is more excat but perhaps too much complex for the gain */
294 gint pos;
295 gchar c;
296
297 pos = sci_get_position_from_line (sci, line) - 1;
298 for (; (c = sci_get_char_at (sci, pos)); pos --) {
299 if (c == '\n' || c == '\r')
300 line --;
301 else if (! isspace (c))
302 break;
303 }
304 #else
305 line --;
306 #endif
307 }
308 g_free (str);
309
310 return line;
311 }
312
313 /* adjusts the start line of a tag */
314 static gint
315 adjust_start_line (ScintillaObject *sci,
316 GPtrArray *tags,
317 const TMTag *tag,
318 gint line)
319 {
320 if (tag->type & (tm_tag_function_t | tm_tag_prototype_t |
321 tm_tag_macro_with_arg_t)) {
322 line = adjust_function_start_line (sci, tag->name, line);
323 }
324
325 return line;
326 }
327
328 /* inserts the comment for @tag in @sci according to @setting */
329 static gboolean
330 do_insert_comment (GeanyDocument *doc,
331 const TMTag *tag,
332 GgdFileType *ft,
333 GgdDocSetting *setting)
334 {
335 gboolean success = FALSE;
336 gchar *comment;
337 gint cursor_offset = 0;
338 ScintillaObject *sci = doc->editor->sci;
339 GPtrArray *tag_array = doc->tm_file->tags_array;
340
341 comment = get_comment (ft, setting, doc, tag, &cursor_offset);
342 if (comment) {
343 gint pos = 0;
344
345 switch (setting->position) {
346 case GGD_POS_AFTER:
347 pos = sci_get_line_end_position (sci, tag->line - 1);
348 break;
349
350 case GGD_POS_BEFORE: {
351 gint line;
352
353 line = tag->line - 1;
354 line = adjust_start_line (sci, tag_array, tag, line);
355 pos = sci_get_position_from_line (sci, line);
356 if (GGD_OPT_indent) {
357 while (isspace (sci_get_char_at (sci, pos))) {
358 pos++;
359 }
360 }
361 break;
362 }
363
364 case GGD_POS_CURSOR:
365 pos = sci_get_current_position (sci);
366 break;
367 }
368 editor_insert_text_block (doc->editor, comment, pos, cursor_offset,
369 -1, TRUE);
370 success = TRUE;
371 }
372 g_free (comment);
373
374 return success;
375 }
376
377 /* Gets the #GgdDocSetting that applies for a given tag.
378 * Since a policy may forward documenting to a parent, tag that actually applies
379 * is returned in @real_tag. */
380 static GgdDocSetting *
381 get_setting_from_tag (GgdDocType *doctype,
382 GeanyDocument *doc,
383 const TMTag *tag,
384 const TMTag **real_tag)
385 {
386 GgdDocSetting *setting = NULL;
387 gchar *hierarchy;
388 GPtrArray *tag_array = doc->tm_file->tags_array;
389 GeanyFiletypeID geany_ft = FILETYPE_ID (doc->file_type);
390
391 hierarchy = ggd_tag_resolve_type_hierarchy (tag_array, geany_ft, tag);
392 /*g_debug ("type hierarchy for tag %s is: %s", tag->name, hierarchy);*/
393 *real_tag = tag;
394 if (hierarchy) {
395 gint nth_child;
396
397 setting = ggd_doc_type_resolve_setting (doctype, hierarchy, &nth_child);
398 if (setting) {
399 for (; nth_child > 0; nth_child--) {
400 *real_tag = ggd_tag_find_parent (tag_array, geany_ft, *real_tag);
401 }
402 }
403 g_free (hierarchy);
404 }
405
406 return setting;
407 }
408
409 /*
410 * get_config:
411 * @doc: A #GeanyDocument for which get the configuration
412 * @doc_type: A documentation type identifier
413 * @file_type_: Return location for the corresponding #GgdFileType, or %NULL
414 * @doc_type_: Return location for the corresponding #GgdDocType, or %NULL
415 *
416 * Gets the configuration for a document and a documentation type.
417 *
418 * Returns: %TRUE on success, %FALSE otherwise.
419 */
420 static gboolean
421 get_config (GeanyDocument *doc,
422 const gchar *doc_type,
423 GgdFileType **file_type_,
424 GgdDocType **doc_type_)
425 {
426 gboolean success = FALSE;
427 GgdFileType *ft;
428
429 ft = ggd_file_type_manager_get_file_type (doc->file_type->id);
430 if (ft) {
431 GgdDocType *doctype;
432
433 doctype = ggd_file_type_get_doc (ft, doc_type);
434 if (! doctype) {
435 msgwin_status_add (_("Documentation type \"%s\" does not exist for "
436 "language \"%s\"."),
437 doc_type, doc->file_type->name);
438 } else {
439 if (file_type_) *file_type_ = ft;
440 if (doc_type_) *doc_type_ = doctype;
441 success = TRUE;
442 }
443 }
444
445 return success;
446 }
447
448 /*
449 * insert_multiple_comments:
450 * @doc: A #GeanyDocument in which insert comments
451 * @filetype: The #GgdFileType to use
452 * @doctype: The #GgdDocType to use
453 * @sorted_tag_list: A list of tag to document. This list must be sorted by
454 * tag's line.
455 *
456 * Tries to insert the documentation for all tags listed in @sorted_tag_list,
457 * taking care of settings and duplications.
458 *
459 * Returns: %TRUE on success, %FALSE otherwise.
460 */
461 static gboolean
462 insert_multiple_comments (GeanyDocument *doc,
463 GgdFileType *filetype,
464 GgdDocType *doctype,
465 GList *sorted_tag_list)
466 {
467 gboolean success = FALSE;
468 GList *node;
469 ScintillaObject *sci = doc->editor->sci;
470 GHashTable *tag_done_table; /* keeps the list of documented tags.
471 * Useful since documenting a tag might
472 * actually document another one */
473
474 success = TRUE;
475 tag_done_table = g_hash_table_new (NULL, NULL);
476 sci_start_undo_action (sci);
477 for (node = sorted_tag_list; node; node = node->next) {
478 GgdDocSetting *setting;
479 const TMTag *tag = node->data;
480
481 setting = get_setting_from_tag (doctype, doc, tag, &tag);
482 if (setting && ! g_hash_table_lookup (tag_done_table, tag)) {
483 if (! do_insert_comment (doc, tag, filetype, setting)) {
484 success = FALSE;
485 break;
486 } else {
487 g_hash_table_insert (tag_done_table, (gpointer)tag, (gpointer)tag);
488 }
489 } else if (! setting) {
490 msgwin_status_add (_("No setting applies to symbol \"%s\" of type \"%s\" "
491 "at line %lu."),
492 tag->name, ggd_tag_get_type_name (tag),
493 tag->line);
494 }
495 }
496 sci_end_undo_action (sci);
497 g_hash_table_destroy (tag_done_table);
498
499 return success;
500 }
501
502 /**
503 * ggd_insert_comment:
504 * @doc: The document in which insert the comment
505 * @line: SCI's line for which generate a comment. Usually the current line.
506 * @doc_type: Documentation type identifier
507 *
508 * Tries to insert a comment in a #GeanyDocument.
509 *
510 * <warning>
511 * if tag list is not up-to-date, the result can be surprising
512 * </warning>
513 *
514 * Returns: %TRUE is a comment was added, %FALSE otherwise.
515 */
516 gboolean
517 ggd_insert_comment (GeanyDocument *doc,
518 gint line,
519 const gchar *doc_type)
520 {
521 gboolean success = FALSE;
522 const TMTag *tag = NULL;
523 GPtrArray *tag_array = NULL;
524 GgdFileType *filetype = NULL;
525 GgdDocType *doctype = NULL;
526
527 g_return_val_if_fail (DOC_VALID (doc), FALSE);
528
529 again:
530
531 if (doc->tm_file) {
532 tag_array = doc->tm_file->tags_array;
533 tag = ggd_tag_find_from_line (tag_array, line + 1 /* it is a SCI line */);
534 }
535 if (! tag) {
536 msgwin_status_add (_("No valid tag at line %d."), line);
537 } else {
538 if (get_config (doc, doc_type, &filetype, &doctype)) {
539 GgdDocSetting *setting;
540 GList *tag_list = NULL;
541
542 setting = get_setting_from_tag (doctype, doc, tag, &tag);
543 if (setting && setting->policy == GGD_POLICY_PASS) {
544 /* We want to completely skip this tag, so try previous line instead
545 * FIXME: this implementation is kinda ugly... */
546 line--;
547 goto again;
548 }
549 if (setting && setting->autodoc_children) {
550 tag_list = ggd_tag_find_children_filtered (tag_array, tag,
551 FILETYPE_ID (doc->file_type),
552 setting->matches);
553 }
554 /* we assume that a parent always comes before any children, then simply add
555 * it at the end */
556 tag_list = g_list_append (tag_list, (gpointer)tag);
557 success = insert_multiple_comments (doc, filetype, doctype, tag_list);
558 g_list_free (tag_list);
559 }
560 }
561
562 return success;
563 }
564
565 /**
566 * ggd_insert_all_comments:
567 * @doc: A #GeanyDocument for which insert the comments
568 * @doc_type: Documentation type identifier
569 *
570 * Tries to insert a comment for each symbol of a document.
571 *
572 * Returns: %TRUE on full success, %FALSE otherwise.
573 */
574 gboolean
575 ggd_insert_all_comments (GeanyDocument *doc,
576 const gchar *doc_type)
577 {
578 gboolean success = FALSE;
579 GgdFileType *filetype = NULL;
580 GgdDocType *doctype = NULL;
581
582 g_return_val_if_fail (DOC_VALID (doc), FALSE);
583
584 if (! doc->tm_file) {
585 msgwin_status_add (_("No tags in the document"));
586 } else if (get_config (doc, doc_type, &filetype, &doctype)) {
587 GList *tag_list;
588
589 /* get a sorted list of tags to be sure to insert by the end of the
590 * document, then we don't modify the element's position of tags we'll work
591 * on */
592 tag_list = ggd_tag_sort_by_line_to_list (doc->tm_file->tags_array,
593 GGD_SORT_DESC);
594 success = insert_multiple_comments (doc, filetype, doctype, tag_list);
595 g_list_free (tag_list);
596 }
597
598 return success;
599 }