libguile/symbols.c

   1 /* Copyright (C) 1995,1996,1997,1998,2000,2001 Free Software Foundation, Inc.
   2  *
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2, or (at your option)
   6  * any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License
  14  * along with this software; see the file COPYING.  If not, write to
  15  * the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  16  * Boston, MA 02111-1307 USA
  17  *
  18  * As a special exception, the Free Software Foundation gives permission
  19  * for additional uses of the text contained in its release of GUILE.
  20  *
  21  * The exception is that, if you link the GUILE library with other files
  22  * to produce an executable, this does not by itself cause the
  23  * resulting executable to be covered by the GNU General Public License.
  24  * Your use of that executable is in no way restricted on account of
  25  * linking the GUILE library code into it.
  26  *
  27  * This exception does not however invalidate any other reasons why
  28  * the executable file might be covered by the GNU General Public License.
  29  *
  30  * This exception applies only to the code released by the
  31  * Free Software Foundation under the name GUILE.  If you copy
  32  * code from other Free Software Foundation releases into a copy of
  33  * GUILE, as the General Public License permits, the exception does
  34  * not apply to the code that you add in this way.  To avoid misleading
  35  * anyone as to the status of such modified files, you must delete
  36  * this exception notice from them.
  37  *
  38  * If you write modifications of your own for GUILE, it is your choice
  39  * whether to permit this exception to apply to your modifications.
  40  * If you do not wish that, delete this exception notice.  */
  41
  42
  43 \f
  44
  45 #include "libguile/_scm.h"
  46 #include "libguile/chars.h"
  47 #include "libguile/eval.h"
  48 #include "libguile/hash.h"
  49 #include "libguile/smob.h"
  50 #include "libguile/variable.h"
  51 #include "libguile/alist.h"
  52 #include "libguile/fluids.h"
  53 #include "libguile/strings.h"
  54 #include "libguile/vectors.h"
  55 #include "libguile/hashtab.h"
  56 #include "libguile/weaks.h"
  57 #include "libguile/modules.h"
  58
  59 #include "libguile/validate.h"
  60 #include "libguile/symbols.h"
  61
  62 #ifdef HAVE_STRING_H
  63 #include <string.h>
  64 #endif
  65
  66 \f
  67
  68 static SCM symbols;
  69
  70 #ifdef GUILE_DEBUG
  71 SCM_DEFINE (scm_sys_symbols, "%symbols", 0, 0, 0,
  72             (),
  73             "Return the system symbol obarray.")
  74 #define FUNC_NAME s_scm_sys_symbols
  75 {
  76   return symbols;
  77 }
  78 #undef FUNC_NAME
  79 #endif
  80
  81 \f
  82
  83 /* {Symbols}
  84  */
  85
  86
  87 SCM
  88 scm_mem2symbol (const char *name, size_t len)
  89 {
  90   size_t raw_hash = scm_string_hash ((const unsigned char *) name, len)/2;
  91   size_t hash = raw_hash % SCM_VECTOR_LENGTH (symbols);
  92
  93   {
  94     /* Try to find the symbol in the symbols table */
  95
  96     SCM l;
  97
  98     for (l = SCM_VELTS (symbols) [hash]; !SCM_NULLP (l); l = SCM_CDR (l))
  99       {
 100         SCM sym = SCM_CAAR (l);
 101         if (SCM_SYMBOL_HASH (sym) == raw_hash
 102             && SCM_SYMBOL_LENGTH (sym) == len)
 103           {
 104             char *chrs = SCM_SYMBOL_CHARS (sym);
 105             size_t i = len;
 106
 107             while (i != 0)
 108               {
 109                 --i;
 110                 if (name[i] != chrs[i])
 111                   goto next_symbol;
 112               }
 113
 114             return sym;
 115           }
 116       next_symbol:
 117         ;
 118       }
 119   }
 120
 121   {
 122     /* The symbol was not found - create it. */
 123
 124     SCM symbol;
 125     SCM cell;
 126     SCM slot;
 127
 128     symbol = scm_alloc_double_cell (SCM_MAKE_SYMBOL_TAG (len),
 129                                     (scm_t_bits) scm_gc_strndup (name, len,
 130                                                                  "symbol"),
 131                                     raw_hash,
 132                                     SCM_UNPACK (scm_cons (SCM_BOOL_F,
 133                                                           SCM_EOL)));
 134
 135     slot = SCM_VELTS (symbols) [hash];
 136     cell = scm_cons (symbol, SCM_UNDEFINED);
 137     SCM_VELTS (symbols) [hash] = scm_cons (cell, slot);
 138
 139     return symbol;
 140   }
 141 }
 142
 143 SCM
 144 scm_mem2uninterned_symbol (const char *name, size_t len)
 145 {
 146   size_t raw_hash = (scm_string_hash ((const unsigned char *) name, len)/2
 147                      + SCM_T_BITS_MAX/2 + 1);
 148
 149   return scm_alloc_double_cell (SCM_MAKE_SYMBOL_TAG (len),
 150                                 (scm_t_bits) scm_gc_strndup (name, len,
 151                                                              "symbol"),
 152                                 raw_hash,
 153                                 SCM_UNPACK (scm_cons (SCM_BOOL_F,
 154                                                       SCM_EOL)));
 155 }
 156
 157 SCM
 158 scm_str2symbol (const char *str)
 159 {
 160   return scm_mem2symbol (str, strlen (str));
 161 }
 162
 163 SCM_DEFINE (scm_symbol_p, "symbol?", 1, 0, 0,
 164             (SCM obj),
 165             "Return @code{#t} if @var{obj} is a symbol, otherwise return\n"
 166             "@code{#f}.")
 167 #define FUNC_NAME s_scm_symbol_p
 168 {
 169   return SCM_BOOL (SCM_SYMBOLP (obj));
 170 }
 171 #undef FUNC_NAME
 172
 173 SCM_DEFINE (scm_symbol_interned_p, "symbol-interned?", 1, 0, 0,
 174             (SCM symbol),
 175             "Return @code{#t} if @var{symbol} is interned, otherwise return\n"
 176             "@code{#f}.")
 177 #define FUNC_NAME s_scm_symbol_interned_p
 178 {
 179   SCM_VALIDATE_SYMBOL (1, symbol);
 180   return SCM_BOOL (SCM_SYMBOL_INTERNED_P (symbol));
 181 }
 182 #undef FUNC_NAME
 183
 184 SCM_DEFINE (scm_make_symbol, "make-symbol", 1, 0, 0,
 185             (SCM name),
 186             "Return a new uninterned symbol with the name @var{name}.  "
 187             "The returned symbol is guaranteed to be unique and future "
 188             "calls to @code{string->symbol} will not return it.")
 189 #define FUNC_NAME s_scm_make_symbol
 190 {
 191   SCM sym;
 192   SCM_VALIDATE_STRING (1, name);
 193   sym = scm_mem2uninterned_symbol (SCM_STRING_CHARS (name),
 194                                    SCM_STRING_LENGTH (name));
 195   scm_remember_upto_here_1 (name);
 196   return sym;
 197 }
 198 #undef FUNC_NAME
 199
 200 SCM_DEFINE (scm_symbol_to_string, "symbol->string", 1, 0, 0,
 201            (SCM s),
 202             "Return the name of @var{symbol} as a string.  If the symbol was\n"
 203             "part of an object returned as the value of a literal expression\n"
 204             "(section @pxref{Literal expressions,,,r5rs, The Revised^5\n"
 205             "Report on Scheme}) or by a call to the @code{read} procedure,\n"
 206             "and its name contains alphabetic characters, then the string\n"
 207             "returned will contain characters in the implementation's\n"
 208             "preferred standard case---some implementations will prefer\n"
 209             "upper case, others lower case.  If the symbol was returned by\n"
 210             "@code{string->symbol}, the case of characters in the string\n"
 211             "returned will be the same as the case in the string that was\n"
 212             "passed to @code{string->symbol}.  It is an error to apply\n"
 213             "mutation procedures like @code{string-set!} to strings returned\n"
 214             "by this procedure.\n"
 215             "\n"
 216             "The following examples assume that the implementation's\n"
 217             "standard case is lower case:\n"
 218             "\n"
 219             "@lisp\n"
 220             "(symbol->string 'flying-fish)    @result{} \"flying-fish\"\n"
 221             "(symbol->string 'Martin)         @result{}  \"martin\"\n"
 222             "(symbol->string\n"
 223             "   (string->symbol \"Malvina\")) @result{} \"Malvina\"\n"
 224             "@end lisp")
 225 #define FUNC_NAME s_scm_symbol_to_string
 226 {
 227   SCM str;
 228   SCM_VALIDATE_SYMBOL (1, s);
 229   str = scm_mem2string (SCM_SYMBOL_CHARS (s), SCM_SYMBOL_LENGTH (s));
 230   scm_remember_upto_here_1 (s);
 231   return str;
 232 }
 233 #undef FUNC_NAME
 234
 235
 236 SCM_DEFINE (scm_string_to_symbol, "string->symbol", 1, 0, 0,
 237             (SCM string),
 238             "Return the symbol whose name is @var{string}. This procedure\n"
 239             "can create symbols with names containing special characters or\n"
 240             "letters in the non-standard case, but it is usually a bad idea\n"
 241             "to create such symbols because in some implementations of\n"
 242             "Scheme they cannot be read as themselves.  See\n"
 243             "@code{symbol->string}.\n"
 244             "\n"
 245             "The following examples assume that the implementation's\n"
 246             "standard case is lower case:\n"
 247             "\n"
 248             "@lisp\n"
 249             "(eq? 'mISSISSIppi 'mississippi) @result{} #t\n"
 250             "(string->symbol \"mISSISSIppi\") @result{} @r{the symbol with name \"mISSISSIppi\"}\n"
 251             "(eq? 'bitBlt (string->symbol \"bitBlt\")) @result{} #f\n"
 252             "(eq? 'JollyWog\n"
 253             "  (string->symbol (symbol->string 'JollyWog))) @result{} #t\n"
 254             "(string=? \"K. Harper, M.D.\"\n"
 255             "  (symbol->string\n"
 256             "    (string->symbol \"K. Harper, M.D.\"))) @result{}#t\n"
 257             "@end lisp")
 258 #define FUNC_NAME s_scm_string_to_symbol
 259 {
 260   SCM sym;
 261   SCM_VALIDATE_STRING (1, string);
 262   sym = scm_mem2symbol (SCM_STRING_CHARS (string),
 263                         SCM_STRING_LENGTH (string));
 264   scm_remember_upto_here_1 (string);
 265   return sym;
 266 }
 267 #undef FUNC_NAME
 268
 269 #define MAX_PREFIX_LENGTH 30
 270
 271 static int gensym_counter;
 272
 273 SCM_DEFINE (scm_gensym, "gensym", 0, 1, 0,
 274             (SCM prefix),
 275             "Create a new symbol with a name constructed from a prefix and\n"
 276             "a counter value. The string @var{prefix} can be specified as\n"
 277             "an optional argument. Default prefix is @code{ g}.  The counter\n"
 278             "is increased by 1 at each call. There is no provision for\n"
 279             "resetting the counter.")
 280 #define FUNC_NAME s_scm_gensym
 281 {
 282   char buf[MAX_PREFIX_LENGTH + SCM_INTBUFLEN];
 283   char *name = buf;
 284   size_t len;
 285   if (SCM_UNBNDP (prefix))
 286     {
 287       name[0] = ' ';
 288       name[1] = 'g';
 289       len = 2;
 290     }
 291   else
 292     {
 293       SCM_VALIDATE_STRING (1, prefix);
 294       len = SCM_STRING_LENGTH (prefix);
 295       if (len > MAX_PREFIX_LENGTH)
 296         name = scm_malloc (len + SCM_INTBUFLEN);
 297       memcpy (name, SCM_STRING_CHARS (prefix), len);
 298     }
 299   {
 300     int n_digits = scm_iint2str (gensym_counter++, 10, &name[len]);
 301     SCM res = scm_mem2symbol (name, len + n_digits);
 302     if (name != buf)
 303       free (name);
 304     return res;
 305   }
 306 }
 307 #undef FUNC_NAME
 308
 309 SCM_DEFINE (scm_symbol_hash, "symbol-hash", 1, 0, 0,
 310             (SCM symbol),
 311             "Return a hash value for @var{symbol}.")
 312 #define FUNC_NAME s_scm_symbol_hash
 313 {
 314   SCM_VALIDATE_SYMBOL (1, symbol);
 315   return scm_ulong2num (SCM_SYMBOL_HASH (symbol));
 316 }
 317 #undef FUNC_NAME
 318
 319 SCM_DEFINE (scm_symbol_fref, "symbol-fref", 1, 0, 0,
 320            (SCM s),
 321             "Return the contents of @var{symbol}'s @dfn{function slot}.")
 322 #define FUNC_NAME s_scm_symbol_fref
 323 {
 324   SCM_VALIDATE_SYMBOL (1,s);
 325   return SCM_SYMBOL_FUNC (s);
 326 }
 327 #undef FUNC_NAME
 328
 329
 330 SCM_DEFINE (scm_symbol_pref, "symbol-pref", 1, 0, 0,
 331            (SCM s),
 332             "Return the @dfn{property list} currently associated with @var{symbol}.")
 333 #define FUNC_NAME s_scm_symbol_pref
 334 {
 335   SCM_VALIDATE_SYMBOL (1,s);
 336   return SCM_SYMBOL_PROPS (s);
 337 }
 338 #undef FUNC_NAME
 339
 340
 341 SCM_DEFINE (scm_symbol_fset_x, "symbol-fset!", 2, 0, 0,
 342            (SCM s, SCM val),
 343             "Change the binding of @var{symbol}'s function slot.")
 344 #define FUNC_NAME s_scm_symbol_fset_x
 345 {
 346   SCM_VALIDATE_SYMBOL (1,s);
 347   SCM_SET_SYMBOL_FUNC (s, val);
 348   return SCM_UNSPECIFIED;
 349 }
 350 #undef FUNC_NAME
 351
 352
 353 SCM_DEFINE (scm_symbol_pset_x, "symbol-pset!", 2, 0, 0,
 354            (SCM s, SCM val),
 355             "Change the binding of @var{symbol}'s property slot.")
 356 #define FUNC_NAME s_scm_symbol_pset_x
 357 {
 358   SCM_VALIDATE_SYMBOL (1,s);
 359   SCM_DEFER_INTS;
 360   SCM_SET_SYMBOL_PROPS (s, val);
 361   SCM_ALLOW_INTS;
 362   return SCM_UNSPECIFIED;
 363 }
 364 #undef FUNC_NAME
 365
 366
 367 /* Converts the given Scheme symbol OBJ into a C string, containing a copy
 368    of OBJ's content with a trailing null byte.  If LENP is non-NULL, set
 369    *LENP to the string's length.
 370
 371    When STR is non-NULL it receives the copy and is returned by the function,
 372    otherwise new memory is allocated and the caller is responsible for
 373    freeing it via free().  If out of memory, NULL is returned.
 374
 375    Note that Scheme symbols may contain arbitrary data, including null
 376    characters.  This means that null termination is not a reliable way to
 377    determine the length of the returned value.  However, the function always
 378    copies the complete contents of OBJ, and sets *LENP to the length of the
 379    scheme symbol (if LENP is non-null).  */
 380 #define FUNC_NAME "scm_c_symbol2str"
 381 char *
 382 scm_c_symbol2str (SCM obj, char *str, size_t *lenp)
 383 {
 384   size_t len;
 385
 386   SCM_ASSERT (SCM_SYMBOLP (obj), obj, SCM_ARG1, FUNC_NAME);
 387   len = SCM_SYMBOL_LENGTH (obj);
 388
 389   if (str == NULL)
 390     {
 391       /* FIXME: Should we use exported wrappers for malloc (and free), which
 392        * allow windows DLLs to call the correct freeing function? */
 393       str = (char *) malloc ((len + 1) * sizeof (char));
 394       if (str == NULL)
 395         return NULL;
 396     }
 397
 398   memcpy (str, SCM_SYMBOL_CHARS (obj), len);
 399   scm_remember_upto_here_1 (obj);
 400   str[len] = '\0';
 401
 402   if (lenp != NULL)
 403     *lenp = len;
 404
 405   return str;
 406 }
 407 #undef FUNC_NAME
 408
 409
 410 void
 411 scm_symbols_prehistory ()
 412 {
 413   symbols = scm_make_weak_key_hash_table (SCM_MAKINUM (1009));
 414   scm_permanent_object (symbols);
 415 }
 416
 417
 418 void
 419 scm_init_symbols ()
 420 {
 421   gensym_counter = 0;
 422 #ifndef SCM_MAGIC_SNARFER
 423 #include "libguile/symbols.x"
 424 #endif
 425 }
 426
 427 /*
 428   Local Variables:
 429   c-file-style: "gnu"
 430   End:
 431 */