glib/deprecated/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, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 /*
  19  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
  20  * file for a list of people on the GLib Team.  See the ChangeLog
  21  * files for a list of changes.  These files are distributed with
  22  * GLib at ftp://ftp.gtk.org/pub/gtk/.
  23  */
  24
  25 /*
  26  * MT safe
  27  */
  28
  29 #include "config.h"
  30
  31 /* we know we are deprecated here, no need for warnings */
  32 #define GLIB_DISABLE_DEPRECATION_WARNINGS
  33
  34 #include "gcompletion.h"
  35
  36 #include <glib/gstrfuncs.h>
  37 #include <glib/gmessages.h>
  38 #include <glib/gunicode.h>
  39
  40 #include <string.h>
  41
  42 /**
  43  * SECTION:completion
  44  * @title: Automatic String Completion
  45  * @short_description: support for automatic completion using a group
  46  *                     of target strings
  47  *
  48  * #GCompletion provides support for automatic completion of a string
  49  * using any group of target strings. It is typically used for file
  50  * name completion as is common in many UNIX shells.
  51  *
  52  * A #GCompletion is created using g_completion_new(). Target items are
  53  * added and removed with g_completion_add_items(),
  54  * g_completion_remove_items() and g_completion_clear_items(). A
  55  * completion attempt is requested with g_completion_complete() or
  56  * g_completion_complete_utf8(). When no longer needed, the
  57  * #GCompletion is freed with g_completion_free().
  58  *
  59  * Items in the completion can be simple strings (e.g. filenames), or
  60  * pointers to arbitrary data structures. If data structures are used
  61  * you must provide a #GCompletionFunc in g_completion_new(), which
  62  * retrieves the item's string from the data structure. You can change
  63  * the way in which strings are compared by setting a different
  64  * #GCompletionStrncmpFunc in g_completion_set_compare().
  65  *
  66  * GCompletion has been marked as deprecated, since this API is rarely
  67  * used and not very actively maintained.
  68  **/
  69
  70 /**
  71  * GCompletion:
  72  * @items: list of target items (strings or data structures).
  73  * @func: function which is called to get the string associated with a
  74  *        target item. It is %NULL if the target items are strings.
  75  * @prefix: the last prefix passed to g_completion_complete() or
  76  *          g_completion_complete_utf8().
  77  * @cache: the list of items which begin with @prefix.
  78  * @strncmp_func: The function to use when comparing strings.  Use
  79  *                g_completion_set_compare() to modify this function.
  80  *
  81  * The data structure used for automatic completion.
  82  **/
  83
  84 /**
  85  * GCompletionFunc:
  86  * @Param1: the completion item.
  87  *
  88  * Specifies the type of the function passed to g_completion_new(). It
  89  * should return the string corresponding to the given target item.
  90  * This is used when you use data structures as #GCompletion items.
  91  *
  92  * Returns: the string corresponding to the item.
  93  **/
  94
  95 /**
  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  *
 101  * Specifies the type of the function passed to
 102  * g_completion_set_compare(). This is used when you use strings as
 103  * #GCompletion items.
 104  *
 105  * Returns: an integer less than, equal to, or greater than zero if
 106  *          the first @n bytes of @s1 is found, respectively, to be
 107  *          less than, to match, or to be greater than the first @n
 108  *          bytes of @s2.
 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  *
 120  * Creates a new #GCompletion.
 121  *
 122  * Returns: the new #GCompletion.
 123  **/
 124 GCompletion*
 125 g_completion_new (GCompletionFunc func)
 126 {
 127   GCompletion* gcomp;
 128
 129   gcomp = g_new (GCompletion, 1);
 130   gcomp->items = NULL;
 131   gcomp->cache = NULL;
 132   gcomp->prefix = NULL;
 133   gcomp->func = func;
 134   gcomp->strncmp_func = strncmp;
 135
 136   return gcomp;
 137 }
 138
 139 /**
 140  * g_completion_add_items:
 141  * @cmp: the #GCompletion.
 142  * @items: (transfer none): the list of items to add.
 143  *
 144  * Adds items to the #GCompletion.
 145  *
 146  * Deprecated: 2.26: Rarely used API
 147  **/
 148 void
 149 g_completion_add_items (GCompletion* cmp,
 150                         GList*       items)
 151 {
 152   GList* it;
 153
 154   g_return_if_fail (cmp != NULL);
 155
 156   /* optimize adding to cache? */
 157   if (cmp->cache)
 158     {
 159       g_list_free (cmp->cache);
 160       cmp->cache = NULL;
 161     }
 162
 163   if (cmp->prefix)
 164     {
 165       g_free (cmp->prefix);
 166       cmp->prefix = NULL;
 167     }
 168
 169   it = items;
 170   while (it)
 171     {
 172       cmp->items = g_list_prepend (cmp->items, it->data);
 173       it = it->next;
 174     }
 175 }
 176
 177 /**
 178  * g_completion_remove_items:
 179  * @cmp: the #GCompletion.
 180  * @items: (transfer none): the items to remove.
 181  *
 182  * Removes items from a #GCompletion. The items are not freed, so if the memory
 183  * was dynamically allocated, free @items with g_list_free_full() after calling
 184  * this function.
 185  *
 186  * Deprecated: 2.26: Rarely used API
 187  **/
 188 void
 189 g_completion_remove_items (GCompletion* cmp,
 190                            GList*       items)
 191 {
 192   GList* it;
 193
 194   g_return_if_fail (cmp != NULL);
 195
 196   it = items;
 197   while (cmp->items && it)
 198     {
 199       cmp->items = g_list_remove (cmp->items, it->data);
 200       it = it->next;
 201     }
 202
 203   it = items;
 204   while (cmp->cache && it)
 205     {
 206       cmp->cache = g_list_remove(cmp->cache, it->data);
 207       it = it->next;
 208     }
 209 }
 210
 211 /**
 212  * g_completion_clear_items:
 213  * @cmp: the #GCompletion.
 214  *
 215  * Removes all items from the #GCompletion. The items are not freed, so if the
 216  * memory was dynamically allocated, it should be freed after calling this
 217  * function.
 218  *
 219  * Deprecated: 2.26: Rarely used API
 220  **/
 221 void
 222 g_completion_clear_items (GCompletion* cmp)
 223 {
 224   g_return_if_fail (cmp != NULL);
 225
 226   g_list_free (cmp->items);
 227   cmp->items = NULL;
 228   g_list_free (cmp->cache);
 229   cmp->cache = NULL;
 230   g_free (cmp->prefix);
 231   cmp->prefix = NULL;
 232 }
 233
 234 static void
 235 completion_check_cache (GCompletion* cmp,
 236                         gchar**      new_prefix)
 237 {
 238   GList* list;
 239   gsize len;
 240   gsize i;
 241   gsize plen;
 242   gchar* postfix;
 243   gchar* s;
 244
 245   if (!new_prefix)
 246     return;
 247   if (!cmp->cache)
 248     {
 249       *new_prefix = NULL;
 250       return;
 251     }
 252
 253   len = strlen(cmp->prefix);
 254   list = cmp->cache;
 255   s = cmp->func ? cmp->func (list->data) : (gchar*) list->data;
 256   postfix = s + len;
 257   plen = strlen (postfix);
 258   list = list->next;
 259
 260   while (list && plen)
 261     {
 262       s = cmp->func ? cmp->func (list->data) : (gchar*) list->data;
 263       s += len;
 264       for (i = 0; i < plen; ++i)
 265         {
 266           if (postfix[i] != s[i])
 267             break;
 268         }
 269       plen = i;
 270       list = list->next;
 271     }
 272
 273   *new_prefix = g_new0 (gchar, len + plen + 1);
 274   strncpy (*new_prefix, cmp->prefix, len);
 275   strncpy (*new_prefix + len, postfix, plen);
 276 }
 277
 278 /**
 279  * g_completion_complete_utf8:
 280  * @cmp: the #GCompletion
 281  * @prefix: the prefix string, typically used by the user, which is compared
 282  *    with each of the items
 283  * @new_prefix: if non-%NULL, returns the longest prefix which is common to all
 284  *    items that matched @prefix, or %NULL if no items matched @prefix.
 285  *    This string should be freed when no longer needed.
 286  *
 287  * Attempts to complete the string @prefix using the #GCompletion target items.
 288  * In contrast to g_completion_complete(), this function returns the largest common
 289  * prefix that is a valid UTF-8 string, omitting a possible common partial
 290  * character.
 291  *
 292  * You should use this function instead of g_completion_complete() if your
 293  * items are UTF-8 strings.
 294  *
 295  * Returns: (element-type utf8) (transfer none): the list of items whose strings begin with @prefix. This should
 296  * not be changed.
 297  *
 298  * Since: 2.4
 299  *
 300  * Deprecated: 2.26: Rarely used API
 301  **/
 302 GList*
 303 g_completion_complete_utf8 (GCompletion  *cmp,
 304                             const gchar  *prefix,
 305                             gchar       **new_prefix)
 306 {
 307   GList *list;
 308   gchar *p, *q;
 309
 310   list = g_completion_complete (cmp, prefix, new_prefix);
 311
 312   if (new_prefix && *new_prefix)
 313     {
 314       p = *new_prefix + strlen (*new_prefix);
 315       q = g_utf8_find_prev_char (*new_prefix, p);
 316
 317       switch (g_utf8_get_char_validated (q, p - q))
 318         {
 319         case (gunichar)-2:
 320         case (gunichar)-1:
 321           *q = 0;
 322           break;
 323         default: ;
 324         }
 325
 326     }
 327
 328   return list;
 329 }
 330
 331 /**
 332  * g_completion_complete:
 333  * @cmp: the #GCompletion.
 334  * @prefix: the prefix string, typically typed by the user, which is
 335  *          compared with each of the items.
 336  * @new_prefix: if non-%NULL, returns the longest prefix which is
 337  *              common to all items that matched @prefix, or %NULL if
 338  *              no items matched @prefix.  This string should be freed
 339  *              when no longer needed.
 340  *
 341  * Attempts to complete the string @prefix using the #GCompletion
 342  * target items.
 343  *
 344  * Returns: (transfer none): the list of items whose strings begin with
 345  *          @prefix. This should not be changed.
 346  *
 347  * Deprecated: 2.26: Rarely used API
 348  **/
 349 GList*
 350 g_completion_complete (GCompletion* cmp,
 351                        const gchar* prefix,
 352                        gchar**      new_prefix)
 353 {
 354   gsize plen, len;
 355   gboolean done = FALSE;
 356   GList* list;
 357
 358   g_return_val_if_fail (cmp != NULL, NULL);
 359   g_return_val_if_fail (prefix != NULL, NULL);
 360
 361   len = strlen (prefix);
 362   if (cmp->prefix && cmp->cache)
 363     {
 364       plen = strlen (cmp->prefix);
 365       if (plen <= len && ! cmp->strncmp_func (prefix, cmp->prefix, plen))
 366         {
 367           /* use the cache */
 368           list = cmp->cache;
 369           while (list)
 370             {
 371               GList *next = list->next;
 372
 373               if (cmp->strncmp_func (prefix,
 374                                      cmp->func ? cmp->func (list->data) : (gchar*) list->data,
 375                                      len))
 376                 cmp->cache = g_list_delete_link (cmp->cache, list);
 377
 378               list = next;
 379             }
 380           done = TRUE;
 381         }
 382     }
 383
 384   if (!done)
 385     {
 386       /* normal code */
 387       g_list_free (cmp->cache);
 388       cmp->cache = NULL;
 389       list = cmp->items;
 390       while (*prefix && list)
 391         {
 392           if (!cmp->strncmp_func (prefix,
 393                         cmp->func ? cmp->func (list->data) : (gchar*) list->data,
 394                         len))
 395             cmp->cache = g_list_prepend (cmp->cache, list->data);
 396           list = list->next;
 397         }
 398     }
 399   if (cmp->prefix)
 400     {
 401       g_free (cmp->prefix);
 402       cmp->prefix = NULL;
 403     }
 404   if (cmp->cache)
 405     cmp->prefix = g_strdup (prefix);
 406   completion_check_cache (cmp, new_prefix);
 407
 408   return *prefix ? cmp->cache : cmp->items;
 409 }
 410
 411 /**
 412  * g_completion_free:
 413  * @cmp: the #GCompletion.
 414  *
 415  * Frees all memory used by the #GCompletion. The items are not freed, so if
 416  * the memory was dynamically allocated, it should be freed after calling this
 417  * function.
 418  *
 419  * Deprecated: 2.26: Rarely used API
 420  **/
 421 void
 422 g_completion_free (GCompletion* cmp)
 423 {
 424   g_return_if_fail (cmp != NULL);
 425
 426   g_completion_clear_items (cmp);
 427   g_free (cmp);
 428 }
 429
 430 /**
 431  * g_completion_set_compare:
 432  * @cmp: a #GCompletion.
 433  * @strncmp_func: the string comparison function.
 434  *
 435  * Sets the function to use for string comparisons. The default string
 436  * comparison function is strncmp().
 437  *
 438  * Deprecated: 2.26: Rarely used API
 439  **/
 440 void
 441 g_completion_set_compare(GCompletion *cmp,
 442                          GCompletionStrncmpFunc strncmp_func)
 443 {
 444   cmp->strncmp_func = strncmp_func;
 445 }
 446
 447 #ifdef TEST_COMPLETION
 448 #include <stdio.h>
 449 int
 450 main (int   argc,
 451       char* argv[])
 452 {
 453   FILE *file;
 454   gchar buf[1024];
 455   GList *list;
 456   GList *result;
 457   GList *tmp;
 458   GCompletion *cmp;
 459   gint i;
 460   gchar *longp = NULL;
 461
 462   if (argc < 3)
 463     {
 464       g_warning ("Usage: %s filename prefix1 [prefix2 ...]\n", argv[0]);
 465       return 1;
 466     }
 467
 468   file = fopen (argv[1], "r");
 469   if (!file)
 470     {
 471       g_warning ("Cannot open %s\n", argv[1]);
 472       return 1;
 473     }
 474
 475   cmp = g_completion_new (NULL);
 476   list = g_list_alloc ();
 477   while (fgets (buf, 1024, file))
 478     {
 479       list->data = g_strdup (buf);
 480       g_completion_add_items (cmp, list);
 481     }
 482   fclose (file);
 483
 484   for (i = 2; i < argc; ++i)
 485     {
 486       printf ("COMPLETING: %s\n", argv[i]);
 487       result = g_completion_complete (cmp, argv[i], &longp);
 488       g_list_foreach (result, (GFunc) printf, NULL);
 489       printf ("LONG MATCH: %s\n", longp);
 490       g_free (longp);
 491       longp = NULL;
 492     }
 493
 494   g_list_foreach (cmp->items, (GFunc) g_free, NULL);
 495   g_completion_free (cmp);
 496   g_list_free (list);
 497
 498   return 0;
 499 }
 500 #endif