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"
46 * @title: Automatic String Completion
47 * @short_description: support for automatic completion using a group
50 * #GCompletion provides support for automatic completion of a string
51 * using any group of target strings. It is typically used for file
52 * name completion as is common in many UNIX shells.
54 * A #GCompletion is created using g_completion_new(). Target items are
55 * added and removed with g_completion_add_items(),
56 * g_completion_remove_items() and g_completion_clear_items(). A
57 * completion attempt is requested with g_completion_complete() or
58 * g_completion_complete_utf8(). When no longer needed, the
59 * #GCompletion is freed with g_completion_free().
61 * Items in the completion can be simple strings (e.g. filenames), or
62 * pointers to arbitrary data structures. If data structures are used
63 * you must provide a #GCompletionFunc in g_completion_new(), which
64 * retrieves the item's string from the data structure. You can change
65 * the way in which strings are compared by setting a different
66 * #GCompletionStrncmpFunc in g_completion_set_compare().
68 * GCompletion has been marked as deprecated, since this API is rarely
69 * used and not very actively maintained.
74 * @items: list of target items (strings or data structures).
75 * @func: function which is called to get the string associated with a
76 * target item. It is %NULL if the target items are strings.
77 * @prefix: the last prefix passed to g_completion_complete() or
78 * g_completion_complete_utf8().
79 * @cache: the list of items which begin with @prefix.
80 * @strncmp_func: The function to use when comparing strings. Use
81 * g_completion_set_compare() to modify this function.
83 * The data structure used for automatic completion.
88 * @Param1: the completion item.
89 * @Returns: the string corresponding to the item.
91 * Specifies the type of the function passed to g_completion_new(). It
92 * should return the string corresponding to the given target item.
93 * This is used when you use data structures as #GCompletion items.
97 * GCompletionStrncmpFunc:
98 * @s1: string to compare with @s2.
99 * @s2: string to compare with @s1.
100 * @n: maximal number of bytes to compare.
101 * @Returns: an integer less than, equal to, or greater than zero if
102 * the first @n bytes of @s1 is found, respectively, to be
103 * less than, to match, or to be greater than the first @n
106 * Specifies the type of the function passed to
107 * g_completion_set_compare(). This is used when you use strings as
108 * #GCompletion items.
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.
119 * @Returns: the new #GCompletion.
121 * Creates a new #GCompletion.
124 g_completion_new (GCompletionFunc func)
128 gcomp = g_new (GCompletion, 1);
131 gcomp->prefix = NULL;
133 gcomp->strncmp_func = strncmp;
139 * g_completion_add_items:
140 * @cmp: the #GCompletion.
141 * @items: the list of items to add.
143 * Adds items to the #GCompletion.
145 * Deprecated: 2.26: Rarely used API
148 g_completion_add_items (GCompletion* cmp,
153 g_return_if_fail (cmp != NULL);
155 /* optimize adding to cache? */
158 g_list_free (cmp->cache);
164 g_free (cmp->prefix);
171 cmp->items = g_list_prepend (cmp->items, it->data);
177 * g_completion_remove_items:
178 * @cmp: the #GCompletion.
179 * @items: the items to remove.
181 * Removes items from a #GCompletion.
183 * Deprecated: 2.26: Rarely used API
186 g_completion_remove_items (GCompletion* cmp,
191 g_return_if_fail (cmp != NULL);
194 while (cmp->items && it)
196 cmp->items = g_list_remove (cmp->items, it->data);
201 while (cmp->cache && it)
203 cmp->cache = g_list_remove(cmp->cache, it->data);
209 * g_completion_clear_items:
210 * @cmp: the #GCompletion.
212 * Removes all items from the #GCompletion.
214 * Deprecated: 2.26: Rarely used API
217 g_completion_clear_items (GCompletion* cmp)
219 g_return_if_fail (cmp != NULL);
221 g_list_free (cmp->items);
223 g_list_free (cmp->cache);
225 g_free (cmp->prefix);
230 completion_check_cache (GCompletion* cmp,
233 register GList* list;
248 len = strlen(cmp->prefix);
250 s = cmp->func ? cmp->func (list->data) : (gchar*) list->data;
252 plen = strlen (postfix);
257 s = cmp->func ? cmp->func (list->data) : (gchar*) list->data;
259 for (i = 0; i < plen; ++i)
261 if (postfix[i] != s[i])
268 *new_prefix = g_new0 (gchar, len + plen + 1);
269 strncpy (*new_prefix, cmp->prefix, len);
270 strncpy (*new_prefix + len, postfix, plen);
274 * g_completion_complete_utf8:
275 * @cmp: the #GCompletion
276 * @prefix: the prefix string, typically used by the user, which is compared
277 * with each of the items
278 * @new_prefix: if non-%NULL, returns the longest prefix which is common to all
279 * items that matched @prefix, or %NULL if no items matched @prefix.
280 * This string should be freed when no longer needed.
282 * Attempts to complete the string @prefix using the #GCompletion target items.
283 * In contrast to g_completion_complete(), this function returns the largest common
284 * prefix that is a valid UTF-8 string, omitting a possible common partial
287 * You should use this function instead of g_completion_complete() if your
288 * items are UTF-8 strings.
290 * Return value: the list of items whose strings begin with @prefix. This should
295 * Deprecated: 2.26: Rarely used API
298 g_completion_complete_utf8 (GCompletion *cmp,
305 list = g_completion_complete (cmp, prefix, new_prefix);
307 if (new_prefix && *new_prefix)
309 p = *new_prefix + strlen (*new_prefix);
310 q = g_utf8_find_prev_char (*new_prefix, p);
312 switch (g_utf8_get_char_validated (q, p - q))
327 * g_completion_complete:
328 * @cmp: the #GCompletion.
329 * @prefix: the prefix string, typically typed by the user, which is
330 * compared with each of the items.
331 * @new_prefix: if non-%NULL, returns the longest prefix which is
332 * common to all items that matched @prefix, or %NULL if
333 * no items matched @prefix. This string should be freed
334 * when no longer needed.
335 * @Returns: the list of items whose strings begin with @prefix. This
336 * should not be changed.
338 * Attempts to complete the string @prefix using the #GCompletion
341 * Deprecated: 2.26: Rarely used API
344 g_completion_complete (GCompletion* cmp,
349 gboolean done = FALSE;
352 g_return_val_if_fail (cmp != NULL, NULL);
353 g_return_val_if_fail (prefix != NULL, NULL);
355 len = strlen (prefix);
356 if (cmp->prefix && cmp->cache)
358 plen = strlen (cmp->prefix);
359 if (plen <= len && ! cmp->strncmp_func (prefix, cmp->prefix, plen))
365 GList *next = list->next;
367 if (cmp->strncmp_func (prefix,
368 cmp->func ? cmp->func (list->data) : (gchar*) list->data,
370 cmp->cache = g_list_delete_link (cmp->cache, list);
381 g_list_free (cmp->cache);
384 while (*prefix && list)
386 if (!cmp->strncmp_func (prefix,
387 cmp->func ? cmp->func (list->data) : (gchar*) list->data,
389 cmp->cache = g_list_prepend (cmp->cache, list->data);
395 g_free (cmp->prefix);
399 cmp->prefix = g_strdup (prefix);
400 completion_check_cache (cmp, new_prefix);
402 return *prefix ? cmp->cache : cmp->items;
407 * @cmp: the #GCompletion.
409 * Frees all memory used by the #GCompletion.
411 * Deprecated: 2.26: Rarely used API
414 g_completion_free (GCompletion* cmp)
416 g_return_if_fail (cmp != NULL);
418 g_completion_clear_items (cmp);
423 * g_completion_set_compare:
424 * @cmp: a #GCompletion.
425 * @strncmp_func: the string comparison function.
427 * Sets the function to use for string comparisons. The default string
428 * comparison function is strncmp().
430 * Deprecated: 2.26: Rarely used API
433 g_completion_set_compare(GCompletion *cmp,
434 GCompletionStrncmpFunc strncmp_func)
436 cmp->strncmp_func = strncmp_func;
439 #ifdef TEST_COMPLETION
456 g_warning ("Usage: %s filename prefix1 [prefix2 ...]\n", argv[0]);
460 file = fopen (argv[1], "r");
463 g_warning ("Cannot open %s\n", argv[1]);
467 cmp = g_completion_new (NULL);
468 list = g_list_alloc ();
469 while (fgets (buf, 1024, file))
471 list->data = g_strdup (buf);
472 g_completion_add_items (cmp, list);
476 for (i = 2; i < argc; ++i)
478 printf ("COMPLETING: %s\n", argv[i]);
479 result = g_completion_complete (cmp, argv[i], &longp);
480 g_list_foreach (result, (GFunc) printf, NULL);
481 printf ("LONG MATCH: %s\n", longp);
486 g_list_foreach (cmp->items, (GFunc) g_free, NULL);
487 g_completion_free (cmp);
494 #define __G_COMPLETION_C__
495 #include "galiasdef.c"