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 "gstrfuncs.h"
  36 #include "gmessages.h"
  37 #include "gunicode.h"
  38
  39 #undef G_DISABLE_DEPRECATED
  40
  41 #include "gcompletion.h"
  42 #include "galias.h"
  43
  44 /**
  45  * SECTION: completion
  46  * @title: Automatic String Completion
  47  * @short_description: support for automatic completion using a group
  48  *                     of target strings
  49  *
  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.
  53  *
  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().
  60  *
  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().
  67  *
  68  * GCompletion has been marked as deprecated, since this API is rarely
  69  * used and not very actively maintained.
  70  **/
  71
  72 /**
  73  * GCompletion:
  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.
  82  *
  83  * The data structure used for automatic completion.
  84  **/
  85
  86 /**
  87  * GCompletionFunc:
  88  * @Param1: the completion item.
  89  * @Returns: the string corresponding to the item.
  90  *
  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.
  94  **/
  95
  96 /**
  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
 104  *           bytes of @s2.
 105  *
 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.
 109  **/
 110
 111 static void completion_check_cache (GCompletion* cmp,
 112                                     gchar**      new_prefix);
 113
 114 /**
 115  * g_completion_new:
 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.
 120  *
 121  * Creates a new #GCompletion.
 122  **/
 123 GCompletion*
 124 g_completion_new (GCompletionFunc func)
 125 {
 126   GCompletion* gcomp;
 127
 128   gcomp = g_new (GCompletion, 1);
 129   gcomp->items = NULL;
 130   gcomp->cache = NULL;
 131   gcomp->prefix = NULL;
 132   gcomp->func = func;
 133   gcomp->strncmp_func = strncmp;
 134
 135   return gcomp;
 136 }
 137
 138 /**
 139  * g_completion_add_items:
 140  * @cmp: the #GCompletion.
 141  * @items: the list of items to add.
 142  *
 143  * Adds items to the #GCompletion.
 144  *
 145  * Deprecated: 2.26: Rarely used API
 146  **/
 147 void
 148 g_completion_add_items (GCompletion* cmp,
 149                         GList*       items)
 150 {
 151   GList* it;
 152
 153   g_return_if_fail (cmp != NULL);
 154
 155   /* optimize adding to cache? */
 156   if (cmp->cache)
 157     {
 158       g_list_free (cmp->cache);
 159       cmp->cache = NULL;
 160     }
 161
 162   if (cmp->prefix)
 163     {
 164       g_free (cmp->prefix);
 165       cmp->prefix = NULL;
 166     }
 167
 168   it = items;
 169   while (it)
 170     {
 171       cmp->items = g_list_prepend (cmp->items, it->data);
 172       it = it->next;
 173     }
 174 }
 175
 176 /**
 177  * g_completion_remove_items:
 178  * @cmp: the #GCompletion.
 179  * @items: the items to remove.
 180  *
 181  * Removes items from a #GCompletion.
 182  *
 183  * Deprecated: 2.26: Rarely used API
 184  **/
 185 void
 186 g_completion_remove_items (GCompletion* cmp,
 187                            GList*       items)
 188 {
 189   GList* it;
 190
 191   g_return_if_fail (cmp != NULL);
 192
 193   it = items;
 194   while (cmp->items && it)
 195     {
 196       cmp->items = g_list_remove (cmp->items, it->data);
 197       it = it->next;
 198     }
 199
 200   it = items;
 201   while (cmp->cache && it)
 202     {
 203       cmp->cache = g_list_remove(cmp->cache, it->data);
 204       it = it->next;
 205     }
 206 }
 207
 208 /**
 209  * g_completion_clear_items:
 210  * @cmp: the #GCompletion.
 211  *
 212  * Removes all items from the #GCompletion.
 213  *
 214  * Deprecated: 2.26: Rarely used API
 215  **/
 216 void
 217 g_completion_clear_items (GCompletion* cmp)
 218 {
 219   g_return_if_fail (cmp != NULL);
 220
 221   g_list_free (cmp->items);
 222   cmp->items = NULL;
 223   g_list_free (cmp->cache);
 224   cmp->cache = NULL;
 225   g_free (cmp->prefix);
 226   cmp->prefix = NULL;
 227 }
 228
 229 static void
 230 completion_check_cache (GCompletion* cmp,
 231                         gchar**      new_prefix)
 232 {
 233   register GList* list;
 234   register gsize len;
 235   register gsize i;
 236   register gsize plen;
 237   gchar* postfix;
 238   gchar* s;
 239
 240   if (!new_prefix)
 241     return;
 242   if (!cmp->cache)
 243     {
 244       *new_prefix = NULL;
 245       return;
 246     }
 247
 248   len = strlen(cmp->prefix);
 249   list = cmp->cache;
 250   s = cmp->func ? cmp->func (list->data) : (gchar*) list->data;
 251   postfix = s + len;
 252   plen = strlen (postfix);
 253   list = list->next;
 254
 255   while (list && plen)
 256     {
 257       s = cmp->func ? cmp->func (list->data) : (gchar*) list->data;
 258       s += len;
 259       for (i = 0; i < plen; ++i)
 260         {
 261           if (postfix[i] != s[i])
 262             break;
 263         }
 264       plen = i;
 265       list = list->next;
 266     }
 267
 268   *new_prefix = g_new0 (gchar, len + plen + 1);
 269   strncpy (*new_prefix, cmp->prefix, len);
 270   strncpy (*new_prefix + len, postfix, plen);
 271 }
 272
 273 /**
 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.
 281  *
 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
 285  * character.
 286  *
 287  * You should use this function instead of g_completion_complete() if your
 288  * items are UTF-8 strings.
 289  *
 290  * Return value: the list of items whose strings begin with @prefix. This should
 291  * not be changed.
 292  *
 293  * Since: 2.4
 294  *
 295  * Deprecated: 2.26: Rarely used API
 296  **/
 297 GList*
 298 g_completion_complete_utf8 (GCompletion  *cmp,
 299                             const gchar  *prefix,
 300                             gchar       **new_prefix)
 301 {
 302   GList *list;
 303   gchar *p, *q;
 304
 305   list = g_completion_complete (cmp, prefix, new_prefix);
 306
 307   if (new_prefix && *new_prefix)
 308     {
 309       p = *new_prefix + strlen (*new_prefix);
 310       q = g_utf8_find_prev_char (*new_prefix, p);
 311
 312       switch (g_utf8_get_char_validated (q, p - q))
 313         {
 314         case (gunichar)-2:
 315         case (gunichar)-1:
 316           *q = 0;
 317           break;
 318         default: ;
 319         }
 320
 321     }
 322
 323   return list;
 324 }
 325
 326 /**
 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.
 337  *
 338  * Attempts to complete the string @prefix using the #GCompletion
 339  * target items.
 340  *
 341  * Deprecated: 2.26: Rarely used API
 342  **/
 343 GList*
 344 g_completion_complete (GCompletion* cmp,
 345                        const gchar* prefix,
 346                        gchar**      new_prefix)
 347 {
 348   gsize plen, len;
 349   gboolean done = FALSE;
 350   GList* list;
 351
 352   g_return_val_if_fail (cmp != NULL, NULL);
 353   g_return_val_if_fail (prefix != NULL, NULL);
 354
 355   len = strlen (prefix);
 356   if (cmp->prefix && cmp->cache)
 357     {
 358       plen = strlen (cmp->prefix);
 359       if (plen <= len && ! cmp->strncmp_func (prefix, cmp->prefix, plen))
 360         {
 361           /* use the cache */
 362           list = cmp->cache;
 363           while (list)
 364             {
 365               GList *next = list->next;
 366
 367               if (cmp->strncmp_func (prefix,
 368                                      cmp->func ? cmp->func (list->data) : (gchar*) list->data,
 369                                      len))
 370                 cmp->cache = g_list_delete_link (cmp->cache, list);
 371
 372               list = next;
 373             }
 374           done = TRUE;
 375         }
 376     }
 377
 378   if (!done)
 379     {
 380       /* normal code */
 381       g_list_free (cmp->cache);
 382       cmp->cache = NULL;
 383       list = cmp->items;
 384       while (*prefix && list)
 385         {
 386           if (!cmp->strncmp_func (prefix,
 387                         cmp->func ? cmp->func (list->data) : (gchar*) list->data,
 388                         len))
 389             cmp->cache = g_list_prepend (cmp->cache, list->data);
 390           list = list->next;
 391         }
 392     }
 393   if (cmp->prefix)
 394     {
 395       g_free (cmp->prefix);
 396       cmp->prefix = NULL;
 397     }
 398   if (cmp->cache)
 399     cmp->prefix = g_strdup (prefix);
 400   completion_check_cache (cmp, new_prefix);
 401
 402   return *prefix ? cmp->cache : cmp->items;
 403 }
 404
 405 /**
 406  * g_completion_free:
 407  * @cmp: the #GCompletion.
 408  *
 409  * Frees all memory used by the #GCompletion.
 410  *
 411  * Deprecated: 2.26: Rarely used API
 412  **/
 413 void
 414 g_completion_free (GCompletion* cmp)
 415 {
 416   g_return_if_fail (cmp != NULL);
 417
 418   g_completion_clear_items (cmp);
 419   g_free (cmp);
 420 }
 421
 422 /**
 423  * g_completion_set_compare:
 424  * @cmp: a #GCompletion.
 425  * @strncmp_func: the string comparison function.
 426  *
 427  * Sets the function to use for string comparisons. The default string
 428  * comparison function is strncmp().
 429  *
 430  * Deprecated: 2.26: Rarely used API
 431  **/
 432 void
 433 g_completion_set_compare(GCompletion *cmp,
 434                          GCompletionStrncmpFunc strncmp_func)
 435 {
 436   cmp->strncmp_func = strncmp_func;
 437 }
 438
 439 #ifdef TEST_COMPLETION
 440 #include <stdio.h>
 441 int
 442 main (int   argc,
 443       char* argv[])
 444 {
 445   FILE *file;
 446   gchar buf[1024];
 447   GList *list;
 448   GList *result;
 449   GList *tmp;
 450   GCompletion *cmp;
 451   gint i;
 452   gchar *longp = NULL;
 453
 454   if (argc < 3)
 455     {
 456       g_warning ("Usage: %s filename prefix1 [prefix2 ...]\n", argv[0]);
 457       return 1;
 458     }
 459
 460   file = fopen (argv[1], "r");
 461   if (!file)
 462     {
 463       g_warning ("Cannot open %s\n", argv[1]);
 464       return 1;
 465     }
 466
 467   cmp = g_completion_new (NULL);
 468   list = g_list_alloc ();
 469   while (fgets (buf, 1024, file))
 470     {
 471       list->data = g_strdup (buf);
 472       g_completion_add_items (cmp, list);
 473     }
 474   fclose (file);
 475
 476   for (i = 2; i < argc; ++i)
 477     {
 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);
 482       g_free (longp);
 483       longp = NULL;
 484     }
 485
 486   g_list_foreach (cmp->items, (GFunc) g_free, NULL);
 487   g_completion_free (cmp);
 488   g_list_free (list);
 489
 490   return 0;
 491 }
 492 #endif
 493
 494 #define __G_COMPLETION_C__
 495 #include "galiasdef.c"