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, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
21 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
22 * file for a list of people on the GLib Team. See the ChangeLog
23 * files for a list of changes. These files are distributed with
24 * GLib at ftp://ftp.gtk.org/pub/gtk/.
35 #include "gstrfuncs.h"
36 #include "gmessages.h"
39 #undef G_DISABLE_DEPRECATED
41 #include "gcompletion.h"
45 * @title: Automatic String Completion
46 * @short_description: support for automatic completion using a group
49 * #GCompletion provides support for automatic completion of a string
50 * using any group of target strings. It is typically used for file
51 * name completion as is common in many UNIX shells.
53 * A #GCompletion is created using g_completion_new(). Target items are
54 * added and removed with g_completion_add_items(),
55 * g_completion_remove_items() and g_completion_clear_items(). A
56 * completion attempt is requested with g_completion_complete() or
57 * g_completion_complete_utf8(). When no longer needed, the
58 * #GCompletion is freed with g_completion_free().
60 * Items in the completion can be simple strings (e.g. filenames), or
61 * pointers to arbitrary data structures. If data structures are used
62 * you must provide a #GCompletionFunc in g_completion_new(), which
63 * retrieves the item's string from the data structure. You can change
64 * the way in which strings are compared by setting a different
65 * #GCompletionStrncmpFunc in g_completion_set_compare().
67 * GCompletion has been marked as deprecated, since this API is rarely
68 * used and not very actively maintained.
73 * @items: list of target items (strings or data structures).
74 * @func: function which is called to get the string associated with a
75 * target item. It is %NULL if the target items are strings.
76 * @prefix: the last prefix passed to g_completion_complete() or
77 * g_completion_complete_utf8().
78 * @cache: the list of items which begin with @prefix.
79 * @strncmp_func: The function to use when comparing strings. Use
80 * g_completion_set_compare() to modify this function.
82 * The data structure used for automatic completion.
87 * @Param1: the completion item.
88 * @Returns: the string corresponding to the item.
90 * Specifies the type of the function passed to g_completion_new(). It
91 * should return the string corresponding to the given target item.
92 * This is used when you use data structures as #GCompletion items.
96 * GCompletionStrncmpFunc:
97 * @s1: string to compare with @s2.
98 * @s2: string to compare with @s1.
99 * @n: maximal number of bytes to compare.
100 * @Returns: an integer less than, equal to, or greater than zero if
101 * the first @n bytes of @s1 is found, respectively, to be
102 * less than, to match, or to be greater than the first @n
105 * Specifies the type of the function passed to
106 * g_completion_set_compare(). This is used when you use strings as
107 * #GCompletion items.
110 static void completion_check_cache (GCompletion* cmp,
115 * @func: the function to be called to return the string representing
116 * an item in the #GCompletion, or %NULL if strings are going to
117 * be used as the #GCompletion items.
118 * @Returns: the new #GCompletion.
120 * Creates a new #GCompletion.
123 g_completion_new (GCompletionFunc func)
127 gcomp = g_new (GCompletion, 1);
130 gcomp->prefix = NULL;
132 gcomp->strncmp_func = strncmp;
138 * g_completion_add_items:
139 * @cmp: the #GCompletion.
140 * @items: the list of items to add.
142 * Adds items to the #GCompletion.
144 * Deprecated: 2.26: Rarely used API
147 g_completion_add_items (GCompletion* cmp,
152 g_return_if_fail (cmp != NULL);
154 /* optimize adding to cache? */
157 g_list_free (cmp->cache);
163 g_free (cmp->prefix);
170 cmp->items = g_list_prepend (cmp->items, it->data);
176 * g_completion_remove_items:
177 * @cmp: the #GCompletion.
178 * @items: the items to remove.
180 * Removes items from a #GCompletion.
182 * Deprecated: 2.26: Rarely used API
185 g_completion_remove_items (GCompletion* cmp,
190 g_return_if_fail (cmp != NULL);
193 while (cmp->items && it)
195 cmp->items = g_list_remove (cmp->items, it->data);
200 while (cmp->cache && it)
202 cmp->cache = g_list_remove(cmp->cache, it->data);
208 * g_completion_clear_items:
209 * @cmp: the #GCompletion.
211 * Removes all items from the #GCompletion.
213 * Deprecated: 2.26: Rarely used API
216 g_completion_clear_items (GCompletion* cmp)
218 g_return_if_fail (cmp != NULL);
220 g_list_free (cmp->items);
222 g_list_free (cmp->cache);
224 g_free (cmp->prefix);
229 completion_check_cache (GCompletion* cmp,
232 register GList* list;
247 len = strlen(cmp->prefix);
249 s = cmp->func ? cmp->func (list->data) : (gchar*) list->data;
251 plen = strlen (postfix);
256 s = cmp->func ? cmp->func (list->data) : (gchar*) list->data;
258 for (i = 0; i < plen; ++i)
260 if (postfix[i] != s[i])
267 *new_prefix = g_new0 (gchar, len + plen + 1);
268 strncpy (*new_prefix, cmp->prefix, len);
269 strncpy (*new_prefix + len, postfix, plen);
273 * g_completion_complete_utf8:
274 * @cmp: the #GCompletion
275 * @prefix: the prefix string, typically used by the user, which is compared
276 * with each of the items
277 * @new_prefix: if non-%NULL, returns the longest prefix which is common to all
278 * items that matched @prefix, or %NULL if no items matched @prefix.
279 * This string should be freed when no longer needed.
281 * Attempts to complete the string @prefix using the #GCompletion target items.
282 * In contrast to g_completion_complete(), this function returns the largest common
283 * prefix that is a valid UTF-8 string, omitting a possible common partial
286 * You should use this function instead of g_completion_complete() if your
287 * items are UTF-8 strings.
289 * Return value: the list of items whose strings begin with @prefix. This should
294 * Deprecated: 2.26: Rarely used API
297 g_completion_complete_utf8 (GCompletion *cmp,
304 list = g_completion_complete (cmp, prefix, new_prefix);
306 if (new_prefix && *new_prefix)
308 p = *new_prefix + strlen (*new_prefix);
309 q = g_utf8_find_prev_char (*new_prefix, p);
311 switch (g_utf8_get_char_validated (q, p - q))
326 * g_completion_complete:
327 * @cmp: the #GCompletion.
328 * @prefix: the prefix string, typically typed by the user, which is
329 * compared with each of the items.
330 * @new_prefix: if non-%NULL, returns the longest prefix which is
331 * common to all items that matched @prefix, or %NULL if
332 * no items matched @prefix. This string should be freed
333 * when no longer needed.
334 * @Returns: the list of items whose strings begin with @prefix. This
335 * should not be changed.
337 * Attempts to complete the string @prefix using the #GCompletion
340 * Deprecated: 2.26: Rarely used API
343 g_completion_complete (GCompletion* cmp,
348 gboolean done = FALSE;
351 g_return_val_if_fail (cmp != NULL, NULL);
352 g_return_val_if_fail (prefix != NULL, NULL);
354 len = strlen (prefix);
355 if (cmp->prefix && cmp->cache)
357 plen = strlen (cmp->prefix);
358 if (plen <= len && ! cmp->strncmp_func (prefix, cmp->prefix, plen))
364 GList *next = list->next;
366 if (cmp->strncmp_func (prefix,
367 cmp->func ? cmp->func (list->data) : (gchar*) list->data,
369 cmp->cache = g_list_delete_link (cmp->cache, list);
380 g_list_free (cmp->cache);
383 while (*prefix && list)
385 if (!cmp->strncmp_func (prefix,
386 cmp->func ? cmp->func (list->data) : (gchar*) list->data,
388 cmp->cache = g_list_prepend (cmp->cache, list->data);
394 g_free (cmp->prefix);
398 cmp->prefix = g_strdup (prefix);
399 completion_check_cache (cmp, new_prefix);
401 return *prefix ? cmp->cache : cmp->items;
406 * @cmp: the #GCompletion.
408 * Frees all memory used by the #GCompletion.
410 * Deprecated: 2.26: Rarely used API
413 g_completion_free (GCompletion* cmp)
415 g_return_if_fail (cmp != NULL);
417 g_completion_clear_items (cmp);
422 * g_completion_set_compare:
423 * @cmp: a #GCompletion.
424 * @strncmp_func: the string comparison function.
426 * Sets the function to use for string comparisons. The default string
427 * comparison function is strncmp().
429 * Deprecated: 2.26: Rarely used API
432 g_completion_set_compare(GCompletion *cmp,
433 GCompletionStrncmpFunc strncmp_func)
435 cmp->strncmp_func = strncmp_func;
438 #ifdef TEST_COMPLETION
455 g_warning ("Usage: %s filename prefix1 [prefix2 ...]\n", argv[0]);
459 file = fopen (argv[1], "r");
462 g_warning ("Cannot open %s\n", argv[1]);
466 cmp = g_completion_new (NULL);
467 list = g_list_alloc ();
468 while (fgets (buf, 1024, file))
470 list->data = g_strdup (buf);
471 g_completion_add_items (cmp, list);
475 for (i = 2; i < argc; ++i)
477 printf ("COMPLETING: %s\n", argv[i]);
478 result = g_completion_complete (cmp, argv[i], &longp);
479 g_list_foreach (result, (GFunc) printf, NULL);
480 printf ("LONG MATCH: %s\n", longp);
485 g_list_foreach (cmp->items, (GFunc) g_free, NULL);
486 g_completion_free (cmp);