428
+ − 1 @c -*-texinfo-*-
+ − 2 @c This is part of the XEmacs Lisp Reference Manual.
+ − 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+ − 4 @c See the file lispref.texi for copying conditions.
+ − 5 @setfilename ../../info/objects.info
693
+ − 6 @node Lisp Data Types, Numbers, Packaging, Top
428
+ − 7 @chapter Lisp Data Types
+ − 8 @cindex object
+ − 9 @cindex Lisp object
+ − 10 @cindex type
+ − 11 @cindex data type
+ − 12
+ − 13 A Lisp @dfn{object} is a piece of data used and manipulated by Lisp
+ − 14 programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of
+ − 15 possible objects.
+ − 16
+ − 17 Every object belongs to at least one type. Objects of the same type
+ − 18 have similar structures and may usually be used in the same contexts.
+ − 19 Types can overlap, and objects can belong to two or more types.
+ − 20 Consequently, we can ask whether an object belongs to a particular type,
+ − 21 but not for ``the'' type of an object.
+ − 22
+ − 23 @cindex primitive type
+ − 24 A few fundamental object types are built into XEmacs. These, from
+ − 25 which all other types are constructed, are called @dfn{primitive types}.
+ − 26 Each object belongs to one and only one primitive type. These types
+ − 27 include @dfn{integer}, @dfn{character} (starting with XEmacs 20.0),
+ − 28 @dfn{float}, @dfn{cons}, @dfn{symbol}, @dfn{string}, @dfn{vector},
+ − 29 @dfn{bit-vector}, @dfn{subr}, @dfn{compiled-function}, @dfn{hash-table},
+ − 30 @dfn{range-table}, @dfn{char-table}, @dfn{weak-list}, and several
+ − 31 special types, such as @dfn{buffer}, that are related to editing.
+ − 32 (@xref{Editing Types}.)
+ − 33
+ − 34 Each primitive type has a corresponding Lisp function that checks
+ − 35 whether an object is a member of that type.
+ − 36
+ − 37 Note that Lisp is unlike many other languages in that Lisp objects are
+ − 38 @dfn{self-typing}: the primitive type of the object is implicit in the
+ − 39 object itself. For example, if an object is a vector, nothing can treat
+ − 40 it as a number; Lisp knows it is a vector, not a number.
+ − 41
+ − 42 In most languages, the programmer must declare the data type of each
+ − 43 variable, and the type is known by the compiler but not represented in
+ − 44 the data. Such type declarations do not exist in XEmacs Lisp. A Lisp
+ − 45 variable can have any type of value, and it remembers whatever value
+ − 46 you store in it, type and all.
+ − 47
+ − 48 This chapter describes the purpose, printed representation, and read
+ − 49 syntax of each of the standard types in Emacs Lisp. Details on how
+ − 50 to use these types can be found in later chapters.
+ − 51
+ − 52 @menu
+ − 53 * Printed Representation:: How Lisp objects are represented as text.
+ − 54 * Comments:: Comments and their formatting conventions.
+ − 55 * Primitive Types:: List of all primitive types in XEmacs.
+ − 56 * Programming Types:: Types found in all Lisp systems.
+ − 57 * Editing Types:: Types specific to XEmacs.
+ − 58 * Window-System Types:: Types specific to windowing systems.
+ − 59 * Type Predicates:: Tests related to types.
+ − 60 * Equality Predicates:: Tests of equality between any two objects.
+ − 61 @end menu
+ − 62
+ − 63 @node Printed Representation
+ − 64 @section Printed Representation and Read Syntax
+ − 65 @cindex printed representation
+ − 66 @cindex read syntax
+ − 67
+ − 68 The @dfn{printed representation} of an object is the format of the
+ − 69 output generated by the Lisp printer (the function @code{prin1}) for
+ − 70 that object. The @dfn{read syntax} of an object is the format of the
+ − 71 input accepted by the Lisp reader (the function @code{read}) for that
+ − 72 object. Most objects have more than one possible read syntax. Some
+ − 73 types of object have no read syntax; except for these cases, the printed
+ − 74 representation of an object is also a read syntax for it.
+ − 75
+ − 76 In other languages, an expression is text; it has no other form. In
+ − 77 Lisp, an expression is primarily a Lisp object and only secondarily the
+ − 78 text that is the object's read syntax. Often there is no need to
+ − 79 emphasize this distinction, but you must keep it in the back of your
+ − 80 mind, or you will occasionally be very confused.
+ − 81
+ − 82 @cindex hash notation
+ − 83 Every type has a printed representation. Some types have no read
+ − 84 syntax, since it may not make sense to enter objects of these types
+ − 85 directly in a Lisp program. For example, the buffer type does not have
+ − 86 a read syntax. Objects of these types are printed in @dfn{hash
+ − 87 notation}: the characters @samp{#<} followed by a descriptive string
+ − 88 (typically the type name followed by the name of the object), and closed
+ − 89 with a matching @samp{>}. Hash notation cannot be read at all, so the
+ − 90 Lisp reader signals the error @code{invalid-read-syntax} whenever it
+ − 91 encounters @samp{#<}.
+ − 92 @kindex invalid-read-syntax
+ − 93
+ − 94 @example
+ − 95 (current-buffer)
+ − 96 @result{} #<buffer "objects.texi">
+ − 97 @end example
+ − 98
+ − 99 When you evaluate an expression interactively, the Lisp interpreter
+ − 100 first reads the textual representation of it, producing a Lisp object,
+ − 101 and then evaluates that object (@pxref{Evaluation}). However,
+ − 102 evaluation and reading are separate activities. Reading returns the
+ − 103 Lisp object represented by the text that is read; the object may or may
+ − 104 not be evaluated later. @xref{Input Functions}, for a description of
+ − 105 @code{read}, the basic function for reading objects.
+ − 106
+ − 107 @node Comments
+ − 108 @section Comments
+ − 109 @cindex comments
+ − 110 @cindex @samp{;} in comment
+ − 111
+ − 112 A @dfn{comment} is text that is written in a program only for the sake
+ − 113 of humans that read the program, and that has no effect on the meaning
+ − 114 of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it
+ − 115 is not within a string or character constant. The comment continues to
+ − 116 the end of line. The Lisp reader discards comments; they do not become
+ − 117 part of the Lisp objects which represent the program within the Lisp
+ − 118 system.
+ − 119
+ − 120 The @samp{#@@@var{count}} construct, which skips the next @var{count}
+ − 121 characters, is useful for program-generated comments containing binary
+ − 122 data. The XEmacs Lisp byte compiler uses this in its output files
+ − 123 (@pxref{Byte Compilation}). It isn't meant for source files, however.
+ − 124
+ − 125 @xref{Comment Tips}, for conventions for formatting comments.
+ − 126
+ − 127 @node Primitive Types
+ − 128 @section Primitive Types
+ − 129 @cindex primitive types
+ − 130
+ − 131 For reference, here is a list of all the primitive types that may
+ − 132 exist in XEmacs. Note that some of these types may not exist
+ − 133 in some XEmacs executables; that depends on the options that
+ − 134 XEmacs was configured with.
+ − 135
+ − 136 @itemize @bullet
+ − 137 @item
+ − 138 bit-vector
+ − 139 @item
+ − 140 buffer
+ − 141 @item
+ − 142 char-table
+ − 143 @item
+ − 144 character
+ − 145 @item
+ − 146 charset
+ − 147 @item
+ − 148 coding-system
+ − 149 @item
+ − 150 cons
+ − 151 @item
+ − 152 color-instance
+ − 153 @item
+ − 154 compiled-function
+ − 155 @item
+ − 156 console
+ − 157 @item
+ − 158 database
+ − 159 @item
+ − 160 device
+ − 161 @item
+ − 162 event
+ − 163 @item
+ − 164 extent
+ − 165 @item
+ − 166 face
+ − 167 @item
+ − 168 float
+ − 169 @item
+ − 170 font-instance
+ − 171 @item
+ − 172 frame
+ − 173 @item
+ − 174 glyph
+ − 175 @item
+ − 176 hash-table
+ − 177 @item
+ − 178 image-instance
+ − 179 @item
+ − 180 integer
+ − 181 @item
+ − 182 keymap
+ − 183 @item
+ − 184 marker
+ − 185 @item
+ − 186 process
+ − 187 @item
+ − 188 range-table
+ − 189 @item
+ − 190 specifier
+ − 191 @item
+ − 192 string
+ − 193 @item
+ − 194 subr
+ − 195 @item
+ − 196 subwindow
+ − 197 @item
+ − 198 symbol
+ − 199 @item
+ − 200 toolbar-button
+ − 201 @item
+ − 202 tooltalk-message
+ − 203 @item
+ − 204 tooltalk-pattern
+ − 205 @item
+ − 206 vector
+ − 207 @item
+ − 208 weak-list
+ − 209 @item
+ − 210 window
+ − 211 @item
+ − 212 window-configuration
+ − 213 @item
+ − 214 x-resource
+ − 215 @end itemize
+ − 216
+ − 217 In addition, the following special types are created internally
+ − 218 but will never be seen by Lisp code. You may encounter them,
+ − 219 however, if you are debugging XEmacs. The printed representation
+ − 220 of these objects begins @samp{#<INTERNAL EMACS BUG}, which indicates
+ − 221 to the Lisp programmer that he has found an internal bug in XEmacs
+ − 222 if he ever encounters any of these objects.
+ − 223
+ − 224 @itemize @bullet
+ − 225 @item
+ − 226 char-table-entry
+ − 227 @item
+ − 228 command-builder
+ − 229 @item
+ − 230 extent-auxiliary
+ − 231 @item
+ − 232 extent-info
+ − 233 @item
+ − 234 lcrecord-list
+ − 235 @item
+ − 236 lstream
+ − 237 @item
+ − 238 opaque
+ − 239 @item
+ − 240 opaque-list
+ − 241 @item
+ − 242 popup-data
+ − 243 @item
+ − 244 symbol-value-buffer-local
+ − 245 @item
+ − 246 symbol-value-forward
+ − 247 @item
+ − 248 symbol-value-lisp-magic
+ − 249 @item
+ − 250 symbol-value-varalias
+ − 251 @item
+ − 252 toolbar-data
+ − 253 @end itemize
+ − 254
+ − 255 @node Programming Types
+ − 256 @section Programming Types
+ − 257 @cindex programming types
+ − 258
+ − 259 There are two general categories of types in XEmacs Lisp: those having
+ − 260 to do with Lisp programming, and those having to do with editing. The
+ − 261 former exist in many Lisp implementations, in one form or another. The
+ − 262 latter are unique to XEmacs Lisp.
+ − 263
+ − 264 @menu
+ − 265 * Integer Type:: Numbers without fractional parts.
+ − 266 * Floating Point Type:: Numbers with fractional parts and with a large range.
+ − 267 * Character Type:: The representation of letters, numbers and
+ − 268 control characters.
+ − 269 * Symbol Type:: A multi-use object that refers to a function,
+ − 270 variable, or property list, and has a unique identity.
+ − 271 * Sequence Type:: Both lists and arrays are classified as sequences.
+ − 272 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
+ − 273 * Array Type:: Arrays include strings and vectors.
+ − 274 * String Type:: An (efficient) array of characters.
+ − 275 * Vector Type:: One-dimensional arrays.
+ − 276 * Bit Vector Type:: An (efficient) array of bits.
+ − 277 * Function Type:: A piece of executable code you can call from elsewhere.
+ − 278 * Macro Type:: A method of expanding an expression into another
+ − 279 expression, more fundamental but less pretty.
+ − 280 * Primitive Function Type:: A function written in C, callable from Lisp.
+ − 281 * Compiled-Function Type:: A function written in Lisp, then compiled.
+ − 282 * Autoload Type:: A type used for automatically loading seldom-used
+ − 283 functions.
+ − 284 * Char Table Type:: A mapping from characters to Lisp objects.
+ − 285 * Hash Table Type:: A fast mapping between Lisp objects.
+ − 286 * Range Table Type:: A mapping from ranges of integers to Lisp objects.
+ − 287 * Weak List Type:: A list with special garbage-collection properties.
+ − 288 @end menu
+ − 289
+ − 290 @node Integer Type
+ − 291 @subsection Integer Type
+ − 292
+ − 293 The range of values for integers in XEmacs Lisp is @minus{}134217728 to
+ − 294 134217727 (28 bits; i.e.,
+ − 295 @ifinfo
+ − 296 -2**27
+ − 297 @end ifinfo
+ − 298 @tex
+ − 299 $-2^{27}$
+ − 300 @end tex
+ − 301 to
+ − 302 @ifinfo
+ − 303 2**27 - 1)
+ − 304 @end ifinfo
+ − 305 @tex
+ − 306 $2^{28}-1$)
+ − 307 @end tex
+ − 308 on most machines. (Some machines, in particular 64-bit machines such as
+ − 309 the DEC Alpha, may provide a wider range.) It is important to note that
+ − 310 the XEmacs Lisp arithmetic functions do not check for overflow. Thus
+ − 311 @code{(1+ 134217727)} is @minus{}134217728 on most machines. (However,
+ − 312 you @emph{will} get an error if you attempt to read an out-of-range
+ − 313 number using the Lisp reader.)
+ − 314
+ − 315 The read syntax for integers is a sequence of (base ten) digits with
+ − 316 an optional sign at the beginning. (The printed representation produced
+ − 317 by the Lisp interpreter never has a leading @samp{+}.)
+ − 318
+ − 319 @example
+ − 320 @group
+ − 321 -1 ; @r{The integer -1.}
+ − 322 1 ; @r{The integer 1.}
+ − 323 +1 ; @r{Also the integer 1.}
+ − 324 268435457 ; @r{Causes an error on a 28-bit implementation.}
+ − 325 @end group
+ − 326 @end example
+ − 327
+ − 328 @xref{Numbers}, for more information.
+ − 329
+ − 330 @node Floating Point Type
+ − 331 @subsection Floating Point Type
+ − 332
+ − 333 XEmacs supports floating point numbers. The precise range of floating
+ − 334 point numbers is machine-specific.
+ − 335
+ − 336 The printed representation for floating point numbers requires either
+ − 337 a decimal point (with at least one digit following), an exponent, or
+ − 338 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
+ − 339 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
+ − 340 number whose value is 1500. They are all equivalent.
+ − 341
+ − 342 @xref{Numbers}, for more information.
+ − 343
+ − 344 @node Character Type
+ − 345 @subsection Character Type
+ − 346 @cindex @sc{ascii} character codes
+ − 347 @cindex char-int confoundance disease
+ − 348
+ − 349 In XEmacs version 19, and in all versions of FSF GNU Emacs, a
+ − 350 @dfn{character} in XEmacs Lisp is nothing more than an integer.
+ − 351 This is yet another holdover from XEmacs Lisp's derivation from
+ − 352 vintage-1980 Lisps; modern versions of Lisp consider this equivalence
+ − 353 a bad idea, and have separate character types. In XEmacs version 20,
+ − 354 the modern convention is followed, and characters are their own
+ − 355 primitive types. (This change was necessary in order for @sc{mule},
+ − 356 i.e. Asian-language, support to be correctly implemented.)
+ − 357
+ − 358 Even in XEmacs version 20, remnants of the equivalence between
+ − 359 characters and integers still exist; this is termed the @dfn{char-int
+ − 360 confoundance disease}. In particular, many functions such as @code{eq},
+ − 361 @code{equal}, and @code{memq} have equivalent functions (@code{old-eq},
+ − 362 @code{old-equal}, @code{old-memq}, etc.) that pretend like characters
+ − 363 are integers are the same. Byte code compiled under any version 19
+ − 364 Emacs will have all such functions mapped to their @code{old-} equivalents
+ − 365 when the byte code is read into XEmacs 20. This is to preserve
440
+ − 366 compatibility---Emacs 19 converts all constant characters to the equivalent
428
+ − 367 integer during byte-compilation, and thus there is no other way to preserve
+ − 368 byte-code compatibility even if the code has specifically been written
+ − 369 with the distinction between characters and integers in mind.
+ − 370
+ − 371 Every character has an equivalent integer, called the @dfn{character
+ − 372 code}. For example, the character @kbd{A} is represented as the
+ − 373 @w{integer 65}, following the standard @sc{ascii} representation of
+ − 374 characters. If XEmacs was not compiled with @sc{mule} support, the
440
+ − 375 range of this integer will always be 0 to 255---eight bits, or one
428
+ − 376 byte. (Integers outside this range are accepted but silently truncated;
+ − 377 however, you should most decidedly @emph{not} rely on this, because it
+ − 378 will not work under XEmacs with @sc{mule} support.) When @sc{mule}
+ − 379 support is present, the range of character codes is much
+ − 380 larger. (Currently, 19 bits are used.)
+ − 381
+ − 382 FSF GNU Emacs uses kludgy character codes above 255 to represent
+ − 383 keyboard input of @sc{ascii} characters in combination with certain
+ − 384 modifiers. XEmacs does not use this (a more general mechanism is
+ − 385 used that does not distinguish between @sc{ascii} keys and other
+ − 386 keys), so you will never find character codes above 255 in a
+ − 387 non-@sc{mule} XEmacs.
+ − 388
+ − 389 Individual characters are not often used in programs. It is far more
+ − 390 common to work with @emph{strings}, which are sequences composed of
+ − 391 characters. @xref{String Type}.
+ − 392
+ − 393 @cindex read syntax for characters
+ − 394 @cindex printed representation for characters
+ − 395 @cindex syntax for characters
+ − 396
+ − 397 The read syntax for characters begins with a question mark, followed
+ − 398 by the character (if it's printable) or some symbolic representation of
+ − 399 it. In XEmacs 20, where characters are their own type, this is also the
+ − 400 print representation. In XEmacs 19, however, where characters are
+ − 401 really integers, the printed representation of a character is a decimal
+ − 402 number. This is also a possible read syntax for a character, but
+ − 403 writing characters that way in Lisp programs is a very bad idea. You
+ − 404 should @emph{always} use the special read syntax formats that XEmacs Lisp
+ − 405 provides for characters.
+ − 406
+ − 407 The usual read syntax for alphanumeric characters is a question mark
+ − 408 followed by the character; thus, @samp{?A} for the character
+ − 409 @kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
+ − 410 character @kbd{a}.
+ − 411
+ − 412 For example:
+ − 413
+ − 414 @example
+ − 415 ;; @r{Under XEmacs 20:}
+ − 416 ?Q @result{} ?Q ?q @result{} ?q
+ − 417 (char-int ?Q) @result{} 81
+ − 418 ;; @r{Under XEmacs 19:}
+ − 419 ?Q @result{} 81 ?q @result{} 113
+ − 420 @end example
+ − 421
+ − 422 You can use the same syntax for punctuation characters, but it is
+ − 423 often a good idea to add a @samp{\} so that the Emacs commands for
+ − 424 editing Lisp code don't get confused. For example, @samp{?\ } is the
+ − 425 way to write the space character. If the character is @samp{\}, you
+ − 426 @emph{must} use a second @samp{\} to quote it: @samp{?\\}. XEmacs 20
+ − 427 always prints punctuation characters with a @samp{\} in front of them,
+ − 428 to avoid confusion.
+ − 429
+ − 430 @cindex whitespace
+ − 431 @cindex bell character
+ − 432 @cindex @samp{\a}
+ − 433 @cindex backspace
+ − 434 @cindex @samp{\b}
+ − 435 @cindex tab
+ − 436 @cindex @samp{\t}
+ − 437 @cindex vertical tab
+ − 438 @cindex @samp{\v}
+ − 439 @cindex formfeed
+ − 440 @cindex @samp{\f}
+ − 441 @cindex newline
+ − 442 @cindex @samp{\n}
+ − 443 @cindex return
+ − 444 @cindex @samp{\r}
+ − 445 @cindex escape
+ − 446 @cindex @samp{\e}
+ − 447 You can express the characters Control-g, backspace, tab, newline,
+ − 448 vertical tab, formfeed, return, and escape as @samp{?\a}, @samp{?\b},
+ − 449 @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, @samp{?\r}, @samp{?\e},
+ − 450 respectively. Their character codes are 7, 8, 9, 10, 11, 12, 13, and 27
+ − 451 in decimal. Thus,
+ − 452
+ − 453 @example
+ − 454 ;; @r{Under XEmacs 20:}
+ − 455 ?\a @result{} ?\^G ; @r{@kbd{C-g}}
+ − 456 (char-int ?\a) @result{} 7
+ − 457 ?\b @result{} ?\^H ; @r{backspace, @key{BS}, @kbd{C-h}}
+ − 458 (char-int ?\b) @result{} 8
+ − 459 ?\t @result{} ?\t ; @r{tab, @key{TAB}, @kbd{C-i}}
+ − 460 (char-int ?\t) @result{} 9
+ − 461 ?\n @result{} ?\n ; @r{newline, @key{LFD}, @kbd{C-j}}
+ − 462 ?\v @result{} ?\^K ; @r{vertical tab, @kbd{C-k}}
+ − 463 ?\f @result{} ?\^L ; @r{formfeed character, @kbd{C-l}}
+ − 464 ?\r @result{} ?\r ; @r{carriage return, @key{RET}, @kbd{C-m}}
+ − 465 ?\e @result{} ?\^[ ; @r{escape character, @key{ESC}, @kbd{C-[}}
+ − 466 ?\\ @result{} ?\\ ; @r{backslash character, @kbd{\}}
+ − 467 ;; @r{Under XEmacs 19:}
+ − 468 ?\a @result{} 7 ; @r{@kbd{C-g}}
+ − 469 ?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
+ − 470 ?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
+ − 471 ?\n @result{} 10 ; @r{newline, @key{LFD}, @kbd{C-j}}
+ − 472 ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
+ − 473 ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
+ − 474 ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
+ − 475 ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
+ − 476 ?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
+ − 477 @end example
+ − 478
+ − 479 @cindex escape sequence
+ − 480 These sequences which start with backslash are also known as
+ − 481 @dfn{escape sequences}, because backslash plays the role of an escape
+ − 482 character; this usage has nothing to do with the character @key{ESC}.
+ − 483
+ − 484 @cindex control characters
+ − 485 Control characters may be represented using yet another read syntax.
+ − 486 This consists of a question mark followed by a backslash, caret, and the
+ − 487 corresponding non-control character, in either upper or lower case. For
+ − 488 example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
+ − 489 character @kbd{C-i}, the character whose value is 9.
+ − 490
+ − 491 Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
+ − 492 equivalent to @samp{?\^I} and to @samp{?\^i}:
+ − 493
+ − 494 @example
+ − 495 ;; @r{Under XEmacs 20:}
+ − 496 ?\^I @result{} ?\t ?\C-I @result{} ?\t
+ − 497 (char-int ?\^I) @result{} 9
+ − 498 ;; @r{Under XEmacs 19:}
+ − 499 ?\^I @result{} 9 ?\C-I @result{} 9
+ − 500 @end example
+ − 501
+ − 502 There is also a character read syntax beginning with @samp{\M-}. This
+ − 503 sets the high bit of the character code (same as adding 128 to the
+ − 504 character code). For example, @samp{?\M-A} stands for the character
+ − 505 with character code 193, or 128 plus 65. You should @emph{not} use this
+ − 506 syntax in your programs. It is a holdover of yet another confoundance
+ − 507 disease from earlier Emacsen. (This was used to represent keyboard input
+ − 508 with the @key{META} key set, thus the @samp{M}; however, it conflicts
+ − 509 with the legitimate @sc{iso}-8859-1 interpretation of the character code.
+ − 510 For example, character code 193 is a lowercase @samp{a} with an acute
+ − 511 accent, in @sc{iso}-8859-1.)
+ − 512
+ − 513 @ignore @c None of this crap applies to XEmacs.
+ − 514 For use in strings and buffers, you are limited to the control
+ − 515 characters that exist in @sc{ascii}, but for keyboard input purposes,
+ − 516 you can turn any character into a control character with @samp{C-}. The
+ − 517 character codes for these non-@sc{ascii} control characters include the
+ − 518 @iftex
+ − 519 $2^{26}$
+ − 520 @end iftex
+ − 521 @ifinfo
+ − 522 2**26
+ − 523 @end ifinfo
+ − 524 bit as well as the code for the corresponding non-control
+ − 525 character. Ordinary terminals have no way of generating non-@sc{ASCII}
+ − 526 control characters, but you can generate them straightforwardly using an
+ − 527 X terminal.
+ − 528
+ − 529 For historical reasons, Emacs treats the @key{DEL} character as
+ − 530 the control equivalent of @kbd{?}:
+ − 531
+ − 532 @example
+ − 533 ?\^? @result{} 127 ?\C-? @result{} 127
+ − 534 @end example
+ − 535
+ − 536 @noindent
+ − 537 As a result, it is currently not possible to represent the character
+ − 538 @kbd{Control-?}, which is a meaningful input character under X. It is
+ − 539 not easy to change this as various Lisp files refer to @key{DEL} in this
+ − 540 way.
+ − 541
+ − 542 For representing control characters to be found in files or strings,
+ − 543 we recommend the @samp{^} syntax; for control characters in keyboard
+ − 544 input, we prefer the @samp{C-} syntax. This does not affect the meaning
+ − 545 of the program, but may guide the understanding of people who read it.
+ − 546
+ − 547 @cindex meta characters
+ − 548 A @dfn{meta character} is a character typed with the @key{META}
+ − 549 modifier key. The integer that represents such a character has the
+ − 550 @iftex
+ − 551 $2^{27}$
+ − 552 @end iftex
+ − 553 @ifinfo
+ − 554 2**27
+ − 555 @end ifinfo
+ − 556 bit set (which on most machines makes it a negative number). We
+ − 557 use high bits for this and other modifiers to make possible a wide range
+ − 558 of basic character codes.
+ − 559
+ − 560 In a string, the
+ − 561 @iftex
+ − 562 $2^{7}$
+ − 563 @end iftex
+ − 564 @ifinfo
+ − 565 2**7
+ − 566 @end ifinfo
+ − 567 bit indicates a meta character, so the meta
+ − 568 characters that can fit in a string have codes in the range from 128 to
+ − 569 255, and are the meta versions of the ordinary @sc{ASCII} characters.
+ − 570 (In Emacs versions 18 and older, this convention was used for characters
+ − 571 outside of strings as well.)
+ − 572
+ − 573 The read syntax for meta characters uses @samp{\M-}. For example,
+ − 574 @samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
+ − 575 octal character codes (see below), with @samp{\C-}, or with any other
+ − 576 syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
+ − 577 or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
+ − 578 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
+ − 579
+ − 580 The case of an ordinary letter is indicated by its character code as
+ − 581 part of @sc{ASCII}, but @sc{ASCII} has no way to represent whether a
+ − 582 control character is upper case or lower case. Emacs uses the
+ − 583 @iftex
+ − 584 $2^{25}$
+ − 585 @end iftex
+ − 586 @ifinfo
+ − 587 2**25
+ − 588 @end ifinfo
+ − 589 bit to indicate that the shift key was used for typing a control
+ − 590 character. This distinction is possible only when you use X terminals
+ − 591 or other special terminals; ordinary terminals do not indicate the
+ − 592 distinction to the computer in any way.
+ − 593
+ − 594 @cindex hyper characters
+ − 595 @cindex super characters
+ − 596 @cindex alt characters
+ − 597 The X Window System defines three other modifier bits that can be set
+ − 598 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
+ − 599 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. Thus,
+ − 600 @samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}.
+ − 601 @iftex
+ − 602 Numerically, the
+ − 603 bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper.
+ − 604 @end iftex
+ − 605 @ifinfo
+ − 606 Numerically, the
+ − 607 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
+ − 608 @end ifinfo
+ − 609 @end ignore
+ − 610
+ − 611 @cindex @samp{?} in character constant
+ − 612 @cindex question mark in character constant
+ − 613 @cindex @samp{\} in character constant
+ − 614 @cindex backslash in character constant
+ − 615 @cindex octal character code
+ − 616 Finally, the most general read syntax consists of a question mark
+ − 617 followed by a backslash and the character code in octal (up to three
+ − 618 octal digits); thus, @samp{?\101} for the character @kbd{A},
+ − 619 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
+ − 620 character @kbd{C-b}. Although this syntax can represent any @sc{ascii}
+ − 621 character, it is preferred only when the precise octal value is more
+ − 622 important than the @sc{ascii} representation.
+ − 623
+ − 624 @example
+ − 625 @group
+ − 626 ;; @r{Under XEmacs 20:}
+ − 627 ?\012 @result{} ?\n ?\n @result{} ?\n ?\C-j @result{} ?\n
+ − 628 ?\101 @result{} ?A ?A @result{} ?A
+ − 629 @end group
+ − 630 @group
+ − 631 ;; @r{Under XEmacs 19:}
+ − 632 ?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10
+ − 633 ?\101 @result{} 65 ?A @result{} 65
+ − 634 @end group
+ − 635 @end example
+ − 636
+ − 637 A backslash is allowed, and harmless, preceding any character without
+ − 638 a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
+ − 639 There is no reason to add a backslash before most characters. However,
+ − 640 you should add a backslash before any of the characters
+ − 641 @samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing
+ − 642 Lisp code. Also add a backslash before whitespace characters such as
+ − 643 space, tab, newline and formfeed. However, it is cleaner to use one of
+ − 644 the easily readable escape sequences, such as @samp{\t}, instead of an
+ − 645 actual whitespace character such as a tab.
+ − 646
+ − 647 @node Symbol Type
+ − 648 @subsection Symbol Type
+ − 649
+ − 650 A @dfn{symbol} in XEmacs Lisp is an object with a name. The symbol
+ − 651 name serves as the printed representation of the symbol. In ordinary
+ − 652 use, the name is unique---no two symbols have the same name.
+ − 653
+ − 654 A symbol can serve as a variable, as a function name, or to hold a
+ − 655 property list. Or it may serve only to be distinct from all other Lisp
+ − 656 objects, so that its presence in a data structure may be recognized
+ − 657 reliably. In a given context, usually only one of these uses is
+ − 658 intended. But you can use one symbol in all of these ways,
+ − 659 independently.
+ − 660
+ − 661 @cindex @samp{\} in symbols
+ − 662 @cindex backslash in symbols
+ − 663 A symbol name can contain any characters whatever. Most symbol names
+ − 664 are written with letters, digits, and the punctuation characters
+ − 665 @samp{-+=*/}. Such names require no special punctuation; the characters
+ − 666 of the name suffice as long as the name does not look like a number.
+ − 667 (If it does, write a @samp{\} at the beginning of the name to force
+ − 668 interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}} are
+ − 669 less often used but also require no special punctuation. Any other
+ − 670 characters may be included in a symbol's name by escaping them with a
+ − 671 backslash. In contrast to its use in strings, however, a backslash in
+ − 672 the name of a symbol simply quotes the single character that follows the
+ − 673 backslash. For example, in a string, @samp{\t} represents a tab
+ − 674 character; in the name of a symbol, however, @samp{\t} merely quotes the
+ − 675 letter @kbd{t}. To have a symbol with a tab character in its name, you
+ − 676 must actually use a tab (preceded with a backslash). But it's rare to
+ − 677 do such a thing.
+ − 678
+ − 679 @cindex CL note---case of letters
+ − 680 @quotation
+ − 681 @b{Common Lisp note:} In Common Lisp, lower case letters are always
+ − 682 ``folded'' to upper case, unless they are explicitly escaped. In Emacs
+ − 683 Lisp, upper case and lower case letters are distinct.
+ − 684 @end quotation
+ − 685
+ − 686 Here are several examples of symbol names. Note that the @samp{+} in
+ − 687 the fifth example is escaped to prevent it from being read as a number.
+ − 688 This is not necessary in the sixth example because the rest of the name
+ − 689 makes it invalid as a number.
+ − 690
+ − 691 @example
+ − 692 @group
+ − 693 foo ; @r{A symbol named @samp{foo}.}
+ − 694 FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
+ − 695 char-to-string ; @r{A symbol named @samp{char-to-string}.}
+ − 696 @end group
+ − 697 @group
+ − 698 1+ ; @r{A symbol named @samp{1+}}
+ − 699 ; @r{(not @samp{+1}, which is an integer).}
+ − 700 @end group
+ − 701 @group
+ − 702 \+1 ; @r{A symbol named @samp{+1}}
+ − 703 ; @r{(not a very readable name).}
+ − 704 @end group
+ − 705 @group
+ − 706 \(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
+ − 707 @c the @'s in this next line use up three characters, hence the
+ − 708 @c apparent misalignment of the comment.
+ − 709 +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
+ − 710 ; @r{These characters need not be escaped.}
+ − 711 @end group
+ − 712 @end example
+ − 713
+ − 714 @node Sequence Type
+ − 715 @subsection Sequence Types
+ − 716
+ − 717 A @dfn{sequence} is a Lisp object that represents an ordered set of
+ − 718 elements. There are two kinds of sequence in XEmacs Lisp, lists and
+ − 719 arrays. Thus, an object of type list or of type array is also
+ − 720 considered a sequence.
+ − 721
+ − 722 Arrays are further subdivided into strings, vectors, and bit vectors.
+ − 723 Vectors can hold elements of any type, but string elements must be
+ − 724 characters, and bit vector elements must be either 0 or 1. However, the
+ − 725 characters in a string can have extents (@pxref{Extents}) and text
+ − 726 properties (@pxref{Text Properties}) like characters in a buffer;
+ − 727 vectors do not support extents or text properties even when their
+ − 728 elements happen to be characters.
+ − 729
+ − 730 Lists, strings, vectors, and bit vectors are different, but they have
+ − 731 important similarities. For example, all have a length @var{l}, and all
+ − 732 have elements which can be indexed from zero to @var{l} minus one.
+ − 733 Also, several functions, called sequence functions, accept any kind of
+ − 734 sequence. For example, the function @code{elt} can be used to extract
+ − 735 an element of a sequence, given its index. @xref{Sequences Arrays
+ − 736 Vectors}.
+ − 737
+ − 738 It is impossible to read the same sequence twice, since sequences are
+ − 739 always created anew upon reading. If you read the read syntax for a
+ − 740 sequence twice, you get two sequences with equal contents. There is one
+ − 741 exception: the empty list @code{()} always stands for the same object,
+ − 742 @code{nil}.
+ − 743
+ − 744 @node Cons Cell Type
+ − 745 @subsection Cons Cell and List Types
+ − 746 @cindex address field of register
+ − 747 @cindex decrement field of register
+ − 748
+ − 749 A @dfn{cons cell} is an object comprising two pointers named the
+ − 750 @sc{car} and the @sc{cdr}. Each of them can point to any Lisp object.
+ − 751
+ − 752 A @dfn{list} is a series of cons cells, linked together so that the
+ − 753 @sc{cdr} of each cons cell points either to another cons cell or to the
+ − 754 empty list. @xref{Lists}, for functions that work on lists. Because
+ − 755 most cons cells are used as part of lists, the phrase @dfn{list
+ − 756 structure} has come to refer to any structure made out of cons cells.
+ − 757
+ − 758 The names @sc{car} and @sc{cdr} have only historical meaning now. The
+ − 759 original Lisp implementation ran on an @w{IBM 704} computer which
+ − 760 divided words into two parts, called the ``address'' part and the
+ − 761 ``decrement''; @sc{car} was an instruction to extract the contents of
+ − 762 the address part of a register, and @sc{cdr} an instruction to extract
+ − 763 the contents of the decrement. By contrast, ``cons cells'' are named
+ − 764 for the function @code{cons} that creates them, which in turn is named
+ − 765 for its purpose, the construction of cells.
+ − 766
+ − 767 @cindex atom
+ − 768 Because cons cells are so central to Lisp, we also have a word for
+ − 769 ``an object which is not a cons cell''. These objects are called
+ − 770 @dfn{atoms}.
+ − 771
+ − 772 @cindex parenthesis
+ − 773 The read syntax and printed representation for lists are identical, and
+ − 774 consist of a left parenthesis, an arbitrary number of elements, and a
+ − 775 right parenthesis.
+ − 776
+ − 777 Upon reading, each object inside the parentheses becomes an element
+ − 778 of the list. That is, a cons cell is made for each element. The
+ − 779 @sc{car} of the cons cell points to the element, and its @sc{cdr} points
+ − 780 to the next cons cell of the list, which holds the next element in the
+ − 781 list. The @sc{cdr} of the last cons cell is set to point to @code{nil}.
+ − 782
+ − 783 @cindex box diagrams, for lists
+ − 784 @cindex diagrams, boxed, for lists
+ − 785 A list can be illustrated by a diagram in which the cons cells are
+ − 786 shown as pairs of boxes. (The Lisp reader cannot read such an
+ − 787 illustration; unlike the textual notation, which can be understood by
+ − 788 both humans and computers, the box illustrations can be understood only
+ − 789 by humans.) The following represents the three-element list @code{(rose
+ − 790 violet buttercup)}:
+ − 791
+ − 792 @example
+ − 793 @group
+ − 794 ___ ___ ___ ___ ___ ___
+ − 795 |___|___|--> |___|___|--> |___|___|--> nil
+ − 796 | | |
+ − 797 | | |
+ − 798 --> rose --> violet --> buttercup
+ − 799 @end group
+ − 800 @end example
+ − 801
+ − 802 In this diagram, each box represents a slot that can refer to any Lisp
+ − 803 object. Each pair of boxes represents a cons cell. Each arrow is a
+ − 804 reference to a Lisp object, either an atom or another cons cell.
+ − 805
+ − 806 In this example, the first box, the @sc{car} of the first cons cell,
+ − 807 refers to or ``contains'' @code{rose} (a symbol). The second box, the
+ − 808 @sc{cdr} of the first cons cell, refers to the next pair of boxes, the
+ − 809 second cons cell. The @sc{car} of the second cons cell refers to
+ − 810 @code{violet} and the @sc{cdr} refers to the third cons cell. The
+ − 811 @sc{cdr} of the third (and last) cons cell refers to @code{nil}.
+ − 812
+ − 813 Here is another diagram of the same list, @code{(rose violet
+ − 814 buttercup)}, sketched in a different manner:
+ − 815
+ − 816 @smallexample
+ − 817 @group
+ − 818 --------------- ---------------- -------------------
+ − 819 | car | cdr | | car | cdr | | car | cdr |
+ − 820 | rose | o-------->| violet | o-------->| buttercup | nil |
+ − 821 | | | | | | | | |
+ − 822 --------------- ---------------- -------------------
+ − 823 @end group
+ − 824 @end smallexample
+ − 825
+ − 826 @cindex @samp{(@dots{})} in lists
+ − 827 @cindex @code{nil} in lists
+ − 828 @cindex empty list
+ − 829 A list with no elements in it is the @dfn{empty list}; it is identical
+ − 830 to the symbol @code{nil}. In other words, @code{nil} is both a symbol
+ − 831 and a list.
+ − 832
+ − 833 Here are examples of lists written in Lisp syntax:
+ − 834
+ − 835 @example
+ − 836 (A 2 "A") ; @r{A list of three elements.}
+ − 837 () ; @r{A list of no elements (the empty list).}
+ − 838 nil ; @r{A list of no elements (the empty list).}
+ − 839 ("A ()") ; @r{A list of one element: the string @code{"A ()"}.}
+ − 840 (A ()) ; @r{A list of two elements: @code{A} and the empty list.}
+ − 841 (A nil) ; @r{Equivalent to the previous.}
+ − 842 ((A B C)) ; @r{A list of one element}
+ − 843 ; @r{(which is a list of three elements).}
+ − 844 @end example
+ − 845
+ − 846 Here is the list @code{(A ())}, or equivalently @code{(A nil)},
+ − 847 depicted with boxes and arrows:
+ − 848
+ − 849 @example
+ − 850 @group
+ − 851 ___ ___ ___ ___
+ − 852 |___|___|--> |___|___|--> nil
+ − 853 | |
+ − 854 | |
+ − 855 --> A --> nil
+ − 856 @end group
+ − 857 @end example
+ − 858
+ − 859 @menu
+ − 860 * Dotted Pair Notation:: An alternative syntax for lists.
+ − 861 * Association List Type:: A specially constructed list.
+ − 862 @end menu
+ − 863
+ − 864 @node Dotted Pair Notation
+ − 865 @subsubsection Dotted Pair Notation
+ − 866 @cindex dotted pair notation
+ − 867 @cindex @samp{.} in lists
+ − 868
+ − 869 @dfn{Dotted pair notation} is an alternative syntax for cons cells
+ − 870 that represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
+ − 871 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
+ − 872 the object @var{a}, and whose @sc{cdr} is the object @var{b}. Dotted
+ − 873 pair notation is therefore more general than list syntax. In the dotted
+ − 874 pair notation, the list @samp{(1 2 3)} is written as @samp{(1 . (2 . (3
+ − 875 . nil)))}. For @code{nil}-terminated lists, the two notations produce
+ − 876 the same result, but list notation is usually clearer and more
+ − 877 convenient when it is applicable. When printing a list, the dotted pair
+ − 878 notation is only used if the @sc{cdr} of a cell is not a list.
+ − 879
+ − 880 Here's how box notation can illustrate dotted pairs. This example
+ − 881 shows the pair @code{(rose . violet)}:
+ − 882
+ − 883 @example
+ − 884 @group
+ − 885 ___ ___
+ − 886 |___|___|--> violet
+ − 887 |
+ − 888 |
+ − 889 --> rose
+ − 890 @end group
+ − 891 @end example
+ − 892
+ − 893 Dotted pair notation can be combined with list notation to represent a
+ − 894 chain of cons cells with a non-@code{nil} final @sc{cdr}. For example,
+ − 895 @code{(rose violet . buttercup)} is equivalent to @code{(rose . (violet
+ − 896 . buttercup))}. The object looks like this:
+ − 897
+ − 898 @example
+ − 899 @group
+ − 900 ___ ___ ___ ___
+ − 901 |___|___|--> |___|___|--> buttercup
+ − 902 | |
+ − 903 | |
+ − 904 --> rose --> violet
+ − 905 @end group
+ − 906 @end example
+ − 907
+ − 908 These diagrams make it evident why @w{@code{(rose .@: violet .@:
+ − 909 buttercup)}} is invalid syntax; it would require a cons cell that has
+ − 910 three parts rather than two.
+ − 911
+ − 912 The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}
+ − 913 and looks like this:
+ − 914
+ − 915 @example
+ − 916 @group
+ − 917 ___ ___ ___ ___
+ − 918 |___|___|--> |___|___|--> nil
+ − 919 | |
+ − 920 | |
+ − 921 --> rose --> violet
+ − 922 @end group
+ − 923 @end example
+ − 924
+ − 925 Similarly, the three-element list @code{(rose violet buttercup)}
+ − 926 is equivalent to @code{(rose . (violet . (buttercup)))}.
+ − 927 @ifinfo
+ − 928 It looks like this:
+ − 929
+ − 930 @example
+ − 931 @group
+ − 932 ___ ___ ___ ___ ___ ___
+ − 933 |___|___|--> |___|___|--> |___|___|--> nil
+ − 934 | | |
+ − 935 | | |
+ − 936 --> rose --> violet --> buttercup
+ − 937 @end group
+ − 938 @end example
+ − 939 @end ifinfo
+ − 940
+ − 941 @node Association List Type
+ − 942 @subsubsection Association List Type
+ − 943
+ − 944 An @dfn{association list} or @dfn{alist} is a specially-constructed
+ − 945 list whose elements are cons cells. In each element, the @sc{car} is
+ − 946 considered a @dfn{key}, and the @sc{cdr} is considered an
+ − 947 @dfn{associated value}. (In some cases, the associated value is stored
+ − 948 in the @sc{car} of the @sc{cdr}.) Association lists are often used as
+ − 949 stacks, since it is easy to add or remove associations at the front of
+ − 950 the list.
+ − 951
+ − 952 For example,
+ − 953
+ − 954 @example
+ − 955 (setq alist-of-colors
+ − 956 '((rose . red) (lily . white) (buttercup . yellow)))
+ − 957 @end example
+ − 958
+ − 959 @noindent
+ − 960 sets the variable @code{alist-of-colors} to an alist of three elements. In the
+ − 961 first element, @code{rose} is the key and @code{red} is the value.
+ − 962
+ − 963 @xref{Association Lists}, for a further explanation of alists and for
+ − 964 functions that work on alists.
+ − 965
+ − 966 @node Array Type
+ − 967 @subsection Array Type
+ − 968
+ − 969 An @dfn{array} is composed of an arbitrary number of slots for
+ − 970 referring to other Lisp objects, arranged in a contiguous block of
+ − 971 memory. Accessing any element of an array takes the same amount of
+ − 972 time. In contrast, accessing an element of a list requires time
+ − 973 proportional to the position of the element in the list. (Elements at
+ − 974 the end of a list take longer to access than elements at the beginning
+ − 975 of a list.)
+ − 976
+ − 977 XEmacs defines three types of array, strings, vectors, and bit
+ − 978 vectors. A string is an array of characters, a vector is an array of
+ − 979 arbitrary objects, and a bit vector is an array of 1's and 0's. All are
+ − 980 one-dimensional. (Most other programming languages support
+ − 981 multidimensional arrays, but they are not essential; you can get the
+ − 982 same effect with an array of arrays.) Each type of array has its own
+ − 983 read syntax; see @ref{String Type}, @ref{Vector Type}, and @ref{Bit
+ − 984 Vector Type}.
+ − 985
+ − 986 An array may have any length up to the largest integer; but once
+ − 987 created, it has a fixed size. The first element of an array has index
+ − 988 zero, the second element has index 1, and so on. This is called
+ − 989 @dfn{zero-origin} indexing. For example, an array of four elements has
+ − 990 indices 0, 1, 2, @w{and 3}.
+ − 991
+ − 992 The array type is contained in the sequence type and contains the
+ − 993 string type, the vector type, and the bit vector type.
+ − 994
+ − 995 @node String Type
+ − 996 @subsection String Type
+ − 997
+ − 998 A @dfn{string} is an array of characters. Strings are used for many
+ − 999 purposes in XEmacs, as can be expected in a text editor; for example, as
+ − 1000 the names of Lisp symbols, as messages for the user, and to represent
+ − 1001 text extracted from buffers. Strings in Lisp are constants: evaluation
+ − 1002 of a string returns the same string.
+ − 1003
+ − 1004 @cindex @samp{"} in strings
+ − 1005 @cindex double-quote in strings
+ − 1006 @cindex @samp{\} in strings
+ − 1007 @cindex backslash in strings
+ − 1008 The read syntax for strings is a double-quote, an arbitrary number of
+ − 1009 characters, and another double-quote, @code{"like this"}. The Lisp
+ − 1010 reader accepts the same formats for reading the characters of a string
+ − 1011 as it does for reading single characters (without the question mark that
+ − 1012 begins a character literal). You can enter a nonprinting character such
+ − 1013 as tab or @kbd{C-a} using the convenient escape sequences, like this:
+ − 1014 @code{"\t, \C-a"}. You can include a double-quote in a string by
+ − 1015 preceding it with a backslash; thus, @code{"\""} is a string containing
+ − 1016 just a single double-quote character. (@xref{Character Type}, for a
+ − 1017 description of the read syntax for characters.)
+ − 1018
+ − 1019 @ignore @c More ill-conceived FSF Emacs crap.
+ − 1020 If you use the @samp{\M-} syntax to indicate a meta character in a
+ − 1021 string constant, this sets the
+ − 1022 @iftex
+ − 1023 $2^{7}$
+ − 1024 @end iftex
+ − 1025 @ifinfo
+ − 1026 2**7
+ − 1027 @end ifinfo
+ − 1028 bit of the character in the string.
+ − 1029 This is not the same representation that the meta modifier has in a
+ − 1030 character on its own (not inside a string). @xref{Character Type}.
+ − 1031
+ − 1032 Strings cannot hold characters that have the hyper, super, or alt
+ − 1033 modifiers; they can hold @sc{ASCII} control characters, but no others.
+ − 1034 They do not distinguish case in @sc{ASCII} control characters.
+ − 1035 @end ignore
+ − 1036
+ − 1037 The printed representation of a string consists of a double-quote, the
+ − 1038 characters it contains, and another double-quote. However, you must
+ − 1039 escape any backslash or double-quote characters in the string with a
+ − 1040 backslash, like this: @code{"this \" is an embedded quote"}.
+ − 1041
+ − 1042 The newline character is not special in the read syntax for strings;
+ − 1043 if you write a new line between the double-quotes, it becomes a
+ − 1044 character in the string. But an escaped newline---one that is preceded
+ − 1045 by @samp{\}---does not become part of the string; i.e., the Lisp reader
+ − 1046 ignores an escaped newline while reading a string.
+ − 1047 @cindex newline in strings
+ − 1048
+ − 1049 @example
+ − 1050 "It is useful to include newlines
+ − 1051 in documentation strings,
+ − 1052 but the newline is \
+ − 1053 ignored if escaped."
+ − 1054 @result{} "It is useful to include newlines
+ − 1055 in documentation strings,
+ − 1056 but the newline is ignored if escaped."
+ − 1057 @end example
+ − 1058
+ − 1059 A string can hold extents and properties of the text it contains, in
+ − 1060 addition to the characters themselves. This enables programs that copy
+ − 1061 text between strings and buffers to preserve the extents and properties
+ − 1062 with no special effort. @xref{Extents}, @xref{Text Properties}.
+ − 1063
+ − 1064 Note that FSF GNU Emacs has a special read and print syntax for
+ − 1065 strings with text properties, but XEmacs does not currently implement
+ − 1066 this. It was judged better not to include this in XEmacs because it
+ − 1067 entails that @code{equal} return @code{nil} when passed a string with
+ − 1068 text properties and the equivalent string without text properties, which
+ − 1069 is often counter-intuitive.
+ − 1070
+ − 1071 @ignore @c Not in XEmacs
+ − 1072 Strings with text
+ − 1073 properties have a special read and print syntax:
+ − 1074
+ − 1075 @example
+ − 1076 #("@var{characters}" @var{property-data}...)
+ − 1077 @end example
+ − 1078
+ − 1079 @noindent
+ − 1080 where @var{property-data} consists of zero or more elements, in groups
+ − 1081 of three as follows:
+ − 1082
+ − 1083 @example
444
+ − 1084 @var{start} @var{end} @var{plist}
428
+ − 1085 @end example
+ − 1086
+ − 1087 @noindent
444
+ − 1088 The elements @var{start} and @var{end} are integers, and together specify
428
+ − 1089 a range of indices in the string; @var{plist} is the property list for
+ − 1090 that range.
+ − 1091 @end ignore
+ − 1092
+ − 1093 @xref{Strings and Characters}, for functions that work on strings.
+ − 1094
+ − 1095 @node Vector Type
+ − 1096 @subsection Vector Type
+ − 1097
+ − 1098 A @dfn{vector} is a one-dimensional array of elements of any type. It
+ − 1099 takes a constant amount of time to access any element of a vector. (In
+ − 1100 a list, the access time of an element is proportional to the distance of
+ − 1101 the element from the beginning of the list.)
+ − 1102
+ − 1103 The printed representation of a vector consists of a left square
+ − 1104 bracket, the elements, and a right square bracket. This is also the
+ − 1105 read syntax. Like numbers and strings, vectors are considered constants
+ − 1106 for evaluation.
+ − 1107
+ − 1108 @example
+ − 1109 [1 "two" (three)] ; @r{A vector of three elements.}
+ − 1110 @result{} [1 "two" (three)]
+ − 1111 @end example
+ − 1112
+ − 1113 @xref{Vectors}, for functions that work with vectors.
+ − 1114
+ − 1115 @node Bit Vector Type
+ − 1116 @subsection Bit Vector Type
+ − 1117
+ − 1118 A @dfn{bit vector} is a one-dimensional array of 1's and 0's. It
+ − 1119 takes a constant amount of time to access any element of a bit vector,
+ − 1120 as for vectors. Bit vectors have an extremely compact internal
+ − 1121 representation (one machine bit per element), which makes them ideal
+ − 1122 for keeping track of unordered sets, large collections of boolean values,
+ − 1123 etc.
+ − 1124
+ − 1125 The printed representation of a bit vector consists of @samp{#*}
+ − 1126 followed by the bits in the vector. This is also the read syntax. Like
+ − 1127 numbers, strings, and vectors, bit vectors are considered constants for
+ − 1128 evaluation.
+ − 1129
+ − 1130 @example
+ − 1131 #*00101000 ; @r{A bit vector of eight elements.}
+ − 1132 @result{} #*00101000
+ − 1133 @end example
+ − 1134
+ − 1135 @xref{Bit Vectors}, for functions that work with bit vectors.
+ − 1136
+ − 1137 @node Function Type
+ − 1138 @subsection Function Type
+ − 1139
+ − 1140 Just as functions in other programming languages are executable,
+ − 1141 @dfn{Lisp function} objects are pieces of executable code. However,
+ − 1142 functions in Lisp are primarily Lisp objects, and only secondarily the
+ − 1143 text which represents them. These Lisp objects are lambda expressions:
+ − 1144 lists whose first element is the symbol @code{lambda} (@pxref{Lambda
+ − 1145 Expressions}).
+ − 1146
+ − 1147 In most programming languages, it is impossible to have a function
+ − 1148 without a name. In Lisp, a function has no intrinsic name. A lambda
+ − 1149 expression is also called an @dfn{anonymous function} (@pxref{Anonymous
+ − 1150 Functions}). A named function in Lisp is actually a symbol with a valid
+ − 1151 function in its function cell (@pxref{Defining Functions}).
+ − 1152
+ − 1153 Most of the time, functions are called when their names are written in
+ − 1154 Lisp expressions in Lisp programs. However, you can construct or obtain
+ − 1155 a function object at run time and then call it with the primitive
+ − 1156 functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
+ − 1157
+ − 1158 @node Macro Type
+ − 1159 @subsection Macro Type
+ − 1160
+ − 1161 A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
+ − 1162 language. It is represented as an object much like a function, but with
+ − 1163 different parameter-passing semantics. A Lisp macro has the form of a
+ − 1164 list whose first element is the symbol @code{macro} and whose @sc{cdr}
+ − 1165 is a Lisp function object, including the @code{lambda} symbol.
+ − 1166
+ − 1167 Lisp macro objects are usually defined with the built-in
+ − 1168 @code{defmacro} function, but any list that begins with @code{macro} is
+ − 1169 a macro as far as XEmacs is concerned. @xref{Macros}, for an explanation
+ − 1170 of how to write a macro.
+ − 1171
+ − 1172 @node Primitive Function Type
+ − 1173 @subsection Primitive Function Type
+ − 1174 @cindex special forms
+ − 1175
+ − 1176 A @dfn{primitive function} is a function callable from Lisp but
+ − 1177 written in the C programming language. Primitive functions are also
+ − 1178 called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
+ − 1179 derived from ``subroutine''.) Most primitive functions evaluate all
+ − 1180 their arguments when they are called. A primitive function that does
+ − 1181 not evaluate all its arguments is called a @dfn{special form}
+ − 1182 (@pxref{Special Forms}).@refill
+ − 1183
+ − 1184 It does not matter to the caller of a function whether the function is
+ − 1185 primitive. However, this does matter if you try to substitute a
+ − 1186 function written in Lisp for a primitive of the same name. The reason
+ − 1187 is that the primitive function may be called directly from C code.
+ − 1188 Calls to the redefined function from Lisp will use the new definition,
+ − 1189 but calls from C code may still use the built-in definition.
+ − 1190
+ − 1191 The term @dfn{function} refers to all Emacs functions, whether written
+ − 1192 in Lisp or C. @xref{Function Type}, for information about the
+ − 1193 functions written in Lisp.
+ − 1194
+ − 1195 Primitive functions have no read syntax and print in hash notation
+ − 1196 with the name of the subroutine.
+ − 1197
+ − 1198 @example
+ − 1199 @group
+ − 1200 (symbol-function 'car) ; @r{Access the function cell}
+ − 1201 ; @r{of the symbol.}
+ − 1202 @result{} #<subr car>
+ − 1203 (subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
+ − 1204 @result{} t ; @r{Yes.}
+ − 1205 @end group
+ − 1206 @end example
+ − 1207
+ − 1208 @node Compiled-Function Type
+ − 1209 @subsection Compiled-Function Type
+ − 1210
+ − 1211 The byte compiler produces @dfn{compiled-function objects}. The
+ − 1212 evaluator handles this data type specially when it appears as a function
+ − 1213 to be called. @xref{Byte Compilation}, for information about the byte
+ − 1214 compiler.
+ − 1215
+ − 1216 The printed representation for a compiled-function object is normally
+ − 1217 @samp{#<compiled-function...>}. If @code{print-readably} is true,
+ − 1218 however, it is @samp{#[...]}.
+ − 1219
+ − 1220 @node Autoload Type
+ − 1221 @subsection Autoload Type
+ − 1222
+ − 1223 An @dfn{autoload object} is a list whose first element is the symbol
+ − 1224 @code{autoload}. It is stored as the function definition of a symbol as
+ − 1225 a placeholder for the real definition; it says that the real definition
+ − 1226 is found in a file of Lisp code that should be loaded when necessary.
+ − 1227 The autoload object contains the name of the file, plus some other
+ − 1228 information about the real definition.
+ − 1229
+ − 1230 After the file has been loaded, the symbol should have a new function
+ − 1231 definition that is not an autoload object. The new definition is then
+ − 1232 called as if it had been there to begin with. From the user's point of
+ − 1233 view, the function call works as expected, using the function definition
+ − 1234 in the loaded file.
+ − 1235
+ − 1236 An autoload object is usually created with the function
+ − 1237 @code{autoload}, which stores the object in the function cell of a
+ − 1238 symbol. @xref{Autoload}, for more details.
+ − 1239
+ − 1240 @node Char Table Type
+ − 1241 @subsection Char Table Type
+ − 1242 @cindex char table type
+ − 1243
+ − 1244 (not yet documented)
+ − 1245
+ − 1246 @node Hash Table Type
+ − 1247 @subsection Hash Table Type
+ − 1248 @cindex hash table type
+ − 1249
+ − 1250 A @dfn{hash table} is a table providing an arbitrary mapping from
+ − 1251 one Lisp object to another, using an internal indexing method
+ − 1252 called @dfn{hashing}. Hash tables are very fast (much more efficient
+ − 1253 that using an association list, when there are a large number of
+ − 1254 elements in the table).
+ − 1255
+ − 1256 Hash tables have a special read syntax beginning with
+ − 1257 @samp{#s(hash-table} (this is an example of @dfn{structure} read
+ − 1258 syntax. This notation is also used for printing when
+ − 1259 @code{print-readably} is @code{t}.
+ − 1260
+ − 1261 Otherwise they print in hash notation (The ``hash'' in ``hash notation''
+ − 1262 has nothing to do with the ``hash'' in ``hash table''), giving the
+ − 1263 number of elements, total space allocated for elements, and a unique
+ − 1264 number assigned at the time the hash table was created. (Hash tables
+ − 1265 automatically resize as necessary so there is no danger of running out
+ − 1266 of space for elements.)
+ − 1267
+ − 1268 @example
+ − 1269 @group
+ − 1270 (make-hash-table :size 50)
+ − 1271 @result{} #<hash-table 0/107 0x313a>
+ − 1272 @end group
+ − 1273 @end example
+ − 1274
+ − 1275 @xref{Hash Tables}, for information on how to create and work with hash
+ − 1276 tables.
+ − 1277
+ − 1278 @node Range Table Type
+ − 1279 @subsection Range Table Type
+ − 1280 @cindex range table type
+ − 1281
+ − 1282 A @dfn{range table} is a table that maps from ranges of integers to
+ − 1283 arbitrary Lisp objects. Range tables automatically combine overlapping
+ − 1284 ranges that map to the same Lisp object, and operations are provided
+ − 1285 for mapping over all of the ranges in a range table.
+ − 1286
+ − 1287 Range tables have a special read syntax beginning with
+ − 1288 @samp{#s(range-table} (this is an example of @dfn{structure} read syntax,
+ − 1289 which is also used for char tables and faces).
+ − 1290
+ − 1291 @example
+ − 1292 @group
+ − 1293 (setq x (make-range-table))
+ − 1294 (put-range-table 20 50 'foo x)
+ − 1295 (put-range-table 100 200 "bar" x)
+ − 1296 x
+ − 1297 @result{} #s(range-table data ((20 50) foo (100 200) "bar"))
+ − 1298 @end group
+ − 1299 @end example
+ − 1300
+ − 1301 @xref{Range Tables}, for information on how to create and work with range
+ − 1302 tables.
+ − 1303
+ − 1304 @node Weak List Type
+ − 1305 @subsection Weak List Type
+ − 1306 @cindex weak list type
+ − 1307
+ − 1308 (not yet documented)
+ − 1309
+ − 1310 @node Editing Types
+ − 1311 @section Editing Types
+ − 1312 @cindex editing types
+ − 1313
+ − 1314 The types in the previous section are common to many Lisp dialects.
+ − 1315 XEmacs Lisp provides several additional data types for purposes connected
+ − 1316 with editing.
+ − 1317
+ − 1318 @menu
+ − 1319 * Buffer Type:: The basic object of editing.
+ − 1320 * Marker Type:: A position in a buffer.
+ − 1321 * Extent Type:: A range in a buffer or string, maybe with properties.
+ − 1322 * Window Type:: Buffers are displayed in windows.
+ − 1323 * Frame Type:: Windows subdivide frames.
+ − 1324 * Device Type:: Devices group all frames on a display.
+ − 1325 * Console Type:: Consoles group all devices with the same keyboard.
+ − 1326 * Window Configuration Type:: Recording the way a frame is subdivided.
+ − 1327 * Event Type:: An interesting occurrence in the system.
+ − 1328 * Process Type:: A process running on the underlying OS.
+ − 1329 * Stream Type:: Receive or send characters.
+ − 1330 * Keymap Type:: What function a keystroke invokes.
+ − 1331 * Syntax Table Type:: What a character means.
+ − 1332 * Display Table Type:: How display tables are represented.
+ − 1333 * Database Type:: A connection to an external DBM or DB database.
+ − 1334 * Charset Type:: A character set (e.g. all Kanji characters),
+ − 1335 under XEmacs/MULE.
+ − 1336 * Coding System Type:: An object encapsulating a way of converting between
+ − 1337 different textual encodings, under XEmacs/MULE.
+ − 1338 * ToolTalk Message Type:: A message, in the ToolTalk IPC protocol.
+ − 1339 * ToolTalk Pattern Type:: A pattern, in the ToolTalk IPC protocol.
+ − 1340 @end menu
+ − 1341
+ − 1342 @node Buffer Type
+ − 1343 @subsection Buffer Type
+ − 1344
+ − 1345 A @dfn{buffer} is an object that holds text that can be edited
+ − 1346 (@pxref{Buffers}). Most buffers hold the contents of a disk file
+ − 1347 (@pxref{Files}) so they can be edited, but some are used for other
+ − 1348 purposes. Most buffers are also meant to be seen by the user, and
+ − 1349 therefore displayed, at some time, in a window (@pxref{Windows}). But a
+ − 1350 buffer need not be displayed in any window.
+ − 1351
+ − 1352 The contents of a buffer are much like a string, but buffers are not
+ − 1353 used like strings in XEmacs Lisp, and the available operations are
+ − 1354 different. For example, insertion of text into a buffer is very
+ − 1355 efficient, whereas ``inserting'' text into a string requires
+ − 1356 concatenating substrings, and the result is an entirely new string
+ − 1357 object.
+ − 1358
+ − 1359 Each buffer has a designated position called @dfn{point}
+ − 1360 (@pxref{Positions}). At any time, one buffer is the @dfn{current
+ − 1361 buffer}. Most editing commands act on the contents of the current
+ − 1362 buffer in the neighborhood of point. Many of the standard Emacs
+ − 1363 functions manipulate or test the characters in the current buffer; a
+ − 1364 whole chapter in this manual is devoted to describing these functions
+ − 1365 (@pxref{Text}).
+ − 1366
+ − 1367 Several other data structures are associated with each buffer:
+ − 1368
+ − 1369 @itemize @bullet
+ − 1370 @item
+ − 1371 a local syntax table (@pxref{Syntax Tables});
+ − 1372
+ − 1373 @item
+ − 1374 a local keymap (@pxref{Keymaps});
+ − 1375
+ − 1376 @item
+ − 1377 a local variable binding list (@pxref{Buffer-Local Variables});
+ − 1378
+ − 1379 @item
+ − 1380 a list of extents (@pxref{Extents});
+ − 1381
+ − 1382 @item
+ − 1383 and various other related properties.
+ − 1384 @end itemize
+ − 1385
+ − 1386 @noindent
+ − 1387 The local keymap and variable list contain entries that individually
+ − 1388 override global bindings or values. These are used to customize the
+ − 1389 behavior of programs in different buffers, without actually changing the
+ − 1390 programs.
+ − 1391
+ − 1392 A buffer may be @dfn{indirect}, which means it shares the text
+ − 1393 of another buffer. @xref{Indirect Buffers}.
+ − 1394
+ − 1395 Buffers have no read syntax. They print in hash notation, showing the
+ − 1396 buffer name.
+ − 1397
+ − 1398 @example
+ − 1399 @group
+ − 1400 (current-buffer)
+ − 1401 @result{} #<buffer "objects.texi">
+ − 1402 @end group
+ − 1403 @end example
+ − 1404
+ − 1405 @node Marker Type
+ − 1406 @subsection Marker Type
+ − 1407
+ − 1408 A @dfn{marker} denotes a position in a specific buffer. Markers
+ − 1409 therefore have two components: one for the buffer, and one for the
+ − 1410 position. Changes in the buffer's text automatically relocate the
+ − 1411 position value as necessary to ensure that the marker always points
+ − 1412 between the same two characters in the buffer.
+ − 1413
+ − 1414 Markers have no read syntax. They print in hash notation, giving the
+ − 1415 current character position and the name of the buffer.
+ − 1416
+ − 1417 @example
+ − 1418 @group
+ − 1419 (point-marker)
+ − 1420 @result{} #<marker at 50661 in objects.texi>
+ − 1421 @end group
+ − 1422 @end example
+ − 1423
+ − 1424 @xref{Markers}, for information on how to test, create, copy, and move
+ − 1425 markers.
+ − 1426
+ − 1427 @node Extent Type
+ − 1428 @subsection Extent Type
+ − 1429
+ − 1430 An @dfn{extent} specifies temporary alteration of the display
+ − 1431 appearance of a part of a buffer (or string). It contains markers
+ − 1432 delimiting a range of the buffer, plus a property list (a list whose
+ − 1433 elements are alternating property names and values). Extents are used
+ − 1434 to present parts of the buffer temporarily in a different display style.
+ − 1435 They have no read syntax, and print in hash notation, giving the buffer
+ − 1436 name and range of positions.
+ − 1437
+ − 1438 Extents can exist over strings as well as buffers; the primary use
+ − 1439 of this is to preserve extent and text property information as text
+ − 1440 is copied from one buffer to another or between different parts of
+ − 1441 a buffer.
+ − 1442
+ − 1443 Extents have no read syntax. They print in hash notation, giving the
+ − 1444 range of text they cover, the name of the buffer or string they are in,
+ − 1445 the address in core, and a summary of some of the properties attached to
+ − 1446 the extent.
+ − 1447
+ − 1448 @example
+ − 1449 @group
+ − 1450 (extent-at (point))
+ − 1451 @result{} #<extent [51742, 51748) font-lock text-prop 0x90121e0 in buffer objects.texi>
+ − 1452 @end group
+ − 1453 @end example
+ − 1454
+ − 1455 @xref{Extents}, for how to create and use extents.
+ − 1456
+ − 1457 Extents are used to implement text properties. @xref{Text Properties}.
+ − 1458
+ − 1459 @node Window Type
+ − 1460 @subsection Window Type
+ − 1461
+ − 1462 A @dfn{window} describes the portion of the frame that XEmacs uses to
+ − 1463 display a buffer. (In standard window-system usage, a @dfn{window} is
+ − 1464 what XEmacs calls a @dfn{frame}; XEmacs confusingly uses the term
+ − 1465 ``window'' to refer to what is called a @dfn{pane} in standard
+ − 1466 window-system usage.) Every window has one associated buffer, whose
+ − 1467 contents appear in the window. By contrast, a given buffer may appear
+ − 1468 in one window, no window, or several windows.
+ − 1469
+ − 1470 Though many windows may exist simultaneously, at any time one window
+ − 1471 is designated the @dfn{selected window}. This is the window where the
+ − 1472 cursor is (usually) displayed when XEmacs is ready for a command. The
+ − 1473 selected window usually displays the current buffer, but this is not
+ − 1474 necessarily the case.
+ − 1475
+ − 1476 Windows are grouped on the screen into frames; each window belongs to
+ − 1477 one and only one frame. @xref{Frame Type}.
+ − 1478
+ − 1479 Windows have no read syntax. They print in hash notation, giving the
+ − 1480 name of the buffer being displayed and a unique number assigned at the
+ − 1481 time the window was created. (This number can be useful because the
+ − 1482 buffer displayed in any given window can change frequently.)
+ − 1483
+ − 1484 @example
+ − 1485 @group
+ − 1486 (selected-window)
+ − 1487 @result{} #<window on "objects.texi" 0x266c>
+ − 1488 @end group
+ − 1489 @end example
+ − 1490
+ − 1491 @xref{Windows}, for a description of the functions that work on windows.
+ − 1492
+ − 1493 @node Frame Type
+ − 1494 @subsection Frame Type
+ − 1495
+ − 1496 A @var{frame} is a rectangle on the screen (a @dfn{window} in standard
+ − 1497 window-system terminology) that contains one or more non-overlapping
+ − 1498 Emacs windows (@dfn{panes} in standard window-system terminology). A
+ − 1499 frame initially contains a single main window (plus perhaps a minibuffer
+ − 1500 window) which you can subdivide vertically or horizontally into smaller
+ − 1501 windows.
+ − 1502
+ − 1503 Frames have no read syntax. They print in hash notation, giving the
+ − 1504 frame's type, name as used for resourcing, and a unique number assigned
+ − 1505 at the time the frame was created.
+ − 1506
+ − 1507 @example
+ − 1508 @group
+ − 1509 (selected-frame)
+ − 1510 @result{} #<x-frame "emacs" 0x9db>
+ − 1511 @end group
+ − 1512 @end example
+ − 1513
+ − 1514 @xref{Frames}, for a description of the functions that work on frames.
+ − 1515
+ − 1516 @node Device Type
+ − 1517 @subsection Device Type
+ − 1518
+ − 1519 A @dfn{device} represents a single display on which frames exist.
+ − 1520 Normally, there is only one device object, but there may be more
+ − 1521 than one if XEmacs is being run on a multi-headed display (e.g. an
+ − 1522 X server with attached color and mono screens) or if XEmacs is
+ − 1523 simultaneously driving frames attached to different consoles, e.g.
+ − 1524 an X display and a @sc{tty} connection.
+ − 1525
+ − 1526 Devices do not have a read syntax. They print in hash notation,
+ − 1527 giving the device's type, connection name, and a unique number assigned
+ − 1528 at the time the device was created.
+ − 1529
+ − 1530 @example
+ − 1531 @group
+ − 1532 (selected-device)
+ − 1533 @result{} #<x-device on ":0.0" 0x5b9>
+ − 1534 @end group
+ − 1535 @end example
+ − 1536
+ − 1537 @xref{Consoles and Devices}, for a description of several functions
+ − 1538 related to devices.
+ − 1539
+ − 1540 @node Console Type
+ − 1541 @subsection Console Type
+ − 1542
+ − 1543 A @dfn{console} represents a single keyboard to which devices
+ − 1544 (i.e. displays on which frames exist) are connected. Normally, there is
+ − 1545 only one console object, but there may be more than one if XEmacs is
+ − 1546 simultaneously driving frames attached to different X servers and/or
+ − 1547 @sc{tty} connections. (XEmacs is capable of driving multiple X and
+ − 1548 @sc{tty} connections at the same time, and provides a robust mechanism
+ − 1549 for handling the differing display capabilities of such heterogeneous
+ − 1550 environments. A buffer with embedded glyphs and multiple fonts and
+ − 1551 colors, for example, will display reasonably if it simultaneously
+ − 1552 appears on a frame on a color X display, a frame on a mono X display,
+ − 1553 and a frame on a @sc{tty} connection.)
+ − 1554
+ − 1555 Consoles do not have a read syntax. They print in hash notation,
+ − 1556 giving the console's type, connection name, and a unique number assigned
+ − 1557 at the time the console was created.
+ − 1558
+ − 1559 @example
+ − 1560 @group
+ − 1561 (selected-console)
+ − 1562 @result{} #<x-console on "localhost:0" 0x5b7>
+ − 1563 @end group
+ − 1564 @end example
+ − 1565
+ − 1566 @xref{Consoles and Devices}, for a description of several functions
+ − 1567 related to consoles.
+ − 1568
+ − 1569 @node Window Configuration Type
+ − 1570 @subsection Window Configuration Type
+ − 1571 @cindex screen layout
+ − 1572
+ − 1573 A @dfn{window configuration} stores information about the positions,
+ − 1574 sizes, and contents of the windows in a frame, so you can recreate the
+ − 1575 same arrangement of windows later.
+ − 1576
+ − 1577 Window configurations do not have a read syntax. They print in hash
+ − 1578 notation, giving a unique number assigned at the time the window
+ − 1579 configuration was created.
+ − 1580
+ − 1581 @example
+ − 1582 @group
+ − 1583 (current-window-configuration)
+ − 1584 @result{} #<window-configuration 0x2db4>
+ − 1585 @end group
+ − 1586 @end example
+ − 1587
+ − 1588 @xref{Window Configurations}, for a description of several functions
+ − 1589 related to window configurations.
+ − 1590
+ − 1591 @node Event Type
+ − 1592 @subsection Event Type
+ − 1593
+ − 1594 (not yet documented)
+ − 1595
+ − 1596 @node Process Type
+ − 1597 @subsection Process Type
+ − 1598
+ − 1599 The word @dfn{process} usually means a running program. XEmacs itself
+ − 1600 runs in a process of this sort. However, in XEmacs Lisp, a process is a
+ − 1601 Lisp object that designates a subprocess created by the XEmacs process.
+ − 1602 Programs such as shells, GDB, ftp, and compilers, running in
+ − 1603 subprocesses of XEmacs, extend the capabilities of XEmacs.
+ − 1604
+ − 1605 An Emacs subprocess takes textual input from Emacs and returns textual
+ − 1606 output to Emacs for further manipulation. Emacs can also send signals
+ − 1607 to the subprocess.
+ − 1608
+ − 1609 Process objects have no read syntax. They print in hash notation,
+ − 1610 giving the name of the process, its associated process ID, and the
+ − 1611 current state of the process:
+ − 1612
+ − 1613 @example
+ − 1614 @group
+ − 1615 (process-list)
+ − 1616 @result{} (#<process "shell" pid 2909 state:run>)
+ − 1617 @end group
+ − 1618 @end example
+ − 1619
+ − 1620 @xref{Processes}, for information about functions that create, delete,
+ − 1621 return information about, send input or signals to, and receive output
+ − 1622 from processes.
+ − 1623
+ − 1624 @node Stream Type
+ − 1625 @subsection Stream Type
+ − 1626
+ − 1627 A @dfn{stream} is an object that can be used as a source or sink for
+ − 1628 characters---either to supply characters for input or to accept them as
+ − 1629 output. Many different types can be used this way: markers, buffers,
+ − 1630 strings, and functions. Most often, input streams (character sources)
+ − 1631 obtain characters from the keyboard, a buffer, or a file, and output
+ − 1632 streams (character sinks) send characters to a buffer, such as a
+ − 1633 @file{*Help*} buffer, or to the echo area.
+ − 1634
+ − 1635 The object @code{nil}, in addition to its other meanings, may be used
+ − 1636 as a stream. It stands for the value of the variable
+ − 1637 @code{standard-input} or @code{standard-output}. Also, the object
+ − 1638 @code{t} as a stream specifies input using the minibuffer
+ − 1639 (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
+ − 1640 Area}).
+ − 1641
+ − 1642 Streams have no special printed representation or read syntax, and
+ − 1643 print as whatever primitive type they are.
+ − 1644
+ − 1645 @xref{Read and Print}, for a description of functions
+ − 1646 related to streams, including parsing and printing functions.
+ − 1647
+ − 1648 @node Keymap Type
+ − 1649 @subsection Keymap Type
+ − 1650
+ − 1651 A @dfn{keymap} maps keys typed by the user to commands. This mapping
+ − 1652 controls how the user's command input is executed.
+ − 1653
+ − 1654 NOTE: In XEmacs, a keymap is a separate primitive type. In FSF GNU
+ − 1655 Emacs, a keymap is actually a list whose @sc{car} is the symbol
+ − 1656 @code{keymap}.
+ − 1657
+ − 1658 @xref{Keymaps}, for information about creating keymaps, handling prefix
+ − 1659 keys, local as well as global keymaps, and changing key bindings.
+ − 1660
+ − 1661 @node Syntax Table Type
+ − 1662 @subsection Syntax Table Type
+ − 1663
+ − 1664 Under XEmacs 20, a @dfn{syntax table} is a particular type of char
+ − 1665 table. Under XEmacs 19, a syntax table a vector of 256 integers. In
+ − 1666 both cases, each element defines how one character is interpreted when it
+ − 1667 appears in a buffer. For example, in C mode (@pxref{Major Modes}), the
+ − 1668 @samp{+} character is punctuation, but in Lisp mode it is a valid
+ − 1669 character in a symbol. These modes specify different interpretations by
+ − 1670 changing the syntax table entry for @samp{+}.
+ − 1671
+ − 1672 Syntax tables are used only for scanning text in buffers, not for
+ − 1673 reading Lisp expressions. The table the Lisp interpreter uses to read
+ − 1674 expressions is built into the XEmacs source code and cannot be changed;
+ − 1675 thus, to change the list delimiters to be @samp{@{} and @samp{@}}
+ − 1676 instead of @samp{(} and @samp{)} would be impossible.
+ − 1677
+ − 1678 @xref{Syntax Tables}, for details about syntax classes and how to make
+ − 1679 and modify syntax tables.
+ − 1680
+ − 1681 @node Display Table Type
+ − 1682 @subsection Display Table Type
+ − 1683
+ − 1684 A @dfn{display table} specifies how to display each character code.
+ − 1685 Each buffer and each window can have its own display table. A display
+ − 1686 table is actually a vector of length 256, although in XEmacs 20 this may
+ − 1687 change to be a particular type of char table. @xref{Display Tables}.
+ − 1688
+ − 1689 @node Database Type
+ − 1690 @subsection Database Type
+ − 1691 @cindex database type
+ − 1692
+ − 1693 (not yet documented)
+ − 1694
+ − 1695 @node Charset Type
+ − 1696 @subsection Charset Type
+ − 1697 @cindex charset type
+ − 1698
+ − 1699 (not yet documented)
+ − 1700
+ − 1701 @node Coding System Type
+ − 1702 @subsection Coding System Type
+ − 1703 @cindex coding system type
+ − 1704
+ − 1705 (not yet documented)
+ − 1706
+ − 1707 @node ToolTalk Message Type
+ − 1708 @subsection ToolTalk Message Type
+ − 1709
+ − 1710 (not yet documented)
+ − 1711
+ − 1712 @node ToolTalk Pattern Type
+ − 1713 @subsection ToolTalk Pattern Type
+ − 1714
+ − 1715 (not yet documented)
+ − 1716
+ − 1717 @node Window-System Types
+ − 1718 @section Window-System Types
+ − 1719 @cindex window system types
+ − 1720
+ − 1721 XEmacs also has some types that represent objects such as faces
+ − 1722 (collections of display characters), fonts, and pixmaps that are
+ − 1723 commonly found in windowing systems.
+ − 1724
+ − 1725 @menu
+ − 1726 * Face Type:: A collection of display characteristics.
+ − 1727 * Glyph Type:: An image appearing in a buffer or elsewhere.
+ − 1728 * Specifier Type:: A way of controlling display characteristics on
+ − 1729 a per-buffer, -frame, -window, or -device level.
+ − 1730 * Font Instance Type:: The way a font appears on a particular device.
+ − 1731 * Color Instance Type:: The way a color appears on a particular device.
+ − 1732 * Image Instance Type:: The way an image appears on a particular device.
+ − 1733 * Toolbar Button Type:: An object representing a button in a toolbar.
+ − 1734 * Subwindow Type:: An externally-controlled window-system window
+ − 1735 appearing in a buffer.
+ − 1736 * X Resource Type:: A miscellaneous X resource, if Epoch support was
+ − 1737 compiled into XEmacs.
+ − 1738 @end menu
+ − 1739
+ − 1740 @node Face Type
+ − 1741 @subsection Face Type
+ − 1742 @cindex face type
+ − 1743
+ − 1744 (not yet documented)
+ − 1745
+ − 1746 @node Glyph Type
+ − 1747 @subsection Glyph Type
+ − 1748 @cindex glyph type
+ − 1749
+ − 1750 (not yet documented)
+ − 1751
+ − 1752 @node Specifier Type
+ − 1753 @subsection Specifier Type
+ − 1754 @cindex specifier type
+ − 1755
+ − 1756 (not yet documented)
+ − 1757
+ − 1758 @node Font Instance Type
+ − 1759 @subsection Font Instance Type
+ − 1760 @cindex font instance type
+ − 1761
+ − 1762 (not yet documented)
+ − 1763
+ − 1764 @node Color Instance Type
+ − 1765 @subsection Color Instance Type
+ − 1766 @cindex color instance type
+ − 1767
+ − 1768 (not yet documented)
+ − 1769
+ − 1770 @node Image Instance Type
+ − 1771 @subsection Image Instance Type
+ − 1772 @cindex image instance type
+ − 1773
+ − 1774 (not yet documented)
+ − 1775
+ − 1776 @node Toolbar Button Type
+ − 1777 @subsection Toolbar Button Type
+ − 1778 @cindex toolbar button type
+ − 1779
+ − 1780 (not yet documented)
+ − 1781
+ − 1782 @node Subwindow Type
+ − 1783 @subsection Subwindow Type
+ − 1784 @cindex subwindow type
+ − 1785
+ − 1786 (not yet documented)
+ − 1787
+ − 1788 @node X Resource Type
+ − 1789 @subsection X Resource Type
+ − 1790 @cindex X resource type
+ − 1791
+ − 1792 (not yet documented)
+ − 1793
+ − 1794 @node Type Predicates
+ − 1795 @section Type Predicates
+ − 1796 @cindex predicates
+ − 1797 @cindex type checking
+ − 1798 @kindex wrong-type-argument
+ − 1799
+ − 1800 The XEmacs Lisp interpreter itself does not perform type checking on
+ − 1801 the actual arguments passed to functions when they are called. It could
+ − 1802 not do so, since function arguments in Lisp do not have declared data
+ − 1803 types, as they do in other programming languages. It is therefore up to
+ − 1804 the individual function to test whether each actual argument belongs to
+ − 1805 a type that the function can use.
+ − 1806
+ − 1807 All built-in functions do check the types of their actual arguments
+ − 1808 when appropriate, and signal a @code{wrong-type-argument} error if an
+ − 1809 argument is of the wrong type. For example, here is what happens if you
+ − 1810 pass an argument to @code{+} that it cannot handle:
+ − 1811
+ − 1812 @example
+ − 1813 @group
+ − 1814 (+ 2 'a)
+ − 1815 @error{} Wrong type argument: integer-or-marker-p, a
+ − 1816 @end group
+ − 1817 @end example
+ − 1818
+ − 1819 @cindex type predicates
+ − 1820 @cindex testing types
+ − 1821 If you want your program to handle different types differently, you
+ − 1822 must do explicit type checking. The most common way to check the type
+ − 1823 of an object is to call a @dfn{type predicate} function. Emacs has a
+ − 1824 type predicate for each type, as well as some predicates for
+ − 1825 combinations of types.
+ − 1826
+ − 1827 A type predicate function takes one argument; it returns @code{t} if
+ − 1828 the argument belongs to the appropriate type, and @code{nil} otherwise.
+ − 1829 Following a general Lisp convention for predicate functions, most type
+ − 1830 predicates' names end with @samp{p}.
+ − 1831
+ − 1832 Here is an example which uses the predicates @code{listp} to check for
+ − 1833 a list and @code{symbolp} to check for a symbol.
+ − 1834
+ − 1835 @example
+ − 1836 (defun add-on (x)
+ − 1837 (cond ((symbolp x)
+ − 1838 ;; If X is a symbol, put it on LIST.
+ − 1839 (setq list (cons x list)))
+ − 1840 ((listp x)
+ − 1841 ;; If X is a list, add its elements to LIST.
+ − 1842 (setq list (append x list)))
+ − 1843 @need 3000
+ − 1844 (t
+ − 1845 ;; We only handle symbols and lists.
+ − 1846 (error "Invalid argument %s in add-on" x))))
+ − 1847 @end example
+ − 1848
+ − 1849 Here is a table of predefined type predicates, in alphabetical order,
+ − 1850 with references to further information.
+ − 1851
+ − 1852 @table @code
+ − 1853 @item annotationp
+ − 1854 @xref{Annotation Primitives, annotationp}.
+ − 1855
+ − 1856 @item arrayp
+ − 1857 @xref{Array Functions, arrayp}.
+ − 1858
+ − 1859 @item atom
+ − 1860 @xref{List-related Predicates, atom}.
+ − 1861
+ − 1862 @item bit-vector-p
+ − 1863 @xref{Bit Vector Functions, bit-vector-p}.
+ − 1864
+ − 1865 @item bitp
+ − 1866 @xref{Bit Vector Functions, bitp}.
+ − 1867
+ − 1868 @item boolean-specifier-p
+ − 1869 @xref{Specifier Types, boolean-specifier-p}.
+ − 1870
+ − 1871 @item buffer-glyph-p
+ − 1872 @xref{Glyph Types, buffer-glyph-p}.
+ − 1873
+ − 1874 @item buffer-live-p
+ − 1875 @xref{Killing Buffers, buffer-live-p}.
+ − 1876
+ − 1877 @item bufferp
+ − 1878 @xref{Buffer Basics, bufferp}.
+ − 1879
+ − 1880 @item button-event-p
+ − 1881 @xref{Event Predicates, button-event-p}.
+ − 1882
+ − 1883 @item button-press-event-p
+ − 1884 @xref{Event Predicates, button-press-event-p}.
+ − 1885
+ − 1886 @item button-release-event-p
+ − 1887 @xref{Event Predicates, button-release-event-p}.
+ − 1888
+ − 1889 @item case-table-p
+ − 1890 @xref{Case Tables, case-table-p}.
+ − 1891
+ − 1892 @item char-int-p
+ − 1893 @xref{Character Codes, char-int-p}.
+ − 1894
+ − 1895 @item char-or-char-int-p
+ − 1896 @xref{Character Codes, char-or-char-int-p}.
+ − 1897
+ − 1898 @item char-or-string-p
+ − 1899 @xref{Predicates for Strings, char-or-string-p}.
+ − 1900
+ − 1901 @item char-table-p
+ − 1902 @xref{Char Tables, char-table-p}.
+ − 1903
+ − 1904 @item characterp
+ − 1905 @xref{Predicates for Characters, characterp}.
+ − 1906
+ − 1907 @item color-instance-p
+ − 1908 @xref{Colors, color-instance-p}.
+ − 1909
+ − 1910 @item color-pixmap-image-instance-p
+ − 1911 @xref{Image Instance Types, color-pixmap-image-instance-p}.
+ − 1912
+ − 1913 @item color-specifier-p
+ − 1914 @xref{Specifier Types, color-specifier-p}.
+ − 1915
+ − 1916 @item commandp
+ − 1917 @xref{Interactive Call, commandp}.
+ − 1918
+ − 1919 @item compiled-function-p
+ − 1920 @xref{Compiled-Function Type, compiled-function-p}.
+ − 1921
+ − 1922 @item console-live-p
+ − 1923 @xref{Connecting to a Console or Device, console-live-p}.
+ − 1924
+ − 1925 @item consolep
+ − 1926 @xref{Consoles and Devices, consolep}.
+ − 1927
+ − 1928 @item consp
+ − 1929 @xref{List-related Predicates, consp}.
+ − 1930
+ − 1931 @item database-live-p
+ − 1932 @xref{Connecting to a Database, database-live-p}.
+ − 1933
+ − 1934 @item databasep
+ − 1935 @xref{Databases, databasep}.
+ − 1936
+ − 1937 @item device-live-p
+ − 1938 @xref{Connecting to a Console or Device, device-live-p}.
+ − 1939
+ − 1940 @item device-or-frame-p
+ − 1941 @xref{Basic Device Functions, device-or-frame-p}.
+ − 1942
+ − 1943 @item devicep
+ − 1944 @xref{Consoles and Devices, devicep}.
+ − 1945
+ − 1946 @item eval-event-p
+ − 1947 @xref{Event Predicates, eval-event-p}.
+ − 1948
+ − 1949 @item event-live-p
+ − 1950 @xref{Event Predicates, event-live-p}.
+ − 1951
+ − 1952 @item eventp
+ − 1953 @xref{Events, eventp}.
+ − 1954
+ − 1955 @item extent-live-p
+ − 1956 @xref{Creating and Modifying Extents, extent-live-p}.
+ − 1957
+ − 1958 @item extentp
+ − 1959 @xref{Extents, extentp}.
+ − 1960
+ − 1961 @item face-boolean-specifier-p
+ − 1962 @xref{Specifier Types, face-boolean-specifier-p}.
+ − 1963
+ − 1964 @item facep
+ − 1965 @xref{Basic Face Functions, facep}.
+ − 1966
+ − 1967 @item floatp
+ − 1968 @xref{Predicates on Numbers, floatp}.
+ − 1969
+ − 1970 @item font-instance-p
+ − 1971 @xref{Fonts, font-instance-p}.
+ − 1972
+ − 1973 @item font-specifier-p
+ − 1974 @xref{Specifier Types, font-specifier-p}.
+ − 1975
+ − 1976 @item frame-live-p
+ − 1977 @xref{Deleting Frames, frame-live-p}.
+ − 1978
+ − 1979 @item framep
+ − 1980 @xref{Frames, framep}.
+ − 1981
+ − 1982 @item functionp
+ − 1983 (not yet documented)
+ − 1984
+ − 1985 @item generic-specifier-p
+ − 1986 @xref{Specifier Types, generic-specifier-p}.
+ − 1987
+ − 1988 @item glyphp
+ − 1989 @xref{Glyphs, glyphp}.
+ − 1990
+ − 1991 @item hash-table-p
+ − 1992 @xref{Hash Tables, hash-table-p}.
+ − 1993
+ − 1994 @item icon-glyph-p
+ − 1995 @xref{Glyph Types, icon-glyph-p}.
+ − 1996
+ − 1997 @item image-instance-p
+ − 1998 @xref{Images, image-instance-p}.
+ − 1999
+ − 2000 @item image-specifier-p
+ − 2001 @xref{Specifier Types, image-specifier-p}.
+ − 2002
+ − 2003 @item integer-char-or-marker-p
+ − 2004 @xref{Predicates on Markers, integer-char-or-marker-p}.
+ − 2005
+ − 2006 @item integer-or-char-p
+ − 2007 @xref{Predicates for Characters, integer-or-char-p}.
+ − 2008
+ − 2009 @item integer-or-marker-p
+ − 2010 @xref{Predicates on Markers, integer-or-marker-p}.
+ − 2011
+ − 2012 @item integer-specifier-p
+ − 2013 @xref{Specifier Types, integer-specifier-p}.
+ − 2014
+ − 2015 @item integerp
+ − 2016 @xref{Predicates on Numbers, integerp}.
+ − 2017
+ − 2018 @item itimerp
+ − 2019 (not yet documented)
+ − 2020
+ − 2021 @item key-press-event-p
+ − 2022 @xref{Event Predicates, key-press-event-p}.
+ − 2023
+ − 2024 @item keymapp
+ − 2025 @xref{Creating Keymaps, keymapp}.
+ − 2026
+ − 2027 @item keywordp
+ − 2028 (not yet documented)
+ − 2029
+ − 2030 @item listp
+ − 2031 @xref{List-related Predicates, listp}.
+ − 2032
+ − 2033 @item markerp
+ − 2034 @xref{Predicates on Markers, markerp}.
+ − 2035
+ − 2036 @item misc-user-event-p
+ − 2037 @xref{Event Predicates, misc-user-event-p}.
+ − 2038
+ − 2039 @item mono-pixmap-image-instance-p
+ − 2040 @xref{Image Instance Types, mono-pixmap-image-instance-p}.
+ − 2041
+ − 2042 @item motion-event-p
+ − 2043 @xref{Event Predicates, motion-event-p}.
+ − 2044
+ − 2045 @item mouse-event-p
+ − 2046 @xref{Event Predicates, mouse-event-p}.
+ − 2047
+ − 2048 @item natnum-specifier-p
+ − 2049 @xref{Specifier Types, natnum-specifier-p}.
+ − 2050
+ − 2051 @item natnump
+ − 2052 @xref{Predicates on Numbers, natnump}.
+ − 2053
+ − 2054 @item nlistp
+ − 2055 @xref{List-related Predicates, nlistp}.
+ − 2056
+ − 2057 @item nothing-image-instance-p
+ − 2058 @xref{Image Instance Types, nothing-image-instance-p}.
+ − 2059
+ − 2060 @item number-char-or-marker-p
+ − 2061 @xref{Predicates on Markers, number-char-or-marker-p}.
+ − 2062
+ − 2063 @item number-or-marker-p
+ − 2064 @xref{Predicates on Markers, number-or-marker-p}.
+ − 2065
+ − 2066 @item numberp
+ − 2067 @xref{Predicates on Numbers, numberp}.
+ − 2068
+ − 2069 @item pointer-glyph-p
+ − 2070 @xref{Glyph Types, pointer-glyph-p}.
+ − 2071
+ − 2072 @item pointer-image-instance-p
+ − 2073 @xref{Image Instance Types, pointer-image-instance-p}.
+ − 2074
+ − 2075 @item process-event-p
+ − 2076 @xref{Event Predicates, process-event-p}.
+ − 2077
+ − 2078 @item processp
+ − 2079 @xref{Processes, processp}.
+ − 2080
+ − 2081 @item range-table-p
+ − 2082 @xref{Range Tables, range-table-p}.
+ − 2083
+ − 2084 @item ringp
+ − 2085 (not yet documented)
+ − 2086
+ − 2087 @item sequencep
+ − 2088 @xref{Sequence Functions, sequencep}.
+ − 2089
+ − 2090 @item specifierp
+ − 2091 @xref{Specifiers, specifierp}.
+ − 2092
+ − 2093 @item stringp
+ − 2094 @xref{Predicates for Strings, stringp}.
+ − 2095
+ − 2096 @item subrp
+ − 2097 @xref{Function Cells, subrp}.
+ − 2098
+ − 2099 @item subwindow-image-instance-p
+ − 2100 @xref{Image Instance Types, subwindow-image-instance-p}.
+ − 2101
+ − 2102 @item subwindowp
+ − 2103 @xref{Subwindows, subwindowp}.
+ − 2104
+ − 2105 @item symbolp
+ − 2106 @xref{Symbols, symbolp}.
+ − 2107
+ − 2108 @item syntax-table-p
+ − 2109 @xref{Syntax Tables, syntax-table-p}.
+ − 2110
+ − 2111 @item text-image-instance-p
+ − 2112 @xref{Image Instance Types, text-image-instance-p}.
+ − 2113
+ − 2114 @item timeout-event-p
+ − 2115 @xref{Event Predicates, timeout-event-p}.
+ − 2116
+ − 2117 @item toolbar-button-p
+ − 2118 @xref{Toolbar, toolbar-button-p}.
+ − 2119
+ − 2120 @item toolbar-specifier-p
+ − 2121 @xref{Toolbar, toolbar-specifier-p}.
+ − 2122
+ − 2123 @item user-variable-p
+ − 2124 @xref{Defining Variables, user-variable-p}.
+ − 2125
+ − 2126 @item vectorp
+ − 2127 @xref{Vectors, vectorp}.
+ − 2128
+ − 2129 @item weak-list-p
+ − 2130 @xref{Weak Lists, weak-list-p}.
+ − 2131
+ − 2132 @ignore
+ − 2133 @item wholenump
+ − 2134 @xref{Predicates on Numbers, wholenump}.
+ − 2135 @end ignore
+ − 2136
+ − 2137 @item window-configuration-p
+ − 2138 @xref{Window Configurations, window-configuration-p}.
+ − 2139
+ − 2140 @item window-live-p
+ − 2141 @xref{Deleting Windows, window-live-p}.
+ − 2142
+ − 2143 @item windowp
+ − 2144 @xref{Basic Windows, windowp}.
+ − 2145 @end table
+ − 2146
+ − 2147 The most general way to check the type of an object is to call the
+ − 2148 function @code{type-of}. Recall that each object belongs to one and
+ − 2149 only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
+ − 2150 Data Types}). But @code{type-of} knows nothing about non-primitive
+ − 2151 types. In most cases, it is more convenient to use type predicates than
+ − 2152 @code{type-of}.
+ − 2153
+ − 2154 @defun type-of object
+ − 2155 This function returns a symbol naming the primitive type of
+ − 2156 @var{object}. The value is one of @code{bit-vector}, @code{buffer},
+ − 2157 @code{char-table}, @code{character}, @code{charset},
+ − 2158 @code{coding-system}, @code{cons}, @code{color-instance},
+ − 2159 @code{compiled-function}, @code{console}, @code{database},
+ − 2160 @code{device}, @code{event}, @code{extent}, @code{face}, @code{float},
+ − 2161 @code{font-instance}, @code{frame}, @code{glyph}, @code{hash-table},
+ − 2162 @code{image-instance}, @code{integer}, @code{keymap}, @code{marker},
+ − 2163 @code{process}, @code{range-table}, @code{specifier}, @code{string},
+ − 2164 @code{subr}, @code{subwindow}, @code{symbol}, @code{toolbar-button},
+ − 2165 @code{tooltalk-message}, @code{tooltalk-pattern}, @code{vector},
+ − 2166 @code{weak-list}, @code{window}, @code{window-configuration}, or
+ − 2167 @code{x-resource}.
+ − 2168
+ − 2169 @example
+ − 2170 (type-of 1)
+ − 2171 @result{} integer
+ − 2172 (type-of 'nil)
+ − 2173 @result{} symbol
+ − 2174 (type-of '()) ; @r{@code{()} is @code{nil}.}
+ − 2175 @result{} symbol
+ − 2176 (type-of '(x))
+ − 2177 @result{} cons
+ − 2178 @end example
+ − 2179 @end defun
+ − 2180
+ − 2181 @node Equality Predicates
+ − 2182 @section Equality Predicates
+ − 2183 @cindex equality
+ − 2184
+ − 2185 Here we describe two functions that test for equality between any two
+ − 2186 objects. Other functions test equality between objects of specific
+ − 2187 types, e.g., strings. For these predicates, see the appropriate chapter
+ − 2188 describing the data type.
+ − 2189
+ − 2190 @defun eq object1 object2
+ − 2191 This function returns @code{t} if @var{object1} and @var{object2} are
+ − 2192 the same object, @code{nil} otherwise. The ``same object'' means that a
+ − 2193 change in one will be reflected by the same change in the other.
+ − 2194
+ − 2195 @code{eq} returns @code{t} if @var{object1} and @var{object2} are
+ − 2196 integers with the same value. Also, since symbol names are normally
+ − 2197 unique, if the arguments are symbols with the same name, they are
+ − 2198 @code{eq}. For other types (e.g., lists, vectors, strings), two
+ − 2199 arguments with the same contents or elements are not necessarily
+ − 2200 @code{eq} to each other: they are @code{eq} only if they are the same
+ − 2201 object.
+ − 2202
+ − 2203 (The @code{make-symbol} function returns an uninterned symbol that is
+ − 2204 not interned in the standard @code{obarray}. When uninterned symbols
+ − 2205 are in use, symbol names are no longer unique. Distinct symbols with
+ − 2206 the same name are not @code{eq}. @xref{Creating Symbols}.)
+ − 2207
+ − 2208 NOTE: Under XEmacs 19, characters are really just integers, and thus
+ − 2209 characters and integers are @code{eq}. Under XEmacs 20, it was
+ − 2210 necessary to preserve remnants of this in function such as @code{old-eq}
+ − 2211 in order to maintain byte-code compatibility. Byte code compiled
+ − 2212 under any Emacs 19 will automatically have calls to @code{eq} mapped
+ − 2213 to @code{old-eq} when executed under XEmacs 20.
+ − 2214
+ − 2215 @example
+ − 2216 @group
+ − 2217 (eq 'foo 'foo)
+ − 2218 @result{} t
+ − 2219 @end group
+ − 2220
+ − 2221 @group
+ − 2222 (eq 456 456)
+ − 2223 @result{} t
+ − 2224 @end group
+ − 2225
+ − 2226 @group
+ − 2227 (eq "asdf" "asdf")
+ − 2228 @result{} nil
+ − 2229 @end group
+ − 2230
+ − 2231 @group
+ − 2232 (eq '(1 (2 (3))) '(1 (2 (3))))
+ − 2233 @result{} nil
+ − 2234 @end group
+ − 2235
+ − 2236 @group
+ − 2237 (setq foo '(1 (2 (3))))
+ − 2238 @result{} (1 (2 (3)))
+ − 2239 (eq foo foo)
+ − 2240 @result{} t
+ − 2241 (eq foo '(1 (2 (3))))
+ − 2242 @result{} nil
+ − 2243 @end group
+ − 2244
+ − 2245 @group
+ − 2246 (eq [(1 2) 3] [(1 2) 3])
+ − 2247 @result{} nil
+ − 2248 @end group
+ − 2249
+ − 2250 @group
+ − 2251 (eq (point-marker) (point-marker))
+ − 2252 @result{} nil
+ − 2253 @end group
+ − 2254 @end example
+ − 2255
+ − 2256 @end defun
+ − 2257
444
+ − 2258 @defun old-eq object1 object2
428
+ − 2259 This function exists under XEmacs 20 and is exactly like @code{eq}
+ − 2260 except that it suffers from the char-int confoundance disease.
+ − 2261 In other words, it returns @code{t} if given a character and the
+ − 2262 equivalent integer, even though the objects are of different types!
+ − 2263 You should @emph{not} ever call this function explicitly in your
+ − 2264 code. However, be aware that all calls to @code{eq} in byte code
+ − 2265 compiled under version 19 map to @code{old-eq} in XEmacs 20.
+ − 2266 (Likewise for @code{old-equal}, @code{old-memq}, @code{old-member},
+ − 2267 @code{old-assq} and @code{old-assoc}.)
+ − 2268
+ − 2269 @example
+ − 2270 @group
+ − 2271 ;; @r{Remember, this does not apply under XEmacs 19.}
+ − 2272 ?A
+ − 2273 @result{} ?A
+ − 2274 (char-int ?A)
+ − 2275 @result{} 65
+ − 2276 (old-eq ?A 65)
+ − 2277 @result{} t ; @r{Eek, we've been infected.}
+ − 2278 (eq ?A 65)
+ − 2279 @result{} nil ; @r{We are still healthy.}
+ − 2280 @end group
+ − 2281 @end example
+ − 2282 @end defun
+ − 2283
+ − 2284 @defun equal object1 object2
+ − 2285 This function returns @code{t} if @var{object1} and @var{object2} have
+ − 2286 equal components, @code{nil} otherwise. Whereas @code{eq} tests if its
+ − 2287 arguments are the same object, @code{equal} looks inside nonidentical
+ − 2288 arguments to see if their elements are the same. So, if two objects are
+ − 2289 @code{eq}, they are @code{equal}, but the converse is not always true.
+ − 2290
+ − 2291 @example
+ − 2292 @group
+ − 2293 (equal 'foo 'foo)
+ − 2294 @result{} t
+ − 2295 @end group
+ − 2296
+ − 2297 @group
+ − 2298 (equal 456 456)
+ − 2299 @result{} t
+ − 2300 @end group
+ − 2301
+ − 2302 @group
+ − 2303 (equal "asdf" "asdf")
+ − 2304 @result{} t
+ − 2305 @end group
+ − 2306 @group
+ − 2307 (eq "asdf" "asdf")
+ − 2308 @result{} nil
+ − 2309 @end group
+ − 2310
+ − 2311 @group
+ − 2312 (equal '(1 (2 (3))) '(1 (2 (3))))
+ − 2313 @result{} t
+ − 2314 @end group
+ − 2315 @group
+ − 2316 (eq '(1 (2 (3))) '(1 (2 (3))))
+ − 2317 @result{} nil
+ − 2318 @end group
+ − 2319
+ − 2320 @group
+ − 2321 (equal [(1 2) 3] [(1 2) 3])
+ − 2322 @result{} t
+ − 2323 @end group
+ − 2324 @group
+ − 2325 (eq [(1 2) 3] [(1 2) 3])
+ − 2326 @result{} nil
+ − 2327 @end group
+ − 2328
+ − 2329 @group
+ − 2330 (equal (point-marker) (point-marker))
+ − 2331 @result{} t
+ − 2332 @end group
+ − 2333
+ − 2334 @group
+ − 2335 (eq (point-marker) (point-marker))
+ − 2336 @result{} nil
+ − 2337 @end group
+ − 2338 @end example
+ − 2339
+ − 2340 Comparison of strings is case-sensitive.
+ − 2341
+ − 2342 Note that in FSF GNU Emacs, comparison of strings takes into account
+ − 2343 their text properties, and you have to use @code{string-equal} if you
+ − 2344 want only the strings themselves compared. This difference does not
+ − 2345 exist in XEmacs; @code{equal} and @code{string-equal} always return
+ − 2346 the same value on the same strings.
+ − 2347
+ − 2348 @ignore @c Not true in XEmacs
+ − 2349 Comparison of strings is case-sensitive and takes account of text
+ − 2350 properties as well as the characters in the strings. To compare
+ − 2351 two strings' characters without comparing their text properties,
+ − 2352 use @code{string=} (@pxref{Text Comparison}).
+ − 2353 @end ignore
+ − 2354
+ − 2355 @example
+ − 2356 @group
+ − 2357 (equal "asdf" "ASDF")
+ − 2358 @result{} nil
+ − 2359 @end group
+ − 2360 @end example
+ − 2361
+ − 2362 Two distinct buffers are never @code{equal}, even if their contents
+ − 2363 are the same.
+ − 2364 @end defun
+ − 2365
+ − 2366 The test for equality is implemented recursively, and circular lists may
+ − 2367 therefore cause infinite recursion (leading to an error).