glib/gcompletion.c

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   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.
   8  *
   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.
  13  *
  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.
  18  */
  19
  20 /*
  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/.
  25  */
  26
  27 /*
  28  * MT safe
  29  */
  30
  31 #include "config.h"
  32
  33 #include <string.h>
  34
  35 #include "glib.h"
  36 #include "galias.h"
  37
  38 /**
  39  * SECTION: completion
  40  * @title: Automatic String Completion
  41  * @short_description: support for automatic completion using a group
  42  *                     of target strings
  43  *
  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.
  47  *
  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().
  54  *
  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().
  61  **/
  62
  63 /**
  64  * GCompletion:
  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.
  73  *
  74  * The data structure used for automatic completion.
  75  **/
  76
  77 /**
  78  * GCompletionFunc:
  79  * @Param1: the completion item.
  80  * @Returns: the string corresponding to the item.
  81  *
  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.
  85  **/
  86
  87 /**
  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
  95  *           bytes of @s2.
  96  *
  97  * Specifies the type of the function passed to
  98  * g_completion_set_compare(). This is used when you use strings as
  99  * #GCompletion items.
 100  **/
 101
 102 static void completion_check_cache (GCompletion* cmp,
 103                                     gchar**      new_prefix);
 104
 105 /**
 106  * g_completion_new:
 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.
 111  *
 112  * Creates a new #GCompletion.
 113  **/
 114 GCompletion*
 115 g_completion_new (GCompletionFunc func)
 116 {
 117   GCompletion* gcomp;
 118
 119   gcomp = g_new (GCompletion, 1);
 120   gcomp->items = NULL;
 121   gcomp->cache = NULL;
 122   gcomp->prefix = NULL;
 123   gcomp->func = func;
 124   gcomp->strncmp_func = strncmp;
 125
 126   return gcomp;
 127 }
 128
 129 /**
 130  * g_completion_add_items:
 131  * @cmp: the #GCompletion.
 132  * @items: the list of items to add.
 133  *
 134  * Adds items to the #GCompletion.
 135  **/
 136 void
 137 g_completion_add_items (GCompletion* cmp,
 138                         GList*       items)
 139 {
 140   GList* it;
 141
 142   g_return_if_fail (cmp != NULL);
 143
 144   /* optimize adding to cache? */
 145   if (cmp->cache)
 146     {
 147       g_list_free (cmp->cache);
 148       cmp->cache = NULL;
 149     }
 150
 151   if (cmp->prefix)
 152     {
 153       g_free (cmp->prefix);
 154       cmp->prefix = NULL;
 155     }
 156
 157   it = items;
 158   while (it)
 159     {
 160       cmp->items = g_list_prepend (cmp->items, it->data);
 161       it = it->next;
 162     }
 163 }
 164
 165 /**
 166  * g_completion_remove_items:
 167  * @cmp: the #GCompletion.
 168  * @items: the items to remove.
 169  *
 170  * Removes items from a #GCompletion.
 171  **/
 172 void
 173 g_completion_remove_items (GCompletion* cmp,
 174                            GList*       items)
 175 {
 176   GList* it;
 177
 178   g_return_if_fail (cmp != NULL);
 179
 180   it = items;
 181   while (cmp->items && it)
 182     {
 183       cmp->items = g_list_remove (cmp->items, it->data);
 184       it = it->next;
 185     }
 186
 187   it = items;
 188   while (cmp->cache && it)
 189     {
 190       cmp->cache = g_list_remove(cmp->cache, it->data);
 191       it = it->next;
 192     }
 193 }
 194
 195 /**
 196  * g_completion_clear_items:
 197  * @cmp: the #GCompletion.
 198  *
 199  * Removes all items from the #GCompletion.
 200  **/
 201 void
 202 g_completion_clear_items (GCompletion* cmp)
 203 {
 204   g_return_if_fail (cmp != NULL);
 205
 206   g_list_free (cmp->items);
 207   cmp->items = NULL;
 208   g_list_free (cmp->cache);
 209   cmp->cache = NULL;
 210   g_free (cmp->prefix);
 211   cmp->prefix = NULL;
 212 }
 213
 214 static void
 215 completion_check_cache (GCompletion* cmp,
 216                         gchar**      new_prefix)
 217 {
 218   register GList* list;
 219   register gsize len;
 220   register gsize i;
 221   register gsize plen;
 222   gchar* postfix;
 223   gchar* s;
 224
 225   if (!new_prefix)
 226     return;
 227   if (!cmp->cache)
 228     {
 229       *new_prefix = NULL;
 230       return;
 231     }
 232
 233   len = strlen(cmp->prefix);
 234   list = cmp->cache;
 235   s = cmp->func ? cmp->func (list->data) : (gchar*) list->data;
 236   postfix = s + len;
 237   plen = strlen (postfix);
 238   list = list->next;
 239
 240   while (list && plen)
 241     {
 242       s = cmp->func ? cmp->func (list->data) : (gchar*) list->data;
 243       s += len;
 244       for (i = 0; i < plen; ++i)
 245         {
 246           if (postfix[i] != s[i])
 247             break;
 248         }
 249       plen = i;
 250       list = list->next;
 251     }
 252
 253   *new_prefix = g_new0 (gchar, len + plen + 1);
 254   strncpy (*new_prefix, cmp->prefix, len);
 255   strncpy (*new_prefix + len, postfix, plen);
 256 }
 257
 258 /**
 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.
 266  *
 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
 270  * character.
 271  *
 272  * You should use this function instead of g_completion_complete() if your
 273  * items are UTF-8 strings.
 274  *
 275  * Return value: the list of items whose strings begin with @prefix. This should
 276  * not be changed.
 277  *
 278  * Since: 2.4
 279  **/
 280 GList*
 281 g_completion_complete_utf8 (GCompletion  *cmp,
 282                             const gchar  *prefix,
 283                             gchar       **new_prefix)
 284 {
 285   GList *list;
 286   gchar *p, *q;
 287
 288   list = g_completion_complete (cmp, prefix, new_prefix);
 289
 290   if (new_prefix && *new_prefix)
 291     {
 292       p = *new_prefix + strlen (*new_prefix);
 293       q = g_utf8_find_prev_char (*new_prefix, p);
 294
 295       switch (g_utf8_get_char_validated (q, p - q))
 296         {
 297         case (gunichar)-2:
 298         case (gunichar)-1:
 299           *q = 0;
 300           break;
 301         default: ;
 302         }
 303
 304     }
 305
 306   return list;
 307 }
 308
 309 /**
 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.
 320  *
 321  * Attempts to complete the string @prefix using the #GCompletion
 322  * target items.
 323  **/
 324 GList*
 325 g_completion_complete (GCompletion* cmp,
 326                        const gchar* prefix,
 327                        gchar**      new_prefix)
 328 {
 329   gsize plen, len;
 330   gboolean done = FALSE;
 331   GList* list;
 332
 333   g_return_val_if_fail (cmp != NULL, NULL);
 334   g_return_val_if_fail (prefix != NULL, NULL);
 335
 336   len = strlen (prefix);
 337   if (cmp->prefix && cmp->cache)
 338     {
 339       plen = strlen (cmp->prefix);
 340       if (plen <= len && ! cmp->strncmp_func (prefix, cmp->prefix, plen))
 341         {
 342           /* use the cache */
 343           list = cmp->cache;
 344           while (list)
 345             {
 346               GList *next = list->next;
 347
 348               if (cmp->strncmp_func (prefix,
 349                                      cmp->func ? cmp->func (list->data) : (gchar*) list->data,
 350                                      len))
 351                 cmp->cache = g_list_delete_link (cmp->cache, list);
 352
 353               list = next;
 354             }
 355           done = TRUE;
 356         }
 357     }
 358
 359   if (!done)
 360     {
 361       /* normal code */
 362       g_list_free (cmp->cache);
 363       cmp->cache = NULL;
 364       list = cmp->items;
 365       while (*prefix && list)
 366         {
 367           if (!cmp->strncmp_func (prefix,
 368                         cmp->func ? cmp->func (list->data) : (gchar*) list->data,
 369                         len))
 370             cmp->cache = g_list_prepend (cmp->cache, list->data);
 371           list = list->next;
 372         }
 373     }
 374   if (cmp->prefix)
 375     {
 376       g_free (cmp->prefix);
 377       cmp->prefix = NULL;
 378     }
 379   if (cmp->cache)
 380     cmp->prefix = g_strdup (prefix);
 381   completion_check_cache (cmp, new_prefix);
 382
 383   return *prefix ? cmp->cache : cmp->items;
 384 }
 385
 386 /**
 387  * g_completion_free:
 388  * @cmp: the #GCompletion.
 389  *
 390  * Frees all memory used by the #GCompletion.
 391  **/
 392 void
 393 g_completion_free (GCompletion* cmp)
 394 {
 395   g_return_if_fail (cmp != NULL);
 396
 397   g_completion_clear_items (cmp);
 398   g_free (cmp);
 399 }
 400
 401 /**
 402  * g_completion_set_compare:
 403  * @cmp: a #GCompletion.
 404  * @strncmp_func: the string comparison function.
 405  *
 406  * Sets the function to use for string comparisons. The default string
 407  * comparison function is strncmp().
 408  **/
 409 void
 410 g_completion_set_compare(GCompletion *cmp,
 411                          GCompletionStrncmpFunc strncmp_func)
 412 {
 413   cmp->strncmp_func = strncmp_func;
 414 }
 415
 416 #ifdef TEST_COMPLETION
 417 #include <stdio.h>
 418 int
 419 main (int   argc,
 420       char* argv[])
 421 {
 422   FILE *file;
 423   gchar buf[1024];
 424   GList *list;
 425   GList *result;
 426   GList *tmp;
 427   GCompletion *cmp;
 428   gint i;
 429   gchar *longp = NULL;
 430
 431   if (argc < 3)
 432     {
 433       g_warning ("Usage: %s filename prefix1 [prefix2 ...]\n", argv[0]);
 434       return 1;
 435     }
 436
 437   file = fopen (argv[1], "r");
 438   if (!file)
 439     {
 440       g_warning ("Cannot open %s\n", argv[1]);
 441       return 1;
 442     }
 443
 444   cmp = g_completion_new (NULL);
 445   list = g_list_alloc ();
 446   while (fgets (buf, 1024, file))
 447     {
 448       list->data = g_strdup (buf);
 449       g_completion_add_items (cmp, list);
 450     }
 451   fclose (file);
 452
 453   for (i = 2; i < argc; ++i)
 454     {
 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);
 459       g_free (longp);
 460       longp = NULL;
 461     }
 462
 463   g_list_foreach (cmp->items, (GFunc) g_free, NULL);
 464   g_completion_free (cmp);
 465   g_list_free (list);
 466
 467   return 0;
 468 }
 469 #endif
 470
 471 #define __G_COMPLETION_C__
 472 #include "galiasdef.c"