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/.
40 * @title: Automatic String Completion
41 * @short_description: support for automatic completion using a group
44 * #GCompletion provides support for automatic completion of a string
45 * using any group of target strings. It is typically used for file
46 * name completion as is common in many UNIX shells.
48 * A #GCompletion is created using g_completion_new(). Target items are
49 * added and removed with g_completion_add_items(),
50 * g_completion_remove_items() and g_completion_clear_items(). A
51 * completion attempt is requested with g_completion_complete() or
52 * g_completion_complete_utf8(). When no longer needed, the
53 * #GCompletion is freed with g_completion_free().
55 * Items in the completion can be simple strings (e.g. filenames), or
56 * pointers to arbitrary data structures. If data structures are used
57 * you must provide a #GCompletionFunc in g_completion_new(), which
58 * retrieves the item's string from the data structure. You can change
59 * the way in which strings are compared by setting a different
60 * #GCompletionStrncmpFunc in g_completion_set_compare().
65 * @items: list of target items (strings or data structures).
66 * @func: function which is called to get the string associated with a
67 * target item. It is %NULL if the target items are strings.
68 * @prefix: the last prefix passed to g_completion_complete() or
69 * g_completion_complete_utf8().
70 * @cache: the list of items which begin with @prefix.
71 * @strncmp_func: The function to use when comparing strings. Use
72 * g_completion_set_compare() to modify this function.
74 * The data structure used for automatic completion.
79 * @Param1: the completion item.
80 * @Returns: the string corresponding to the item.
82 * Specifies the type of the function passed to g_completion_new(). It
83 * should return the string corresponding to the given target item.
84 * This is used when you use data structures as #GCompletion items.
88 * GCompletionStrncmpFunc:
89 * @s1: string to compare with @s2.
90 * @s2: string to compare with @s1.
91 * @n: maximal number of bytes to compare.
92 * @Returns: an integer less than, equal to, or greater than zero if
93 * the first @n bytes of @s1 is found, respectively, to be
94 * less than, to match, or to be greater than the first @n
97 * Specifies the type of the function passed to
98 * g_completion_set_compare(). This is used when you use strings as
102 static void completion_check_cache (GCompletion
* cmp
,
107 * @func: the function to be called to return the string representing
108 * an item in the #GCompletion, or %NULL if strings are going to
109 * be used as the #GCompletion items.
110 * @Returns: the new #GCompletion.
112 * Creates a new #GCompletion.
115 g_completion_new (GCompletionFunc func
)
119 gcomp
= g_new (GCompletion
, 1);
122 gcomp
->prefix
= NULL
;
124 gcomp
->strncmp_func
= strncmp
;
130 * g_completion_add_items:
131 * @cmp: the #GCompletion.
132 * @items: the list of items to add.
134 * Adds items to the #GCompletion.
137 g_completion_add_items (GCompletion
* cmp
,
142 g_return_if_fail (cmp
!= NULL
);
144 /* optimize adding to cache? */
147 g_list_free (cmp
->cache
);
153 g_free (cmp
->prefix
);
160 cmp
->items
= g_list_prepend (cmp
->items
, it
->data
);
166 * g_completion_remove_items:
167 * @cmp: the #GCompletion.
168 * @items: the items to remove.
170 * Removes items from a #GCompletion.
173 g_completion_remove_items (GCompletion
* cmp
,
178 g_return_if_fail (cmp
!= NULL
);
181 while (cmp
->items
&& it
)
183 cmp
->items
= g_list_remove (cmp
->items
, it
->data
);
188 while (cmp
->cache
&& it
)
190 cmp
->cache
= g_list_remove(cmp
->cache
, it
->data
);
196 * g_completion_clear_items:
197 * @cmp: the #GCompletion.
199 * Removes all items from the #GCompletion.
202 g_completion_clear_items (GCompletion
* cmp
)
204 g_return_if_fail (cmp
!= NULL
);
206 g_list_free (cmp
->items
);
208 g_list_free (cmp
->cache
);
210 g_free (cmp
->prefix
);
215 completion_check_cache (GCompletion
* cmp
,
218 register GList
* list
;
233 len
= strlen(cmp
->prefix
);
235 s
= cmp
->func
? cmp
->func (list
->data
) : (gchar
*) list
->data
;
237 plen
= strlen (postfix
);
242 s
= cmp
->func
? cmp
->func (list
->data
) : (gchar
*) list
->data
;
244 for (i
= 0; i
< plen
; ++i
)
246 if (postfix
[i
] != s
[i
])
253 *new_prefix
= g_new0 (gchar
, len
+ plen
+ 1);
254 strncpy (*new_prefix
, cmp
->prefix
, len
);
255 strncpy (*new_prefix
+ len
, postfix
, plen
);
259 * g_completion_complete_utf8:
260 * @cmp: the #GCompletion
261 * @prefix: the prefix string, typically used by the user, which is compared
262 * with each of the items
263 * @new_prefix: if non-%NULL, returns the longest prefix which is common to all
264 * items that matched @prefix, or %NULL if no items matched @prefix.
265 * This string should be freed when no longer needed.
267 * Attempts to complete the string @prefix using the #GCompletion target items.
268 * In contrast to g_completion_complete(), this function returns the largest common
269 * prefix that is a valid UTF-8 string, omitting a possible common partial
272 * You should use this function instead of g_completion_complete() if your
273 * items are UTF-8 strings.
275 * Return value: the list of items whose strings begin with @prefix. This should
281 g_completion_complete_utf8 (GCompletion
*cmp
,
288 list
= g_completion_complete (cmp
, prefix
, new_prefix
);
290 if (new_prefix
&& *new_prefix
)
292 p
= *new_prefix
+ strlen (*new_prefix
);
293 q
= g_utf8_find_prev_char (*new_prefix
, p
);
295 switch (g_utf8_get_char_validated (q
, p
- q
))
310 * g_completion_complete:
311 * @cmp: the #GCompletion.
312 * @prefix: the prefix string, typically typed by the user, which is
313 * compared with each of the items.
314 * @new_prefix: if non-%NULL, returns the longest prefix which is
315 * common to all items that matched @prefix, or %NULL if
316 * no items matched @prefix. This string should be freed
317 * when no longer needed.
318 * @Returns: the list of items whose strings begin with @prefix. This
319 * should not be changed.
321 * Attempts to complete the string @prefix using the #GCompletion
325 g_completion_complete (GCompletion
* cmp
,
330 gboolean done
= FALSE
;
333 g_return_val_if_fail (cmp
!= NULL
, NULL
);
334 g_return_val_if_fail (prefix
!= NULL
, NULL
);
336 len
= strlen (prefix
);
337 if (cmp
->prefix
&& cmp
->cache
)
339 plen
= strlen (cmp
->prefix
);
340 if (plen
<= len
&& ! cmp
->strncmp_func (prefix
, cmp
->prefix
, plen
))
346 GList
*next
= list
->next
;
348 if (cmp
->strncmp_func (prefix
,
349 cmp
->func
? cmp
->func (list
->data
) : (gchar
*) list
->data
,
351 cmp
->cache
= g_list_delete_link (cmp
->cache
, list
);
362 g_list_free (cmp
->cache
);
365 while (*prefix
&& list
)
367 if (!cmp
->strncmp_func (prefix
,
368 cmp
->func
? cmp
->func (list
->data
) : (gchar
*) list
->data
,
370 cmp
->cache
= g_list_prepend (cmp
->cache
, list
->data
);
376 g_free (cmp
->prefix
);
380 cmp
->prefix
= g_strdup (prefix
);
381 completion_check_cache (cmp
, new_prefix
);
383 return *prefix
? cmp
->cache
: cmp
->items
;
388 * @cmp: the #GCompletion.
390 * Frees all memory used by the #GCompletion.
393 g_completion_free (GCompletion
* cmp
)
395 g_return_if_fail (cmp
!= NULL
);
397 g_completion_clear_items (cmp
);
402 * g_completion_set_compare:
403 * @cmp: a #GCompletion.
404 * @strncmp_func: the string comparison function.
406 * Sets the function to use for string comparisons. The default string
407 * comparison function is strncmp().
410 g_completion_set_compare(GCompletion
*cmp
,
411 GCompletionStrncmpFunc strncmp_func
)
413 cmp
->strncmp_func
= strncmp_func
;
416 #ifdef TEST_COMPLETION
433 g_warning ("Usage: %s filename prefix1 [prefix2 ...]\n", argv
[0]);
437 file
= fopen (argv
[1], "r");
440 g_warning ("Cannot open %s\n", argv
[1]);
444 cmp
= g_completion_new (NULL
);
445 list
= g_list_alloc ();
446 while (fgets (buf
, 1024, file
))
448 list
->data
= g_strdup (buf
);
449 g_completion_add_items (cmp
, list
);
453 for (i
= 2; i
< argc
; ++i
)
455 printf ("COMPLETING: %s\n", argv
[i
]);
456 result
= g_completion_complete (cmp
, argv
[i
], &longp
);
457 g_list_foreach (result
, (GFunc
) printf
, NULL
);
458 printf ("LONG MATCH: %s\n", longp
);
463 g_list_foreach (cmp
->items
, (GFunc
) g_free
, NULL
);
464 g_completion_free (cmp
);
471 #define __G_COMPLETION_C__
472 #include "galiasdef.c"