1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
20 * file for a list of people on the GLib Team. See the ChangeLog
21 * files for a list of changes. These files are distributed with
22 * GLib at ftp://ftp.gtk.org/pub/gtk/.
31 /* we know we are deprecated here, no need for warnings */
32 #define GLIB_DISABLE_DEPRECATION_WARNINGS
34 #include "gcompletion.h"
36 #include <glib/gstrfuncs.h>
37 #include <glib/gmessages.h>
38 #include <glib/gunicode.h>
44 * @title: Automatic String Completion
45 * @short_description: support for automatic completion using a group
48 * #GCompletion provides support for automatic completion of a string
49 * using any group of target strings. It is typically used for file
50 * name completion as is common in many UNIX shells.
52 * A #GCompletion is created using g_completion_new(). Target items are
53 * added and removed with g_completion_add_items(),
54 * g_completion_remove_items() and g_completion_clear_items(). A
55 * completion attempt is requested with g_completion_complete() or
56 * g_completion_complete_utf8(). When no longer needed, the
57 * #GCompletion is freed with g_completion_free().
59 * Items in the completion can be simple strings (e.g. filenames), or
60 * pointers to arbitrary data structures. If data structures are used
61 * you must provide a #GCompletionFunc in g_completion_new(), which
62 * retrieves the item's string from the data structure. You can change
63 * the way in which strings are compared by setting a different
64 * #GCompletionStrncmpFunc in g_completion_set_compare().
66 * GCompletion has been marked as deprecated, since this API is rarely
67 * used and not very actively maintained.
72 * @items: list of target items (strings or data structures).
73 * @func: function which is called to get the string associated with a
74 * target item. It is %NULL if the target items are strings.
75 * @prefix: the last prefix passed to g_completion_complete() or
76 * g_completion_complete_utf8().
77 * @cache: the list of items which begin with @prefix.
78 * @strncmp_func: The function to use when comparing strings. Use
79 * g_completion_set_compare() to modify this function.
81 * The data structure used for automatic completion.
86 * @Param1: the completion item.
88 * Specifies the type of the function passed to g_completion_new(). It
89 * should return the string corresponding to the given target item.
90 * This is used when you use data structures as #GCompletion items.
92 * Returns: the string corresponding to the item.
96 * GCompletionStrncmpFunc:
97 * @s1: string to compare with @s2.
98 * @s2: string to compare with @s1.
99 * @n: maximal number of bytes to compare.
101 * Specifies the type of the function passed to
102 * g_completion_set_compare(). This is used when you use strings as
103 * #GCompletion items.
105 * Returns: an integer less than, equal to, or greater than zero if
106 * the first @n bytes of @s1 is found, respectively, to be
107 * less than, to match, or to be greater than the first @n
111 static void completion_check_cache (GCompletion* cmp,
116 * @func: the function to be called to return the string representing
117 * an item in the #GCompletion, or %NULL if strings are going to
118 * be used as the #GCompletion items.
120 * Creates a new #GCompletion.
122 * Returns: the new #GCompletion.
125 g_completion_new (GCompletionFunc func)
129 gcomp = g_new (GCompletion, 1);
132 gcomp->prefix = NULL;
134 gcomp->strncmp_func = strncmp;
140 * g_completion_add_items:
141 * @cmp: the #GCompletion.
142 * @items: (transfer none): the list of items to add.
144 * Adds items to the #GCompletion.
146 * Deprecated: 2.26: Rarely used API
149 g_completion_add_items (GCompletion* cmp,
154 g_return_if_fail (cmp != NULL);
156 /* optimize adding to cache? */
159 g_list_free (cmp->cache);
165 g_free (cmp->prefix);
172 cmp->items = g_list_prepend (cmp->items, it->data);
178 * g_completion_remove_items:
179 * @cmp: the #GCompletion.
180 * @items: (transfer none): the items to remove.
182 * Removes items from a #GCompletion. The items are not freed, so if the memory
183 * was dynamically allocated, free @items with g_list_free_full() after calling
186 * Deprecated: 2.26: Rarely used API
189 g_completion_remove_items (GCompletion* cmp,
194 g_return_if_fail (cmp != NULL);
197 while (cmp->items && it)
199 cmp->items = g_list_remove (cmp->items, it->data);
204 while (cmp->cache && it)
206 cmp->cache = g_list_remove(cmp->cache, it->data);
212 * g_completion_clear_items:
213 * @cmp: the #GCompletion.
215 * Removes all items from the #GCompletion. The items are not freed, so if the
216 * memory was dynamically allocated, it should be freed after calling this
219 * Deprecated: 2.26: Rarely used API
222 g_completion_clear_items (GCompletion* cmp)
224 g_return_if_fail (cmp != NULL);
226 g_list_free (cmp->items);
228 g_list_free (cmp->cache);
230 g_free (cmp->prefix);
235 completion_check_cache (GCompletion* cmp,
253 len = strlen(cmp->prefix);
255 s = cmp->func ? cmp->func (list->data) : (gchar*) list->data;
257 plen = strlen (postfix);
262 s = cmp->func ? cmp->func (list->data) : (gchar*) list->data;
264 for (i = 0; i < plen; ++i)
266 if (postfix[i] != s[i])
273 *new_prefix = g_new0 (gchar, len + plen + 1);
274 strncpy (*new_prefix, cmp->prefix, len);
275 strncpy (*new_prefix + len, postfix, plen);
279 * g_completion_complete_utf8:
280 * @cmp: the #GCompletion
281 * @prefix: the prefix string, typically used by the user, which is compared
282 * with each of the items
283 * @new_prefix: if non-%NULL, returns the longest prefix which is common to all
284 * items that matched @prefix, or %NULL if no items matched @prefix.
285 * This string should be freed when no longer needed.
287 * Attempts to complete the string @prefix using the #GCompletion target items.
288 * In contrast to g_completion_complete(), this function returns the largest common
289 * prefix that is a valid UTF-8 string, omitting a possible common partial
292 * You should use this function instead of g_completion_complete() if your
293 * items are UTF-8 strings.
295 * Returns: (element-type utf8) (transfer none): the list of items whose strings begin with @prefix. This should
300 * Deprecated: 2.26: Rarely used API
303 g_completion_complete_utf8 (GCompletion *cmp,
310 list = g_completion_complete (cmp, prefix, new_prefix);
312 if (new_prefix && *new_prefix)
314 p = *new_prefix + strlen (*new_prefix);
315 q = g_utf8_find_prev_char (*new_prefix, p);
317 switch (g_utf8_get_char_validated (q, p - q))
332 * g_completion_complete:
333 * @cmp: the #GCompletion.
334 * @prefix: the prefix string, typically typed by the user, which is
335 * compared with each of the items.
336 * @new_prefix: if non-%NULL, returns the longest prefix which is
337 * common to all items that matched @prefix, or %NULL if
338 * no items matched @prefix. This string should be freed
339 * when no longer needed.
341 * Attempts to complete the string @prefix using the #GCompletion
344 * Returns: (transfer none): the list of items whose strings begin with
345 * @prefix. This should not be changed.
347 * Deprecated: 2.26: Rarely used API
350 g_completion_complete (GCompletion* cmp,
355 gboolean done = FALSE;
358 g_return_val_if_fail (cmp != NULL, NULL);
359 g_return_val_if_fail (prefix != NULL, NULL);
361 len = strlen (prefix);
362 if (cmp->prefix && cmp->cache)
364 plen = strlen (cmp->prefix);
365 if (plen <= len && ! cmp->strncmp_func (prefix, cmp->prefix, plen))
371 GList *next = list->next;
373 if (cmp->strncmp_func (prefix,
374 cmp->func ? cmp->func (list->data) : (gchar*) list->data,
376 cmp->cache = g_list_delete_link (cmp->cache, list);
387 g_list_free (cmp->cache);
390 while (*prefix && list)
392 if (!cmp->strncmp_func (prefix,
393 cmp->func ? cmp->func (list->data) : (gchar*) list->data,
395 cmp->cache = g_list_prepend (cmp->cache, list->data);
401 g_free (cmp->prefix);
405 cmp->prefix = g_strdup (prefix);
406 completion_check_cache (cmp, new_prefix);
408 return *prefix ? cmp->cache : cmp->items;
413 * @cmp: the #GCompletion.
415 * Frees all memory used by the #GCompletion. The items are not freed, so if
416 * the memory was dynamically allocated, it should be freed after calling this
419 * Deprecated: 2.26: Rarely used API
422 g_completion_free (GCompletion* cmp)
424 g_return_if_fail (cmp != NULL);
426 g_completion_clear_items (cmp);
431 * g_completion_set_compare:
432 * @cmp: a #GCompletion.
433 * @strncmp_func: the string comparison function.
435 * Sets the function to use for string comparisons. The default string
436 * comparison function is strncmp().
438 * Deprecated: 2.26: Rarely used API
441 g_completion_set_compare(GCompletion *cmp,
442 GCompletionStrncmpFunc strncmp_func)
444 cmp->strncmp_func = strncmp_func;
447 #ifdef TEST_COMPLETION
464 g_warning ("Usage: %s filename prefix1 [prefix2 ...]\n", argv[0]);
468 file = fopen (argv[1], "r");
471 g_warning ("Cannot open %s\n", argv[1]);
475 cmp = g_completion_new (NULL);
476 list = g_list_alloc ();
477 while (fgets (buf, 1024, file))
479 list->data = g_strdup (buf);
480 g_completion_add_items (cmp, list);
484 for (i = 2; i < argc; ++i)
486 printf ("COMPLETING: %s\n", argv[i]);
487 result = g_completion_complete (cmp, argv[i], &longp);
488 g_list_foreach (result, (GFunc) printf, NULL);
489 printf ("LONG MATCH: %s\n", longp);
494 g_list_foreach (cmp->items, (GFunc) g_free, NULL);
495 g_completion_free (cmp);