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