Debian Codegraph @

geanygendoc/src/ggd-tag-utils.c

raw
1 /*
2 *
3 * GeanyGenDoc, a Geany plugin to ease generation of source code documentation
4 * Copyright (C) 2010-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
22 #ifdef HAVE_CONFIG_H
23 # include "config.h" /* for the gettext domain */
24 #endif
25
26 #include "ggd-tag-utils.h"
27
28 #include <geanyplugin.h>
29 #include <glib.h>
30
31 #include "ggd-utils.h"
32 #include "ggd-plugin.h" /* to access Geany data/funcs */
33
34
35 /*
36 * tag_cmp_by_line:
37 * @a: A #TMTag
38 * @b: Another #TMTag
39 * @data: A pointer that, converted with GPOINTER_TO_INT(), becomes an integer
40 * strictly positive for an ascending sort or strictly negative for a
41 * descending sort. The constants %GGD_SORT_ASC and %GGD_SORT_DESC can be
42 * used here.
43 *
44 * Compares two #TMTag<!-- -->s by their lines.
45 *
46 * Returns: A positive integer if line(a) > line(b), a negative integer if
47 * line(a) < line(b) and a nul integer (0) if line(a) == line(b).
48 */
49 static gint
50 tag_cmp_by_line (gconstpointer a,
51 gconstpointer b,
52 gpointer data)
53 {
54 const TMTag *t1 = a;
55 const TMTag *t2 = b;
56 gint direction = GPOINTER_TO_INT (data);
57 gint rv;
58
59 if (t1->line > t2->line) {
60 rv = +direction;
61 } else if (t1->line < t2->line) {
62 rv = -direction;
63 } else {
64 rv = 0;
65 }
66
67 return rv;
68 }
69
70 /* A wrapper for tag_cmp_by_line() that works with g_ptr_array_sort() */
71 static gint
72 tag_cmp_by_line_ptr_array (gconstpointer a,
73 gconstpointer b,
74 gpointer data)
75 {
76 return tag_cmp_by_line (*((const TMTag**)a), *((const TMTag**)b), data);
77 }
78
79 /**
80 * ggd_tag_sort_by_line:
81 * @tags: A #GPtrArray of #TMTag<!-- -->s
82 * @direction: Sort direction: %GGD_SORT_ASC for an ascending sort or
83 * %GGD_SORT_DESC for a descending sort.
84 *
85 * Sorts a #GPtrArray of #TMTag<!-- -->s by the tags' line position. The sort
86 * direction depend on @direction.
87 */
88 void
89 ggd_tag_sort_by_line (GPtrArray *tags,
90 gint direction)
91 {
92 g_return_if_fail (tags != NULL);
93 g_return_if_fail (direction != 0);
94
95 g_ptr_array_sort_with_data (tags, tag_cmp_by_line_ptr_array,
96 GINT_TO_POINTER (direction));
97 }
98
99 /**
100 * ggd_tag_sort_by_line_to_list:
101 * @tags: A #GPtrArray of #TMTag<!-- -->s
102 * @direction: Sort direction: %GGD_SORT_ASC for an ascending sort or
103 * %GGD_SORT_DESC for a descending sort.
104 *
105 * Creates a sorted list of tags from a #GPtrArray of #TMTag<!-- -->s. The list
106 * is sorted by the tags' line position. The sort direction depend on
107 * @direction.
108 *
109 * <note><para>The tags are not copied; you must then not free the array' items
110 * if you still want to use the returned list.</para></note>
111 *
112 * Returns: A newly created list of tags that should be freed with
113 * g_list_free().
114 */
115 GList *
116 ggd_tag_sort_by_line_to_list (const GPtrArray *tags,
117 gint direction)
118 {
119 GList *children = NULL;
120 guint i = 0;
121 TMTag *el = NULL;
122
123 g_return_val_if_fail (tags != NULL, NULL);
124 g_return_val_if_fail (direction != 0, NULL);
125
126 GGD_PTR_ARRAY_FOR (tags, i, el) {
127 children = g_list_insert_sorted_with_data (children, el,
128 tag_cmp_by_line,
129 GINT_TO_POINTER (direction));
130 }
131
132 return children;
133 }
134
135 /**
136 * ggd_tag_find_from_line:
137 * @tags: A #GPtrArray of TMTag<!-- -->s
138 * @line: Line for which find the tag
139 *
140 * Finds the tag that applies for a given line.
141 * It actually gets the first tag that precede or is at the exact position of
142 * the line.
143 *
144 * Returns: A #TMTag, or %NULL if none found.
145 */
146 TMTag *
147 ggd_tag_find_from_line (const GPtrArray *tags,
148 gulong line)
149 {
150 TMTag *tag = NULL;
151 TMTag *el = NULL;
152 guint i = 0;
153
154 g_return_val_if_fail (tags != NULL, NULL);
155
156 GGD_PTR_ARRAY_FOR (tags, i, el) {
157 if (el->line <= line &&
158 (! tag || el->line > tag->line)) {
159 tag = el;
160 }
161 }
162
163 return tag;
164 }
165
166 /**
167 * ggd_tag_find_at_current_pos:
168 * @doc: A #GeanyDocument
169 *
170 * Finds the tag that applies for the current position in a #GeanyDocument.
171 * See ggd_tag_find_from_line().
172 *
173 * Returns: A #TMTag, or %NULL if none found.
174 */
175 TMTag *
176 ggd_tag_find_at_current_pos (GeanyDocument *doc)
177 {
178 TMTag *tag = NULL;
179
180 if (doc && doc->tm_file) {
181 tag = ggd_tag_find_from_line (doc->tm_file->tags_array,
182 sci_get_current_line (doc->editor->sci) + 1);
183 }
184
185 return tag;
186 }
187
188 /**
189 * ggd_tag_find_parent:
190 * @tags: A #GPtrArray of #TMTag<!-- -->s containing @tag
191 * @geany_ft: The Geany's file type identifier for which tags were generated
192 * @child: A #TMTag, child of the tag to find
193 *
194 * Finds the parent tag of a #TMTag.
195 *
196 * Returns: A #TMTag, or %NULL if @child have no parent.
197 */
198 TMTag *
199 ggd_tag_find_parent (const GPtrArray *tags,
200 GeanyFiletypeID geany_ft,
201 const TMTag *child)
202 {
203 TMTag *tag = NULL;
204
205 g_return_val_if_fail (tags != NULL, NULL);
206 g_return_val_if_fail (child != NULL, NULL);
207
208 if (! child->scope) {
209 /* tag has no parent, we're done */
210 } else {
211 gchar *parent_scope = NULL;
212 const gchar *parent_name;
213 const gchar *tmp;
214 guint i = 0;
215 TMTag *el = NULL;
216 const gchar *separator;
217 gsize separator_len;
218
219 /* scope is of the form a<sep>b<sep>c */
220 parent_name = child->scope;
221 separator = symbols_get_context_separator (geany_ft);
222 separator_len = strlen (separator);
223 while ((tmp = strstr (parent_name, separator)) != NULL) {
224 parent_name = &tmp[separator_len];
225 }
226 /* if parent have scope */
227 if (parent_name != child->scope) {
228 /* the parent scope is the "dirname" of the child's scope */
229 parent_scope = g_strndup (child->scope,
230 parent_name - child->scope -
231 separator_len);
232 }
233 /*g_debug ("%s: parent_name = %s", G_STRFUNC, parent_name);
234 g_debug ("%s: parent_scope = %s", G_STRFUNC, parent_scope);*/
235 GGD_PTR_ARRAY_FOR (tags, i, el) {
236 if ((utils_str_equal (el->name, parent_name) &&
237 utils_str_equal (el->scope, parent_scope) &&
238 el->line <= child->line)) {
239 tag = el;
240 }
241 }
242 g_free (parent_scope);
243 }
244
245 return tag;
246 }
247
248 static const struct {
249 const TMTagType type;
250 const gchar *const name;
251 } GGD_tag_types[] = {
252 { tm_tag_class_t, "class" },
253 { tm_tag_enum_t, "enum" },
254 { tm_tag_enumerator_t, "enumval" },
255 { tm_tag_externvar_t, "extern" },
256 { tm_tag_field_t, "field" },
257 { tm_tag_function_t, "function" },
258 { tm_tag_interface_t, "interface" },
259 { tm_tag_include_t, "include" },
260 { tm_tag_local_var_t, "local" },
261 { tm_tag_macro_t, "define" },
262 { tm_tag_macro_with_arg_t, "macro" },
263 { tm_tag_member_t, "member" },
264 { tm_tag_method_t, "method" },
265 { tm_tag_namespace_t, "namespace" },
266 { tm_tag_other_t, "other" },
267 { tm_tag_package_t, "package" },
268 { tm_tag_prototype_t, "prototype" },
269 { tm_tag_struct_t, "struct" },
270 { tm_tag_typedef_t, "typedef" },
271 { tm_tag_union_t, "union" },
272 { tm_tag_variable_t, "variable" }
273 };
274
275 /**
276 * ggd_tag_type_get_name:
277 * @type: A #TMTagType
278 *
279 * Tries to convert a #TMTagType to a string.
280 *
281 * Returns: A string representing @type that should not be modified or freed,
282 * or %NULL on failure.
283 */
284 const gchar *
285 ggd_tag_type_get_name (TMTagType type)
286 {
287 guint i;
288
289 for (i = 0; i < G_N_ELEMENTS (GGD_tag_types); i++) {
290 if (GGD_tag_types[i].type == type) {
291 return GGD_tag_types[i].name;
292 }
293 }
294
295 return NULL;
296 }
297
298 /**
299 * ggd_tag_type_from_name:
300 * @name: A string representing a #TMTag type
301 *
302 * Tries to convert string to tag type.
303 *
304 * Returns: The #TMTagType that @name stands for, or 0 if @name dosen't stand
305 * for any type.
306 */
307 TMTagType
308 ggd_tag_type_from_name (const gchar *name)
309 {
310 guint i;
311
312 g_return_val_if_fail (name != NULL, 0);
313
314 for (i = 0; i < G_N_ELEMENTS (GGD_tag_types); i++) {
315 if (utils_str_equal (GGD_tag_types[i].name, name)) {
316 return GGD_tag_types[i].type;
317 }
318 }
319
320 return 0;
321 }
322
323 /**
324 * ggd_tag_get_type_name:
325 * @tag: A #TMTag
326 *
327 * Gets the name of a #TMTag's type. See ggd_tag_type_get_name().
328 *
329 * Returns: The #TMTag's type name or %NULL on failure.
330 */
331 const gchar *
332 ggd_tag_get_type_name (const TMTag *tag)
333 {
334 g_return_val_if_fail (tag, NULL);
335
336 return ggd_tag_type_get_name (tag->type);
337 }
338
339 /**
340 * ggd_tag_resolve_type_hierarchy:
341 * @tags: The tag array that contains @tag
342 * @geany_ft: The Geany's file type identifier for which tags were generated
343 * @tag: A #TMTag to which get the type hierarchy
344 *
345 * Gets the type hierarchy of a tag as a string, each element separated by a
346 * dot.
347 *
348 * Returns: the tag's type hierarchy or %NULL if invalid.
349 */
350 /*
351 * FIXME: perhaps we should use array of type's ID rather than a string?
352 * FIXME: perhaps drop recursion
353 */
354 gchar *
355 ggd_tag_resolve_type_hierarchy (const GPtrArray *tags,
356 GeanyFiletypeID geany_ft,
357 const TMTag *tag)
358 {
359 TMTag *parent_tag;
360 gchar *scope = NULL;
361
362 g_return_val_if_fail (tags != NULL, NULL);
363 g_return_val_if_fail (tag != NULL, NULL);
364
365 parent_tag = ggd_tag_find_parent (tags, geany_ft, tag);
366 scope = g_strdup (ggd_tag_get_type_name (tag));
367 if (parent_tag) {
368 gchar *parent_scope;
369
370 parent_scope = ggd_tag_resolve_type_hierarchy (tags, geany_ft, parent_tag);
371 if (! parent_scope) {
372 /*g_debug ("no parent scope");*/
373 } else {
374 gchar *tmp;
375
376 tmp = g_strconcat (parent_scope, ".", scope, NULL);
377 g_free (scope);
378 scope = tmp;
379 g_free (parent_scope);
380 }
381 }
382
383 return scope;
384 }
385
386 /**
387 * ggd_tag_find_from_name:
388 * @tags: A #GPtrArray of tags
389 * @name: the name of the tag to search for
390 *
391 * Gets the tag named @name in @tags
392 *
393 * Returns: The #TMTag named @name, or %NULL if none matches
394 */
395 TMTag *
396 ggd_tag_find_from_name (const GPtrArray *tags,
397 const gchar *name)
398 {
399 TMTag *tag = NULL;
400 guint i = 0;
401 TMTag *el = NULL;
402
403 g_return_val_if_fail (tags != NULL, NULL);
404 g_return_val_if_fail (name != NULL, NULL);
405
406 GGD_PTR_ARRAY_FOR (tags, i, el) {
407 if (utils_str_equal (el->name, name)) {
408 tag = el;
409 break;
410 }
411 }
412
413 return tag;
414 }
415
416 /**
417 * ggd_tag_find_children:
418 * @tags: Array of tags that contains @parent
419 * @parent: Tag for which get children
420 * @geany_ft: The Geany's file type identifier for which tags were generated
421 * @filter: A logical OR of the TMTagType<!-- -->s to match
422 *
423 * Finds children tags of a #TMTag that matches @matches.
424 * <note><para>The returned list of children is sorted in the order they appears
425 * in the source file (by their lines positions)</para></note>
426 *
427 * Returns: The list of children found for @parent
428 */
429 GList *
430 ggd_tag_find_children_filtered (const GPtrArray *tags,
431 const TMTag *parent,
432 GeanyFiletypeID geany_ft,
433 TMTagType filter)
434 {
435 GList *children = NULL;
436 guint i = 0;
437 TMTag *el = NULL;
438
439 g_return_val_if_fail (tags != NULL, NULL);
440 g_return_val_if_fail (parent != NULL, NULL);
441
442 GGD_PTR_ARRAY_FOR (tags, i, el) {
443 if (el->type & filter &&
444 ggd_tag_find_parent (tags, geany_ft, el) == parent) {
445 children = g_list_insert_sorted_with_data (children, el,
446 tag_cmp_by_line,
447 GINT_TO_POINTER (GGD_SORT_ASC));
448 }
449 }
450
451 return children;
452 }
453
454 /**
455 * ggd_tag_find_children:
456 * @tags: Array of tags that contains @parent
457 * @parent: Tag for which get children
458 * @geany_ft: The Geany's file type identifier for which tags were generated
459 *
460 * Finds children tags of a #TMTag.
461 * <note><para>The returned list of children is sorted in the order they appears
462 * in the source file (by their lines positions)</para></note>
463 *
464 * Returns: The list of children found for @parent
465 */
466 GList *
467 ggd_tag_find_children (const GPtrArray *tags,
468 const TMTag *parent,
469 GeanyFiletypeID geany_ft)
470 {
471 return ggd_tag_find_children_filtered (tags, parent, geany_ft, tm_tag_max_t);
472 }