123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142 |
- @c -*- mode: texinfo; coding: utf-8 -*-
- @c This is part of the GNU Emacs Lisp Reference Manual.
- @c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
- @c Foundation, Inc.
- @c See the file elisp.texi for copying conditions.
- @node Lisp Data Types
- @chapter Lisp Data Types
- @cindex object
- @cindex Lisp object
- @cindex type
- @cindex data type
- A Lisp @dfn{object} is a piece of data used and manipulated by Lisp
- programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of
- possible objects.
- Every object belongs to at least one type. Objects of the same type
- have similar structures and may usually be used in the same contexts.
- Types can overlap, and objects can belong to two or more types.
- Consequently, we can ask whether an object belongs to a particular type,
- but not for @emph{the} type of an object.
- @cindex primitive type
- A few fundamental object types are built into Emacs. These, from
- which all other types are constructed, are called @dfn{primitive types}.
- Each object belongs to one and only one primitive type. These types
- include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol},
- @dfn{string}, @dfn{vector}, @dfn{hash-table}, @dfn{subr}, and
- @dfn{byte-code function}, plus several special types, such as
- @dfn{buffer}, that are related to editing. (@xref{Editing Types}.)
- Each primitive type has a corresponding Lisp function that checks
- whether an object is a member of that type.
- Lisp is unlike many other languages in that its objects are
- @dfn{self-typing}: the primitive type of each object is implicit in
- the object itself. For example, if an object is a vector, nothing can
- treat it as a number; Lisp knows it is a vector, not a number.
- In most languages, the programmer must declare the data type of each
- variable, and the type is known by the compiler but not represented in
- the data. Such type declarations do not exist in Emacs Lisp. A Lisp
- variable can have any type of value, and it remembers whatever value
- you store in it, type and all. (Actually, a small number of Emacs
- Lisp variables can only take on values of a certain type.
- @xref{Variables with Restricted Values}.)
- This chapter describes the purpose, printed representation, and read
- syntax of each of the standard types in GNU Emacs Lisp. Details on how
- to use these types can be found in later chapters.
- @menu
- * Printed Representation:: How Lisp objects are represented as text.
- * Comments:: Comments and their formatting conventions.
- * Programming Types:: Types found in all Lisp systems.
- * Editing Types:: Types specific to Emacs.
- * Circular Objects:: Read syntax for circular structure.
- * Type Predicates:: Tests related to types.
- * Equality Predicates:: Tests of equality between any two objects.
- @end menu
- @node Printed Representation
- @section Printed Representation and Read Syntax
- @cindex printed representation
- @cindex read syntax
- The @dfn{printed representation} of an object is the format of the
- output generated by the Lisp printer (the function @code{prin1}) for
- that object. Every data type has a unique printed representation.
- The @dfn{read syntax} of an object is the format of the input accepted
- by the Lisp reader (the function @code{read}) for that object. This
- is not necessarily unique; many kinds of object have more than one
- syntax. @xref{Read and Print}.
- @cindex hash notation
- In most cases, an object's printed representation is also a read
- syntax for the object. However, some types have no read syntax, since
- it does not make sense to enter objects of these types as constants in
- a Lisp program. These objects are printed in @dfn{hash notation},
- which consists of the characters @samp{#<}, a descriptive string
- (typically the type name followed by the name of the object), and a
- closing @samp{>}. For example:
- @example
- (current-buffer)
- @result{} #<buffer objects.texi>
- @end example
- @noindent
- Hash notation cannot be read at all, so the Lisp reader signals the
- error @code{invalid-read-syntax} whenever it encounters @samp{#<}.
- @kindex invalid-read-syntax
- In other languages, an expression is text; it has no other form. In
- Lisp, an expression is primarily a Lisp object and only secondarily the
- text that is the object's read syntax. Often there is no need to
- emphasize this distinction, but you must keep it in the back of your
- mind, or you will occasionally be very confused.
- When you evaluate an expression interactively, the Lisp interpreter
- first reads the textual representation of it, producing a Lisp object,
- and then evaluates that object (@pxref{Evaluation}). However,
- evaluation and reading are separate activities. Reading returns the
- Lisp object represented by the text that is read; the object may or may
- not be evaluated later. @xref{Input Functions}, for a description of
- @code{read}, the basic function for reading objects.
- @node Comments
- @section Comments
- @cindex comments
- @cindex @samp{;} in comment
- A @dfn{comment} is text that is written in a program only for the sake
- of humans that read the program, and that has no effect on the meaning
- of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it
- is not within a string or character constant. The comment continues to
- the end of line. The Lisp reader discards comments; they do not become
- part of the Lisp objects which represent the program within the Lisp
- system.
- The @samp{#@@@var{count}} construct, which skips the next @var{count}
- characters, is useful for program-generated comments containing binary
- data. The Emacs Lisp byte compiler uses this in its output files
- (@pxref{Byte Compilation}). It isn't meant for source files, however.
- @xref{Comment Tips}, for conventions for formatting comments.
- @node Programming Types
- @section Programming Types
- @cindex programming types
- There are two general categories of types in Emacs Lisp: those having
- to do with Lisp programming, and those having to do with editing. The
- former exist in many Lisp implementations, in one form or another. The
- latter are unique to Emacs Lisp.
- @menu
- * Integer Type:: Numbers without fractional parts.
- * Floating-Point Type:: Numbers with fractional parts and with a large range.
- * Character Type:: The representation of letters, numbers and
- control characters.
- * Symbol Type:: A multi-use object that refers to a function,
- variable, or property list, and has a unique identity.
- * Sequence Type:: Both lists and arrays are classified as sequences.
- * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
- * Array Type:: Arrays include strings and vectors.
- * String Type:: An (efficient) array of characters.
- * Vector Type:: One-dimensional arrays.
- * Char-Table Type:: One-dimensional sparse arrays indexed by characters.
- * Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}.
- * Hash Table Type:: Super-fast lookup tables.
- * Function Type:: A piece of executable code you can call from elsewhere.
- * Macro Type:: A method of expanding an expression into another
- expression, more fundamental but less pretty.
- * Primitive Function Type:: A function written in C, callable from Lisp.
- * Byte-Code Type:: A function written in Lisp, then compiled.
- * Autoload Type:: A type used for automatically loading seldom-used
- functions.
- * Finalizer Type:: Runs code when no longer reachable.
- @end menu
- @node Integer Type
- @subsection Integer Type
- The range of values for an integer depends on the machine. The
- minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e.,
- @ifnottex
- @minus{}2**29
- @end ifnottex
- @tex
- @math{-2^{29}}
- @end tex
- to
- @ifnottex
- 2**29 @minus{} 1)
- @end ifnottex
- @tex
- @math{2^{29}-1})
- @end tex
- but many machines provide a wider range.
- Emacs Lisp arithmetic functions do not check for integer overflow. Thus
- @code{(1+ 536870911)} is @minus{}536,870,912 if Emacs integers are 30 bits.
- The read syntax for integers is a sequence of (base ten) digits with an
- optional sign at the beginning and an optional period at the end. The
- printed representation produced by the Lisp interpreter never has a
- leading @samp{+} or a final @samp{.}.
- @example
- @group
- -1 ; @r{The integer @minus{}1.}
- 1 ; @r{The integer 1.}
- 1. ; @r{Also the integer 1.}
- +1 ; @r{Also the integer 1.}
- @end group
- @end example
- @noindent
- As a special exception, if a sequence of digits specifies an integer
- too large or too small to be a valid integer object, the Lisp reader
- reads it as a floating-point number (@pxref{Floating-Point Type}).
- For instance, if Emacs integers are 30 bits, @code{536870912} is read
- as the floating-point number @code{536870912.0}.
- @xref{Numbers}, for more information.
- @node Floating-Point Type
- @subsection Floating-Point Type
- Floating-point numbers are the computer equivalent of scientific
- notation; you can think of a floating-point number as a fraction
- together with a power of ten. The precise number of significant
- figures and the range of possible exponents is machine-specific; Emacs
- uses the C data type @code{double} to store the value, and internally
- this records a power of 2 rather than a power of 10.
- The printed representation for floating-point numbers requires either
- a decimal point (with at least one digit following), an exponent, or
- both. For example, @samp{1500.0}, @samp{+15e2}, @samp{15.0e+2},
- @samp{+1500000e-3}, and @samp{.15e4} are five ways of writing a floating-point
- number whose value is 1500. They are all equivalent.
- @xref{Numbers}, for more information.
- @node Character Type
- @subsection Character Type
- @cindex @acronym{ASCII} character codes
- A @dfn{character} in Emacs Lisp is nothing more than an integer. In
- other words, characters are represented by their character codes. For
- example, the character @kbd{A} is represented as the @w{integer 65}.
- Individual characters are used occasionally in programs, but it is
- more common to work with @emph{strings}, which are sequences composed
- of characters. @xref{String Type}.
- Characters in strings and buffers are currently limited to the range
- of 0 to 4194303---twenty two bits (@pxref{Character Codes}). Codes 0
- through 127 are @acronym{ASCII} codes; the rest are
- non-@acronym{ASCII} (@pxref{Non-ASCII Characters}). Characters that
- represent keyboard input have a much wider range, to encode modifier
- keys such as Control, Meta and Shift.
- There are special functions for producing a human-readable textual
- description of a character for the sake of messages. @xref{Describing
- Characters}.
- @menu
- * Basic Char Syntax:: Syntax for regular characters.
- * General Escape Syntax:: How to specify characters by their codes.
- * Ctl-Char Syntax:: Syntax for control characters.
- * Meta-Char Syntax:: Syntax for meta-characters.
- * Other Char Bits:: Syntax for hyper-, super-, and alt-characters.
- @end menu
- @node Basic Char Syntax
- @subsubsection Basic Char Syntax
- @cindex read syntax for characters
- @cindex printed representation for characters
- @cindex syntax for characters
- @cindex @samp{?} in character constant
- @cindex question mark in character constant
- Since characters are really integers, the printed representation of
- a character is a decimal number. This is also a possible read syntax
- for a character, but writing characters that way in Lisp programs is
- not clear programming. You should @emph{always} use the special read
- syntax formats that Emacs Lisp provides for characters. These syntax
- formats start with a question mark.
- The usual read syntax for alphanumeric characters is a question mark
- followed by the character; thus, @samp{?A} for the character
- @kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
- character @kbd{a}.
- For example:
- @example
- ?Q @result{} 81 ?q @result{} 113
- @end example
- You can use the same syntax for punctuation characters, but it is
- often a good idea to add a @samp{\} so that the Emacs commands for
- editing Lisp code don't get confused. For example, @samp{?\(} is the
- way to write the open-paren character. If the character is @samp{\},
- you @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
- @cindex whitespace
- @cindex bell character
- @cindex @samp{\a}
- @cindex backspace
- @cindex @samp{\b}
- @cindex tab (ASCII character)
- @cindex @samp{\t}
- @cindex vertical tab
- @cindex @samp{\v}
- @cindex formfeed
- @cindex @samp{\f}
- @cindex newline
- @cindex @samp{\n}
- @cindex return (ASCII character)
- @cindex @samp{\r}
- @cindex escape (ASCII character)
- @cindex @samp{\e}
- @cindex space (ASCII character)
- @cindex @samp{\s}
- You can express the characters control-g, backspace, tab, newline,
- vertical tab, formfeed, space, return, del, and escape as @samp{?\a},
- @samp{?\b}, @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f},
- @samp{?\s}, @samp{?\r}, @samp{?\d}, and @samp{?\e}, respectively.
- (@samp{?\s} followed by a dash has a different meaning---it applies
- the Super modifier to the following character.) Thus,
- @example
- ?\a @result{} 7 ; @r{control-g, @kbd{C-g}}
- ?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
- ?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
- ?\n @result{} 10 ; @r{newline, @kbd{C-j}}
- ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
- ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
- ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
- ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
- ?\s @result{} 32 ; @r{space character, @key{SPC}}
- ?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
- ?\d @result{} 127 ; @r{delete character, @key{DEL}}
- @end example
- @cindex escape sequence
- These sequences which start with backslash are also known as
- @dfn{escape sequences}, because backslash plays the role of an
- escape character; this has nothing to do with the
- character @key{ESC}. @samp{\s} is meant for use in character
- constants; in string constants, just write the space.
- A backslash is allowed, and harmless, preceding any character without
- a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
- There is no reason to add a backslash before most characters. However,
- you should add a backslash before any of the characters
- @samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing
- Lisp code. You can also add a backslash before whitespace characters such as
- space, tab, newline and formfeed. However, it is cleaner to use one of
- the easily readable escape sequences, such as @samp{\t} or @samp{\s},
- instead of an actual whitespace character such as a tab or a space.
- (If you do write backslash followed by a space, you should write
- an extra space after the character constant to separate it from the
- following text.)
- @node General Escape Syntax
- @subsubsection General Escape Syntax
- In addition to the specific escape sequences for special important
- control characters, Emacs provides several types of escape syntax that
- you can use to specify non-@acronym{ASCII} text characters.
- @cindex @samp{\} in character constant
- @cindex backslash in character constants
- @cindex unicode character escape
- Firstly, you can specify characters by their Unicode values.
- @code{?\u@var{nnnn}} represents a character with Unicode code point
- @samp{U+@var{nnnn}}, where @var{nnnn} is (by convention) a hexadecimal
- number with exactly four digits. The backslash indicates that the
- subsequent characters form an escape sequence, and the @samp{u}
- specifies a Unicode escape sequence.
- There is a slightly different syntax for specifying Unicode
- characters with code points higher than @code{U+@var{ffff}}:
- @code{?\U00@var{nnnnnn}} represents the character with code point
- @samp{U+@var{nnnnnn}}, where @var{nnnnnn} is a six-digit hexadecimal
- number. The Unicode Standard only defines code points up to
- @samp{U+@var{10ffff}}, so if you specify a code point higher than
- that, Emacs signals an error.
- Secondly, you can specify characters by their hexadecimal character
- codes. A hexadecimal escape sequence consists of a backslash,
- @samp{x}, and the hexadecimal character code. Thus, @samp{?\x41} is
- the character @kbd{A}, @samp{?\x1} is the character @kbd{C-a}, and
- @code{?\xe0} is the character @kbd{à} (@kbd{a} with grave accent).
- You can use any number of hex digits, so you can represent any
- character code in this way.
- @cindex octal character code
- Thirdly, you can specify characters by their character code in
- octal. An octal escape sequence consists of a backslash followed by
- up to three octal digits; thus, @samp{?\101} for the character
- @kbd{A}, @samp{?\001} for the character @kbd{C-a}, and @code{?\002}
- for the character @kbd{C-b}. Only characters up to octal code 777 can
- be specified this way.
- These escape sequences may also be used in strings. @xref{Non-ASCII
- in Strings}.
- @node Ctl-Char Syntax
- @subsubsection Control-Character Syntax
- @cindex control characters
- Control characters can be represented using yet another read syntax.
- This consists of a question mark followed by a backslash, caret, and the
- corresponding non-control character, in either upper or lower case. For
- example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
- character @kbd{C-i}, the character whose value is 9.
- Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
- equivalent to @samp{?\^I} and to @samp{?\^i}:
- @example
- ?\^I @result{} 9 ?\C-I @result{} 9
- @end example
- In strings and buffers, the only control characters allowed are those
- that exist in @acronym{ASCII}; but for keyboard input purposes, you can turn
- any character into a control character with @samp{C-}. The character
- codes for these non-@acronym{ASCII} control characters include the
- @tex
- @math{2^{26}}
- @end tex
- @ifnottex
- 2**26
- @end ifnottex
- bit as well as the code for the corresponding non-control character.
- Ordinary text terminals have no way of generating non-@acronym{ASCII}
- control characters, but you can generate them straightforwardly using
- X and other window systems.
- For historical reasons, Emacs treats the @key{DEL} character as
- the control equivalent of @kbd{?}:
- @example
- ?\^? @result{} 127 ?\C-? @result{} 127
- @end example
- @noindent
- As a result, it is currently not possible to represent the character
- @kbd{Control-?}, which is a meaningful input character under X, using
- @samp{\C-}. It is not easy to change this, as various Lisp files refer
- to @key{DEL} in this way.
- For representing control characters to be found in files or strings,
- we recommend the @samp{^} syntax; for control characters in keyboard
- input, we prefer the @samp{C-} syntax. Which one you use does not
- affect the meaning of the program, but may guide the understanding of
- people who read it.
- @node Meta-Char Syntax
- @subsubsection Meta-Character Syntax
- @cindex meta characters
- A @dfn{meta character} is a character typed with the @key{META}
- modifier key. The integer that represents such a character has the
- @tex
- @math{2^{27}}
- @end tex
- @ifnottex
- 2**27
- @end ifnottex
- bit set. We use high bits for this and other modifiers to make
- possible a wide range of basic character codes.
- In a string, the
- @tex
- @math{2^{7}}
- @end tex
- @ifnottex
- 2**7
- @end ifnottex
- bit attached to an @acronym{ASCII} character indicates a meta
- character; thus, the meta characters that can fit in a string have
- codes in the range from 128 to 255, and are the meta versions of the
- ordinary @acronym{ASCII} characters. @xref{Strings of Events}, for
- details about @key{META}-handling in strings.
- The read syntax for meta characters uses @samp{\M-}. For example,
- @samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
- octal character codes (see below), with @samp{\C-}, or with any other
- syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
- or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
- @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
- @node Other Char Bits
- @subsubsection Other Character Modifier Bits
- The case of a graphic character is indicated by its character code;
- for example, @acronym{ASCII} distinguishes between the characters @samp{a}
- and @samp{A}. But @acronym{ASCII} has no way to represent whether a control
- character is upper case or lower case. Emacs uses the
- @tex
- @math{2^{25}}
- @end tex
- @ifnottex
- 2**25
- @end ifnottex
- bit to indicate that the shift key was used in typing a control
- character. This distinction is possible only when you use X terminals
- or other special terminals; ordinary text terminals do not report the
- distinction. The Lisp syntax for the shift bit is @samp{\S-}; thus,
- @samp{?\C-\S-o} or @samp{?\C-\S-O} represents the shifted-control-o
- character.
- @cindex hyper characters
- @cindex super characters
- @cindex alt characters
- The X Window System defines three other
- @anchor{modifier bits}modifier bits that can be set
- in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
- for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is
- significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents
- @kbd{Alt-Hyper-Meta-x}. (Note that @samp{\s} with no following @samp{-}
- represents the space character.)
- @tex
- Numerically, the bit values are @math{2^{22}} for alt, @math{2^{23}}
- for super and @math{2^{24}} for hyper.
- @end tex
- @ifnottex
- Numerically, the
- bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
- @end ifnottex
- @node Symbol Type
- @subsection Symbol Type
- A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The
- symbol name serves as the printed representation of the symbol. In
- ordinary Lisp use, with one single obarray (@pxref{Creating Symbols}),
- a symbol's name is unique---no two symbols have the same name.
- A symbol can serve as a variable, as a function name, or to hold a
- property list. Or it may serve only to be distinct from all other Lisp
- objects, so that its presence in a data structure may be recognized
- reliably. In a given context, usually only one of these uses is
- intended. But you can use one symbol in all of these ways,
- independently.
- A symbol whose name starts with a colon (@samp{:}) is called a
- @dfn{keyword symbol}. These symbols automatically act as constants,
- and are normally used only by comparing an unknown symbol with a few
- specific alternatives. @xref{Constant Variables}.
- @cindex @samp{\} in symbols
- @cindex backslash in symbols
- A symbol name can contain any characters whatever. Most symbol names
- are written with letters, digits, and the punctuation characters
- @samp{-+=*/}. Such names require no special punctuation; the characters
- of the name suffice as long as the name does not look like a number.
- (If it does, write a @samp{\} at the beginning of the name to force
- interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}?} are
- less often used but also require no special punctuation. Any other
- characters may be included in a symbol's name by escaping them with a
- backslash. In contrast to its use in strings, however, a backslash in
- the name of a symbol simply quotes the single character that follows the
- backslash. For example, in a string, @samp{\t} represents a tab
- character; in the name of a symbol, however, @samp{\t} merely quotes the
- letter @samp{t}. To have a symbol with a tab character in its name, you
- must actually use a tab (preceded with a backslash). But it's rare to
- do such a thing.
- @cindex CL note---case of letters
- @quotation
- @b{Common Lisp note:} In Common Lisp, lower case letters are always
- folded to upper case, unless they are explicitly escaped. In Emacs
- Lisp, upper case and lower case letters are distinct.
- @end quotation
- Here are several examples of symbol names. Note that the @samp{+} in
- the fourth example is escaped to prevent it from being read as a number.
- This is not necessary in the sixth example because the rest of the name
- makes it invalid as a number.
- @example
- @group
- foo ; @r{A symbol named @samp{foo}.}
- FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
- @end group
- @group
- 1+ ; @r{A symbol named @samp{1+}}
- ; @r{(not @samp{+1}, which is an integer).}
- @end group
- @group
- \+1 ; @r{A symbol named @samp{+1}}
- ; @r{(not a very readable name).}
- @end group
- @group
- \(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
- @c the @'s in this next line use up three characters, hence the
- @c apparent misalignment of the comment.
- +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
- ; @r{These characters need not be escaped.}
- @end group
- @end example
- @cindex @samp{##} read syntax
- @ifinfo
- @c This uses "colon" instead of a literal ':' because Info cannot
- @c cope with a ':' in a menu.
- @cindex @samp{#@var{colon}} read syntax
- @end ifinfo
- @ifnotinfo
- @cindex @samp{#:} read syntax
- @end ifnotinfo
- As an exception to the rule that a symbol's name serves as its
- printed representation, @samp{##} is the printed representation for an
- interned symbol whose name is an empty string. Furthermore,
- @samp{#:@var{foo}} is the printed representation for an uninterned
- symbol whose name is @var{foo}. (Normally, the Lisp reader interns
- all symbols; @pxref{Creating Symbols}.)
- @node Sequence Type
- @subsection Sequence Types
- A @dfn{sequence} is a Lisp object that represents an ordered set of
- elements. There are two kinds of sequence in Emacs Lisp: @dfn{lists}
- and @dfn{arrays}.
- Lists are the most commonly-used sequences. A list can hold
- elements of any type, and its length can be easily changed by adding
- or removing elements. See the next subsection for more about lists.
- Arrays are fixed-length sequences. They are further subdivided into
- strings, vectors, char-tables and bool-vectors. Vectors can hold
- elements of any type, whereas string elements must be characters, and
- bool-vector elements must be @code{t} or @code{nil}. Char-tables are
- like vectors except that they are indexed by any valid character code.
- The characters in a string can have text properties like characters in
- a buffer (@pxref{Text Properties}), but vectors do not support text
- properties, even when their elements happen to be characters.
- Lists, strings and the other array types also share important
- similarities. For example, all have a length @var{l}, and all have
- elements which can be indexed from zero to @var{l} minus one. Several
- functions, called sequence functions, accept any kind of sequence.
- For example, the function @code{length} reports the length of any kind
- of sequence. @xref{Sequences Arrays Vectors}.
- It is generally impossible to read the same sequence twice, since
- sequences are always created anew upon reading. If you read the read
- syntax for a sequence twice, you get two sequences with equal contents.
- There is one exception: the empty list @code{()} always stands for the
- same object, @code{nil}.
- @node Cons Cell Type
- @subsection Cons Cell and List Types
- @cindex address field of register
- @cindex decrement field of register
- @cindex pointers
- A @dfn{cons cell} is an object that consists of two slots, called
- the @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} any
- Lisp object. We also say that the @sc{car} of this cons cell is
- whatever object its @sc{car} slot currently holds, and likewise for
- the @sc{cdr}.
- @cindex list structure
- A @dfn{list} is a series of cons cells, linked together so that the
- @sc{cdr} slot of each cons cell holds either the next cons cell or the
- empty list. The empty list is actually the symbol @code{nil}.
- @xref{Lists}, for details. Because most cons cells are used as part
- of lists, we refer to any structure made out of cons cells as a
- @dfn{list structure}.
- @cindex linked list
- @quotation
- A note to C programmers: a Lisp list thus works as a @dfn{linked list}
- built up of cons cells. Because pointers in Lisp are implicit, we do
- not distinguish between a cons cell slot holding a value versus
- pointing to the value.
- @end quotation
- @cindex atoms
- Because cons cells are so central to Lisp, we also have a word for
- an object which is not a cons cell. These objects are called
- @dfn{atoms}.
- @cindex parenthesis
- @cindex @samp{(@dots{})} in lists
- The read syntax and printed representation for lists are identical, and
- consist of a left parenthesis, an arbitrary number of elements, and a
- right parenthesis. Here are examples of lists:
- @example
- (A 2 "A") ; @r{A list of three elements.}
- () ; @r{A list of no elements (the empty list).}
- nil ; @r{A list of no elements (the empty list).}
- ("A ()") ; @r{A list of one element: the string @code{"A ()"}.}
- (A ()) ; @r{A list of two elements: @code{A} and the empty list.}
- (A nil) ; @r{Equivalent to the previous.}
- ((A B C)) ; @r{A list of one element}
- ; @r{(which is a list of three elements).}
- @end example
- Upon reading, each object inside the parentheses becomes an element
- of the list. That is, a cons cell is made for each element. The
- @sc{car} slot of the cons cell holds the element, and its @sc{cdr}
- slot refers to the next cons cell of the list, which holds the next
- element in the list. The @sc{cdr} slot of the last cons cell is set to
- hold @code{nil}.
- The names @sc{car} and @sc{cdr} derive from the history of Lisp. The
- original Lisp implementation ran on an @w{IBM 704} computer which
- divided words into two parts, the address and the
- decrement; @sc{car} was an instruction to extract the contents of
- the address part of a register, and @sc{cdr} an instruction to extract
- the contents of the decrement. By contrast, cons cells are named
- for the function @code{cons} that creates them, which in turn was named
- for its purpose, the construction of cells.
- @menu
- * Box Diagrams:: Drawing pictures of lists.
- * Dotted Pair Notation:: A general syntax for cons cells.
- * Association List Type:: A specially constructed list.
- @end menu
- @node Box Diagrams
- @subsubsection Drawing Lists as Box Diagrams
- @cindex box diagrams, for lists
- @cindex diagrams, boxed, for lists
- A list can be illustrated by a diagram in which the cons cells are
- shown as pairs of boxes, like dominoes. (The Lisp reader cannot read
- such an illustration; unlike the textual notation, which can be
- understood by both humans and computers, the box illustrations can be
- understood only by humans.) This picture represents the three-element
- list @code{(rose violet buttercup)}:
- @example
- @group
- --- --- --- --- --- ---
- | | |--> | | |--> | | |--> nil
- --- --- --- --- --- ---
- | | |
- | | |
- --> rose --> violet --> buttercup
- @end group
- @end example
- In this diagram, each box represents a slot that can hold or refer to
- any Lisp object. Each pair of boxes represents a cons cell. Each arrow
- represents a reference to a Lisp object, either an atom or another cons
- cell.
- In this example, the first box, which holds the @sc{car} of the first
- cons cell, refers to or holds @code{rose} (a symbol). The second
- box, holding the @sc{cdr} of the first cons cell, refers to the next
- pair of boxes, the second cons cell. The @sc{car} of the second cons
- cell is @code{violet}, and its @sc{cdr} is the third cons cell. The
- @sc{cdr} of the third (and last) cons cell is @code{nil}.
- Here is another diagram of the same list, @code{(rose violet
- buttercup)}, sketched in a different manner:
- @smallexample
- @group
- --------------- ---------------- -------------------
- | car | cdr | | car | cdr | | car | cdr |
- | rose | o-------->| violet | o-------->| buttercup | nil |
- | | | | | | | | |
- --------------- ---------------- -------------------
- @end group
- @end smallexample
- @cindex @code{nil} as a list
- @cindex empty list
- A list with no elements in it is the @dfn{empty list}; it is identical
- to the symbol @code{nil}. In other words, @code{nil} is both a symbol
- and a list.
- Here is the list @code{(A ())}, or equivalently @code{(A nil)},
- depicted with boxes and arrows:
- @example
- @group
- --- --- --- ---
- | | |--> | | |--> nil
- --- --- --- ---
- | |
- | |
- --> A --> nil
- @end group
- @end example
- Here is a more complex illustration, showing the three-element list,
- @code{((pine needles) oak maple)}, the first element of which is a
- two-element list:
- @example
- @group
- --- --- --- --- --- ---
- | | |--> | | |--> | | |--> nil
- --- --- --- --- --- ---
- | | |
- | | |
- | --> oak --> maple
- |
- | --- --- --- ---
- --> | | |--> | | |--> nil
- --- --- --- ---
- | |
- | |
- --> pine --> needles
- @end group
- @end example
- The same list represented in the second box notation looks like this:
- @example
- @group
- -------------- -------------- --------------
- | car | cdr | | car | cdr | | car | cdr |
- | o | o------->| oak | o------->| maple | nil |
- | | | | | | | | | |
- -- | --------- -------------- --------------
- |
- |
- | -------------- ----------------
- | | car | cdr | | car | cdr |
- ------>| pine | o------->| needles | nil |
- | | | | | |
- -------------- ----------------
- @end group
- @end example
- @node Dotted Pair Notation
- @subsubsection Dotted Pair Notation
- @cindex dotted pair notation
- @cindex @samp{.} in lists
- @dfn{Dotted pair notation} is a general syntax for cons cells that
- represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
- @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
- the object @var{a} and whose @sc{cdr} is the object @var{b}. Dotted
- pair notation is more general than list syntax because the @sc{cdr}
- does not have to be a list. However, it is more cumbersome in cases
- where list syntax would work. In dotted pair notation, the list
- @samp{(1 2 3)} is written as @samp{(1 . (2 . (3 . nil)))}. For
- @code{nil}-terminated lists, you can use either notation, but list
- notation is usually clearer and more convenient. When printing a
- list, the dotted pair notation is only used if the @sc{cdr} of a cons
- cell is not a list.
- Here's an example using boxes to illustrate dotted pair notation.
- This example shows the pair @code{(rose . violet)}:
- @example
- @group
- --- ---
- | | |--> violet
- --- ---
- |
- |
- --> rose
- @end group
- @end example
- You can combine dotted pair notation with list notation to represent
- conveniently a chain of cons cells with a non-@code{nil} final @sc{cdr}.
- You write a dot after the last element of the list, followed by the
- @sc{cdr} of the final cons cell. For example, @code{(rose violet
- . buttercup)} is equivalent to @code{(rose . (violet . buttercup))}.
- The object looks like this:
- @example
- @group
- --- --- --- ---
- | | |--> | | |--> buttercup
- --- --- --- ---
- | |
- | |
- --> rose --> violet
- @end group
- @end example
- The syntax @code{(rose .@: violet .@: buttercup)} is invalid because
- there is nothing that it could mean. If anything, it would say to put
- @code{buttercup} in the @sc{cdr} of a cons cell whose @sc{cdr} is already
- used for @code{violet}.
- The list @code{(rose violet)} is equivalent to @code{(rose . (violet))},
- and looks like this:
- @example
- @group
- --- --- --- ---
- | | |--> | | |--> nil
- --- --- --- ---
- | |
- | |
- --> rose --> violet
- @end group
- @end example
- Similarly, the three-element list @code{(rose violet buttercup)}
- is equivalent to @code{(rose . (violet . (buttercup)))}.
- @ifnottex
- It looks like this:
- @example
- @group
- --- --- --- --- --- ---
- | | |--> | | |--> | | |--> nil
- --- --- --- --- --- ---
- | | |
- | | |
- --> rose --> violet --> buttercup
- @end group
- @end example
- @end ifnottex
- @node Association List Type
- @subsubsection Association List Type
- An @dfn{association list} or @dfn{alist} is a specially-constructed
- list whose elements are cons cells. In each element, the @sc{car} is
- considered a @dfn{key}, and the @sc{cdr} is considered an
- @dfn{associated value}. (In some cases, the associated value is stored
- in the @sc{car} of the @sc{cdr}.) Association lists are often used as
- stacks, since it is easy to add or remove associations at the front of
- the list.
- For example,
- @example
- (setq alist-of-colors
- '((rose . red) (lily . white) (buttercup . yellow)))
- @end example
- @noindent
- sets the variable @code{alist-of-colors} to an alist of three elements. In the
- first element, @code{rose} is the key and @code{red} is the value.
- @xref{Association Lists}, for a further explanation of alists and for
- functions that work on alists. @xref{Hash Tables}, for another kind of
- lookup table, which is much faster for handling a large number of keys.
- @node Array Type
- @subsection Array Type
- An @dfn{array} is composed of an arbitrary number of slots for
- holding or referring to other Lisp objects, arranged in a contiguous block of
- memory. Accessing any element of an array takes approximately the same
- amount of time. In contrast, accessing an element of a list requires
- time proportional to the position of the element in the list. (Elements
- at the end of a list take longer to access than elements at the
- beginning of a list.)
- Emacs defines four types of array: strings, vectors, bool-vectors, and
- char-tables.
- A string is an array of characters and a vector is an array of
- arbitrary objects. A bool-vector can hold only @code{t} or @code{nil}.
- These kinds of array may have any length up to the largest integer.
- Char-tables are sparse arrays indexed by any valid character code; they
- can hold arbitrary objects.
- The first element of an array has index zero, the second element has
- index 1, and so on. This is called @dfn{zero-origin} indexing. For
- example, an array of four elements has indices 0, 1, 2, @w{and 3}. The
- largest possible index value is one less than the length of the array.
- Once an array is created, its length is fixed.
- All Emacs Lisp arrays are one-dimensional. (Most other programming
- languages support multidimensional arrays, but they are not essential;
- you can get the same effect with nested one-dimensional arrays.) Each
- type of array has its own read syntax; see the following sections for
- details.
- The array type is a subset of the sequence type, and contains the
- string type, the vector type, the bool-vector type, and the char-table
- type.
- @node String Type
- @subsection String Type
- A @dfn{string} is an array of characters. Strings are used for many
- purposes in Emacs, as can be expected in a text editor; for example, as
- the names of Lisp symbols, as messages for the user, and to represent
- text extracted from buffers. Strings in Lisp are constants: evaluation
- of a string returns the same string.
- @xref{Strings and Characters}, for functions that operate on strings.
- @menu
- * Syntax for Strings:: How to specify Lisp strings.
- * Non-ASCII in Strings:: International characters in strings.
- * Nonprinting Characters:: Literal unprintable characters in strings.
- * Text Props and Strings:: Strings with text properties.
- @end menu
- @node Syntax for Strings
- @subsubsection Syntax for Strings
- @cindex @samp{"} in strings
- @cindex double-quote in strings
- @cindex @samp{\} in strings
- @cindex backslash in strings
- The read syntax for a string is a double-quote, an arbitrary number
- of characters, and another double-quote, @code{"like this"}. To
- include a double-quote in a string, precede it with a backslash; thus,
- @code{"\""} is a string containing just one double-quote
- character. Likewise, you can include a backslash by preceding it with
- another backslash, like this: @code{"this \\ is a single embedded
- backslash"}.
- @cindex newline in strings
- The newline character is not special in the read syntax for strings;
- if you write a new line between the double-quotes, it becomes a
- character in the string. But an escaped newline---one that is preceded
- by @samp{\}---does not become part of the string; i.e., the Lisp reader
- ignores an escaped newline while reading a string. An escaped space
- @w{@samp{\ }} is likewise ignored.
- @example
- "It is useful to include newlines
- in documentation strings,
- but the newline is \
- ignored if escaped."
- @result{} "It is useful to include newlines
- in documentation strings,
- but the newline is ignored if escaped."
- @end example
- @node Non-ASCII in Strings
- @subsubsection Non-@acronym{ASCII} Characters in Strings
- There are two text representations for non-@acronym{ASCII}
- characters in Emacs strings: multibyte and unibyte (@pxref{Text
- Representations}). Roughly speaking, unibyte strings store raw bytes,
- while multibyte strings store human-readable text. Each character in
- a unibyte string is a byte, i.e., its value is between 0 and 255. By
- contrast, each character in a multibyte string may have a value
- between 0 to 4194303 (@pxref{Character Type}). In both cases,
- characters above 127 are non-@acronym{ASCII}.
- You can include a non-@acronym{ASCII} character in a string constant
- by writing it literally. If the string constant is read from a
- multibyte source, such as a multibyte buffer or string, or a file that
- would be visited as multibyte, then Emacs reads each
- non-@acronym{ASCII} character as a multibyte character and
- automatically makes the string a multibyte string. If the string
- constant is read from a unibyte source, then Emacs reads the
- non-@acronym{ASCII} character as unibyte, and makes the string
- unibyte.
- Instead of writing a character literally into a multibyte string,
- you can write it as its character code using an escape sequence.
- @xref{General Escape Syntax}, for details about escape sequences.
- If you use any Unicode-style escape sequence @samp{\uNNNN} or
- @samp{\U00NNNNNN} in a string constant (even for an @acronym{ASCII}
- character), Emacs automatically assumes that it is multibyte.
- You can also use hexadecimal escape sequences (@samp{\x@var{n}}) and
- octal escape sequences (@samp{\@var{n}}) in string constants.
- @strong{But beware:} If a string constant contains hexadecimal or
- octal escape sequences, and these escape sequences all specify unibyte
- characters (i.e., less than 256), and there are no other literal
- non-@acronym{ASCII} characters or Unicode-style escape sequences in
- the string, then Emacs automatically assumes that it is a unibyte
- string. That is to say, it assumes that all non-@acronym{ASCII}
- characters occurring in the string are 8-bit raw bytes.
- In hexadecimal and octal escape sequences, the escaped character
- code may contain a variable number of digits, so the first subsequent
- character which is not a valid hexadecimal or octal digit terminates
- the escape sequence. If the next character in a string could be
- interpreted as a hexadecimal or octal digit, write @w{@samp{\ }}
- (backslash and space) to terminate the escape sequence. For example,
- @w{@samp{\xe0\ }} represents one character, @samp{a} with grave
- accent. @w{@samp{\ }} in a string constant is just like
- backslash-newline; it does not contribute any character to the string,
- but it does terminate any preceding hex escape.
- @node Nonprinting Characters
- @subsubsection Nonprinting Characters in Strings
- You can use the same backslash escape-sequences in a string constant
- as in character literals (but do not use the question mark that begins a
- character constant). For example, you can write a string containing the
- nonprinting characters tab and @kbd{C-a}, with commas and spaces between
- them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a
- description of the read syntax for characters.
- However, not all of the characters you can write with backslash
- escape-sequences are valid in strings. The only control characters that
- a string can hold are the @acronym{ASCII} control characters. Strings do not
- distinguish case in @acronym{ASCII} control characters.
- Properly speaking, strings cannot hold meta characters; but when a
- string is to be used as a key sequence, there is a special convention
- that provides a way to represent meta versions of @acronym{ASCII}
- characters in a string. If you use the @samp{\M-} syntax to indicate
- a meta character in a string constant, this sets the
- @tex
- @math{2^{7}}
- @end tex
- @ifnottex
- 2**7
- @end ifnottex
- bit of the character in the string. If the string is used in
- @code{define-key} or @code{lookup-key}, this numeric code is translated
- into the equivalent meta character. @xref{Character Type}.
- Strings cannot hold characters that have the hyper, super, or alt
- modifiers.
- @node Text Props and Strings
- @subsubsection Text Properties in Strings
- @cindex @samp{#(} read syntax
- @cindex text properties, read syntax
- A string can hold properties for the characters it contains, in
- addition to the characters themselves. This enables programs that copy
- text between strings and buffers to copy the text's properties with no
- special effort. @xref{Text Properties}, for an explanation of what text
- properties mean. Strings with text properties use a special read and
- print syntax:
- @example
- #("@var{characters}" @var{property-data}...)
- @end example
- @noindent
- where @var{property-data} consists of zero or more elements, in groups
- of three as follows:
- @example
- @var{beg} @var{end} @var{plist}
- @end example
- @noindent
- The elements @var{beg} and @var{end} are integers, and together specify
- a range of indices in the string; @var{plist} is the property list for
- that range. For example,
- @example
- #("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))
- @end example
- @noindent
- represents a string whose textual contents are @samp{foo bar}, in which
- the first three characters have a @code{face} property with value
- @code{bold}, and the last three have a @code{face} property with value
- @code{italic}. (The fourth character has no text properties, so its
- property list is @code{nil}. It is not actually necessary to mention
- ranges with @code{nil} as the property list, since any characters not
- mentioned in any range will default to having no properties.)
- @node Vector Type
- @subsection Vector Type
- A @dfn{vector} is a one-dimensional array of elements of any type. It
- takes a constant amount of time to access any element of a vector. (In
- a list, the access time of an element is proportional to the distance of
- the element from the beginning of the list.)
- The printed representation of a vector consists of a left square
- bracket, the elements, and a right square bracket. This is also the
- read syntax. Like numbers and strings, vectors are considered constants
- for evaluation.
- @example
- [1 "two" (three)] ; @r{A vector of three elements.}
- @result{} [1 "two" (three)]
- @end example
- @xref{Vectors}, for functions that work with vectors.
- @node Char-Table Type
- @subsection Char-Table Type
- A @dfn{char-table} is a one-dimensional array of elements of any type,
- indexed by character codes. Char-tables have certain extra features to
- make them more useful for many jobs that involve assigning information
- to character codes---for example, a char-table can have a parent to
- inherit from, a default value, and a small number of extra slots to use for
- special purposes. A char-table can also specify a single value for
- a whole character set.
- @cindex @samp{#^} read syntax
- The printed representation of a char-table is like a vector
- except that there is an extra @samp{#^} at the beginning.@footnote{You
- may also encounter @samp{#^^}, used for sub-char-tables.}
- @xref{Char-Tables}, for special functions to operate on char-tables.
- Uses of char-tables include:
- @itemize @bullet
- @item
- Case tables (@pxref{Case Tables}).
- @item
- Character category tables (@pxref{Categories}).
- @item
- Display tables (@pxref{Display Tables}).
- @item
- Syntax tables (@pxref{Syntax Tables}).
- @end itemize
- @node Bool-Vector Type
- @subsection Bool-Vector Type
- A @dfn{bool-vector} is a one-dimensional array whose elements must
- be @code{t} or @code{nil}.
- The printed representation of a bool-vector is like a string, except
- that it begins with @samp{#&} followed by the length. The string
- constant that follows actually specifies the contents of the bool-vector
- as a bitmap---each character in the string contains 8 bits, which
- specify the next 8 elements of the bool-vector (1 stands for @code{t},
- and 0 for @code{nil}). The least significant bits of the character
- correspond to the lowest indices in the bool-vector.
- @example
- (make-bool-vector 3 t)
- @result{} #&3"^G"
- (make-bool-vector 3 nil)
- @result{} #&3"^@@"
- @end example
- @noindent
- These results make sense, because the binary code for @samp{C-g} is
- 111 and @samp{C-@@} is the character with code 0.
- If the length is not a multiple of 8, the printed representation
- shows extra elements, but these extras really make no difference. For
- instance, in the next example, the two bool-vectors are equal, because
- only the first 3 bits are used:
- @example
- (equal #&3"\377" #&3"\007")
- @result{} t
- @end example
- @node Hash Table Type
- @subsection Hash Table Type
- A hash table is a very fast kind of lookup table, somewhat like an
- alist in that it maps keys to corresponding values, but much faster.
- The printed representation of a hash table specifies its properties
- and contents, like this:
- @example
- (make-hash-table)
- @result{} #s(hash-table size 65 test eql rehash-size 1.5
- rehash-threshold 0.8 data ())
- @end example
- @noindent
- @xref{Hash Tables}, for more information about hash tables.
- @node Function Type
- @subsection Function Type
- Lisp functions are executable code, just like functions in other
- programming languages. In Lisp, unlike most languages, functions are
- also Lisp objects. A non-compiled function in Lisp is a lambda
- expression: that is, a list whose first element is the symbol
- @code{lambda} (@pxref{Lambda Expressions}).
- In most programming languages, it is impossible to have a function
- without a name. In Lisp, a function has no intrinsic name. A lambda
- expression can be called as a function even though it has no name; to
- emphasize this, we also call it an @dfn{anonymous function}
- (@pxref{Anonymous Functions}). A named function in Lisp is just a
- symbol with a valid function in its function cell (@pxref{Defining
- Functions}).
- Most of the time, functions are called when their names are written in
- Lisp expressions in Lisp programs. However, you can construct or obtain
- a function object at run time and then call it with the primitive
- functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
- @node Macro Type
- @subsection Macro Type
- A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
- language. It is represented as an object much like a function, but with
- different argument-passing semantics. A Lisp macro has the form of a
- list whose first element is the symbol @code{macro} and whose @sc{cdr}
- is a Lisp function object, including the @code{lambda} symbol.
- Lisp macro objects are usually defined with the built-in
- @code{defmacro} macro, but any list that begins with @code{macro} is a
- macro as far as Emacs is concerned. @xref{Macros}, for an explanation
- of how to write a macro.
- @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard
- Macros}) are entirely different things. When we use the word ``macro''
- without qualification, we mean a Lisp macro, not a keyboard macro.
- @node Primitive Function Type
- @subsection Primitive Function Type
- @cindex primitive function
- A @dfn{primitive function} is a function callable from Lisp but
- written in the C programming language. Primitive functions are also
- called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
- derived from ``subroutine''.) Most primitive functions evaluate all
- their arguments when they are called. A primitive function that does
- not evaluate all its arguments is called a @dfn{special form}
- (@pxref{Special Forms}).
- It does not matter to the caller of a function whether the function is
- primitive. However, this does matter if you try to redefine a primitive
- with a function written in Lisp. The reason is that the primitive
- function may be called directly from C code. Calls to the redefined
- function from Lisp will use the new definition, but calls from C code
- may still use the built-in definition. Therefore, @strong{we discourage
- redefinition of primitive functions}.
- The term @dfn{function} refers to all Emacs functions, whether written
- in Lisp or C@. @xref{Function Type}, for information about the
- functions written in Lisp.
- Primitive functions have no read syntax and print in hash notation
- with the name of the subroutine.
- @example
- @group
- (symbol-function 'car) ; @r{Access the function cell}
- ; @r{of the symbol.}
- @result{} #<subr car>
- (subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
- @result{} t ; @r{Yes.}
- @end group
- @end example
- @node Byte-Code Type
- @subsection Byte-Code Function Type
- @dfn{Byte-code function objects} are produced by byte-compiling Lisp
- code (@pxref{Byte Compilation}). Internally, a byte-code function
- object is much like a vector; however, the evaluator handles this data
- type specially when it appears in a function call. @xref{Byte-Code
- Objects}.
- The printed representation and read syntax for a byte-code function
- object is like that for a vector, with an additional @samp{#} before the
- opening @samp{[}.
- @node Autoload Type
- @subsection Autoload Type
- An @dfn{autoload object} is a list whose first element is the symbol
- @code{autoload}. It is stored as the function definition of a symbol,
- where it serves as a placeholder for the real definition. The autoload
- object says that the real definition is found in a file of Lisp code
- that should be loaded when necessary. It contains the name of the file,
- plus some other information about the real definition.
- After the file has been loaded, the symbol should have a new function
- definition that is not an autoload object. The new definition is then
- called as if it had been there to begin with. From the user's point of
- view, the function call works as expected, using the function definition
- in the loaded file.
- An autoload object is usually created with the function
- @code{autoload}, which stores the object in the function cell of a
- symbol. @xref{Autoload}, for more details.
- @node Finalizer Type
- @subsection Finalizer Type
- A @dfn{finalizer object} helps Lisp code clean up after objects that
- are no longer needed. A finalizer holds a Lisp function object.
- When a finalizer object becomes unreachable after a garbage collection
- pass, Emacs calls the finalizer's associated function object.
- When deciding whether a finalizer is reachable, Emacs does not count
- references from finalizer objects themselves, allowing you to use
- finalizers without having to worry about accidentally capturing
- references to finalized objects themselves.
- Errors in finalizers are printed to @code{*Messages*}. Emacs runs
- a given finalizer object's associated function exactly once, even
- if that function fails.
- @defun make-finalizer function
- Make a finalizer that will run @var{function}. @var{function} will be
- called after garbage collection when the returned finalizer object
- becomes unreachable. If the finalizer object is reachable only
- through references from finalizer objects, it does not count as
- reachable for the purpose of deciding whether to run @var{function}.
- @var{function} will be run once per finalizer object.
- @end defun
- @node Editing Types
- @section Editing Types
- @cindex editing types
- The types in the previous section are used for general programming
- purposes, and most of them are common to most Lisp dialects. Emacs Lisp
- provides several additional data types for purposes connected with
- editing.
- @menu
- * Buffer Type:: The basic object of editing.
- * Marker Type:: A position in a buffer.
- * Window Type:: Buffers are displayed in windows.
- * Frame Type:: Windows subdivide frames.
- * Terminal Type:: A terminal device displays frames.
- * Window Configuration Type:: Recording the way a frame is subdivided.
- * Frame Configuration Type:: Recording the status of all frames.
- * Process Type:: A subprocess of Emacs running on the underlying OS.
- * Stream Type:: Receive or send characters.
- * Keymap Type:: What function a keystroke invokes.
- * Overlay Type:: How an overlay is represented.
- * Font Type:: Fonts for displaying text.
- @end menu
- @node Buffer Type
- @subsection Buffer Type
- A @dfn{buffer} is an object that holds text that can be edited
- (@pxref{Buffers}). Most buffers hold the contents of a disk file
- (@pxref{Files}) so they can be edited, but some are used for other
- purposes. Most buffers are also meant to be seen by the user, and
- therefore displayed, at some time, in a window (@pxref{Windows}). But
- a buffer need not be displayed in any window. Each buffer has a
- designated position called @dfn{point} (@pxref{Positions}); most
- editing commands act on the contents of the current buffer in the
- neighborhood of point. At any time, one buffer is the @dfn{current
- buffer}.
- The contents of a buffer are much like a string, but buffers are not
- used like strings in Emacs Lisp, and the available operations are
- different. For example, you can insert text efficiently into an
- existing buffer, altering the buffer's contents, whereas inserting
- text into a string requires concatenating substrings, and the result
- is an entirely new string object.
- Many of the standard Emacs functions manipulate or test the
- characters in the current buffer; a whole chapter in this manual is
- devoted to describing these functions (@pxref{Text}).
- Several other data structures are associated with each buffer:
- @itemize @bullet
- @item
- a local syntax table (@pxref{Syntax Tables});
- @item
- a local keymap (@pxref{Keymaps}); and,
- @item
- a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}).
- @item
- overlays (@pxref{Overlays}).
- @item
- text properties for the text in the buffer (@pxref{Text Properties}).
- @end itemize
- @noindent
- The local keymap and variable list contain entries that individually
- override global bindings or values. These are used to customize the
- behavior of programs in different buffers, without actually changing the
- programs.
- A buffer may be @dfn{indirect}, which means it shares the text
- of another buffer, but presents it differently. @xref{Indirect Buffers}.
- Buffers have no read syntax. They print in hash notation, showing the
- buffer name.
- @example
- @group
- (current-buffer)
- @result{} #<buffer objects.texi>
- @end group
- @end example
- @node Marker Type
- @subsection Marker Type
- A @dfn{marker} denotes a position in a specific buffer. Markers
- therefore have two components: one for the buffer, and one for the
- position. Changes in the buffer's text automatically relocate the
- position value as necessary to ensure that the marker always points
- between the same two characters in the buffer.
- Markers have no read syntax. They print in hash notation, giving the
- current character position and the name of the buffer.
- @example
- @group
- (point-marker)
- @result{} #<marker at 10779 in objects.texi>
- @end group
- @end example
- @xref{Markers}, for information on how to test, create, copy, and move
- markers.
- @node Window Type
- @subsection Window Type
- A @dfn{window} describes the portion of the terminal screen that Emacs
- uses to display a buffer. Every window has one associated buffer, whose
- contents appear in the window. By contrast, a given buffer may appear
- in one window, no window, or several windows.
- Though many windows may exist simultaneously, at any time one window
- is designated the @dfn{selected window}. This is the window where the
- cursor is (usually) displayed when Emacs is ready for a command. The
- selected window usually displays the current buffer (@pxref{Current
- Buffer}), but this is not necessarily the case.
- Windows are grouped on the screen into frames; each window belongs to
- one and only one frame. @xref{Frame Type}.
- Windows have no read syntax. They print in hash notation, giving the
- window number and the name of the buffer being displayed. The window
- numbers exist to identify windows uniquely, since the buffer displayed
- in any given window can change frequently.
- @example
- @group
- (selected-window)
- @result{} #<window 1 on objects.texi>
- @end group
- @end example
- @xref{Windows}, for a description of the functions that work on windows.
- @node Frame Type
- @subsection Frame Type
- A @dfn{frame} is a screen area that contains one or more Emacs
- windows; we also use the term ``frame'' to refer to the Lisp object
- that Emacs uses to refer to the screen area.
- Frames have no read syntax. They print in hash notation, giving the
- frame's title, plus its address in core (useful to identify the frame
- uniquely).
- @example
- @group
- (selected-frame)
- @result{} #<frame emacs@@psilocin.gnu.org 0xdac80>
- @end group
- @end example
- @xref{Frames}, for a description of the functions that work on frames.
- @node Terminal Type
- @subsection Terminal Type
- @cindex terminal type
- A @dfn{terminal} is a device capable of displaying one or more
- Emacs frames (@pxref{Frame Type}).
- Terminals have no read syntax. They print in hash notation giving
- the terminal's ordinal number and its TTY device file name.
- @example
- @group
- (get-device-terminal nil)
- @result{} #<terminal 1 on /dev/tty>
- @end group
- @end example
- @c FIXME: add an xref to where terminal-related primitives are described.
- @node Window Configuration Type
- @subsection Window Configuration Type
- @cindex window layout in a frame
- A @dfn{window configuration} stores information about the positions,
- sizes, and contents of the windows in a frame, so you can recreate the
- same arrangement of windows later.
- Window configurations do not have a read syntax; their print syntax
- looks like @samp{#<window-configuration>}. @xref{Window
- Configurations}, for a description of several functions related to
- window configurations.
- @node Frame Configuration Type
- @subsection Frame Configuration Type
- @cindex screen layout
- @cindex window layout, all frames
- A @dfn{frame configuration} stores information about the positions,
- sizes, and contents of the windows in all frames. It is not a
- primitive type---it is actually a list whose @sc{car} is
- @code{frame-configuration} and whose @sc{cdr} is an alist. Each alist
- element describes one frame, which appears as the @sc{car} of that
- element.
- @xref{Frame Configurations}, for a description of several functions
- related to frame configurations.
- @node Process Type
- @subsection Process Type
- The word @dfn{process} usually means a running program. Emacs itself
- runs in a process of this sort. However, in Emacs Lisp, a process is a
- Lisp object that designates a subprocess created by the Emacs process.
- Programs such as shells, GDB, ftp, and compilers, running in
- subprocesses of Emacs, extend the capabilities of Emacs.
- An Emacs subprocess takes textual input from Emacs and returns textual
- output to Emacs for further manipulation. Emacs can also send signals
- to the subprocess.
- Process objects have no read syntax. They print in hash notation,
- giving the name of the process:
- @example
- @group
- (process-list)
- @result{} (#<process shell>)
- @end group
- @end example
- @xref{Processes}, for information about functions that create, delete,
- return information about, send input or signals to, and receive output
- from processes.
- @node Stream Type
- @subsection Stream Type
- A @dfn{stream} is an object that can be used as a source or sink for
- characters---either to supply characters for input or to accept them as
- output. Many different types can be used this way: markers, buffers,
- strings, and functions. Most often, input streams (character sources)
- obtain characters from the keyboard, a buffer, or a file, and output
- streams (character sinks) send characters to a buffer, such as a
- @file{*Help*} buffer, or to the echo area.
- The object @code{nil}, in addition to its other meanings, may be used
- as a stream. It stands for the value of the variable
- @code{standard-input} or @code{standard-output}. Also, the object
- @code{t} as a stream specifies input using the minibuffer
- (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
- Area}).
- Streams have no special printed representation or read syntax, and
- print as whatever primitive type they are.
- @xref{Read and Print}, for a description of functions
- related to streams, including parsing and printing functions.
- @node Keymap Type
- @subsection Keymap Type
- A @dfn{keymap} maps keys typed by the user to commands. This mapping
- controls how the user's command input is executed. A keymap is actually
- a list whose @sc{car} is the symbol @code{keymap}.
- @xref{Keymaps}, for information about creating keymaps, handling prefix
- keys, local as well as global keymaps, and changing key bindings.
- @node Overlay Type
- @subsection Overlay Type
- An @dfn{overlay} specifies properties that apply to a part of a
- buffer. Each overlay applies to a specified range of the buffer, and
- contains a property list (a list whose elements are alternating property
- names and values). Overlay properties are used to present parts of the
- buffer temporarily in a different display style. Overlays have no read
- syntax, and print in hash notation, giving the buffer name and range of
- positions.
- @xref{Overlays}, for information on how you can create and use overlays.
- @node Font Type
- @subsection Font Type
- A @dfn{font} specifies how to display text on a graphical terminal.
- There are actually three separate font types---@dfn{font objects},
- @dfn{font specs}, and @dfn{font entities}---each of which has slightly
- different properties. None of them have a read syntax; their print
- syntax looks like @samp{#<font-object>}, @samp{#<font-spec>}, and
- @samp{#<font-entity>} respectively. @xref{Low-Level Font}, for a
- description of these Lisp objects.
- @node Circular Objects
- @section Read Syntax for Circular Objects
- @cindex circular structure, read syntax
- @cindex shared structure, read syntax
- @cindex @samp{#@var{n}=} read syntax
- @cindex @samp{#@var{n}#} read syntax
- To represent shared or circular structures within a complex of Lisp
- objects, you can use the reader constructs @samp{#@var{n}=} and
- @samp{#@var{n}#}.
- Use @code{#@var{n}=} before an object to label it for later reference;
- subsequently, you can use @code{#@var{n}#} to refer the same object in
- another place. Here, @var{n} is some integer. For example, here is how
- to make a list in which the first element recurs as the third element:
- @example
- (#1=(a) b #1#)
- @end example
- @noindent
- This differs from ordinary syntax such as this
- @example
- ((a) b (a))
- @end example
- @noindent
- which would result in a list whose first and third elements
- look alike but are not the same Lisp object. This shows the difference:
- @example
- (prog1 nil
- (setq x '(#1=(a) b #1#)))
- (eq (nth 0 x) (nth 2 x))
- @result{} t
- (setq x '((a) b (a)))
- (eq (nth 0 x) (nth 2 x))
- @result{} nil
- @end example
- You can also use the same syntax to make a circular structure, which
- appears as an element within itself. Here is an example:
- @example
- #1=(a #1#)
- @end example
- @noindent
- This makes a list whose second element is the list itself.
- Here's how you can see that it really works:
- @example
- (prog1 nil
- (setq x '#1=(a #1#)))
- (eq x (cadr x))
- @result{} t
- @end example
- The Lisp printer can produce this syntax to record circular and shared
- structure in a Lisp object, if you bind the variable @code{print-circle}
- to a non-@code{nil} value. @xref{Output Variables}.
- @node Type Predicates
- @section Type Predicates
- @cindex type checking
- @kindex wrong-type-argument
- The Emacs Lisp interpreter itself does not perform type checking on
- the actual arguments passed to functions when they are called. It could
- not do so, since function arguments in Lisp do not have declared data
- types, as they do in other programming languages. It is therefore up to
- the individual function to test whether each actual argument belongs to
- a type that the function can use.
- All built-in functions do check the types of their actual arguments
- when appropriate, and signal a @code{wrong-type-argument} error if an
- argument is of the wrong type. For example, here is what happens if you
- pass an argument to @code{+} that it cannot handle:
- @example
- @group
- (+ 2 'a)
- @error{} Wrong type argument: number-or-marker-p, a
- @end group
- @end example
- @cindex type predicates
- @cindex testing types
- If you want your program to handle different types differently, you
- must do explicit type checking. The most common way to check the type
- of an object is to call a @dfn{type predicate} function. Emacs has a
- type predicate for each type, as well as some predicates for
- combinations of types.
- A type predicate function takes one argument; it returns @code{t} if
- the argument belongs to the appropriate type, and @code{nil} otherwise.
- Following a general Lisp convention for predicate functions, most type
- predicates' names end with @samp{p}.
- Here is an example which uses the predicates @code{listp} to check for
- a list and @code{symbolp} to check for a symbol.
- @example
- (defun add-on (x)
- (cond ((symbolp x)
- ;; If X is a symbol, put it on LIST.
- (setq list (cons x list)))
- ((listp x)
- ;; If X is a list, add its elements to LIST.
- (setq list (append x list)))
- (t
- ;; We handle only symbols and lists.
- (error "Invalid argument %s in add-on" x))))
- @end example
- Here is a table of predefined type predicates, in alphabetical order,
- with references to further information.
- @table @code
- @item atom
- @xref{List-related Predicates, atom}.
- @item arrayp
- @xref{Array Functions, arrayp}.
- @item bool-vector-p
- @xref{Bool-Vectors, bool-vector-p}.
- @item bufferp
- @xref{Buffer Basics, bufferp}.
- @item byte-code-function-p
- @xref{Byte-Code Type, byte-code-function-p}.
- @item case-table-p
- @xref{Case Tables, case-table-p}.
- @item char-or-string-p
- @xref{Predicates for Strings, char-or-string-p}.
- @item char-table-p
- @xref{Char-Tables, char-table-p}.
- @item commandp
- @xref{Interactive Call, commandp}.
- @item consp
- @xref{List-related Predicates, consp}.
- @item custom-variable-p
- @xref{Variable Definitions, custom-variable-p}.
- @item floatp
- @xref{Predicates on Numbers, floatp}.
- @item fontp
- @xref{Low-Level Font}.
- @item frame-configuration-p
- @xref{Frame Configurations, frame-configuration-p}.
- @item frame-live-p
- @xref{Deleting Frames, frame-live-p}.
- @item framep
- @xref{Frames, framep}.
- @item functionp
- @xref{Functions, functionp}.
- @item hash-table-p
- @xref{Other Hash, hash-table-p}.
- @item integer-or-marker-p
- @xref{Predicates on Markers, integer-or-marker-p}.
- @item integerp
- @xref{Predicates on Numbers, integerp}.
- @item keymapp
- @xref{Creating Keymaps, keymapp}.
- @item keywordp
- @xref{Constant Variables}.
- @item listp
- @xref{List-related Predicates, listp}.
- @item markerp
- @xref{Predicates on Markers, markerp}.
- @item wholenump
- @xref{Predicates on Numbers, wholenump}.
- @item nlistp
- @xref{List-related Predicates, nlistp}.
- @item numberp
- @xref{Predicates on Numbers, numberp}.
- @item number-or-marker-p
- @xref{Predicates on Markers, number-or-marker-p}.
- @item overlayp
- @xref{Overlays, overlayp}.
- @item processp
- @xref{Processes, processp}.
- @item sequencep
- @xref{Sequence Functions, sequencep}.
- @item stringp
- @xref{Predicates for Strings, stringp}.
- @item subrp
- @xref{Function Cells, subrp}.
- @item symbolp
- @xref{Symbols, symbolp}.
- @item syntax-table-p
- @xref{Syntax Tables, syntax-table-p}.
- @item vectorp
- @xref{Vectors, vectorp}.
- @item window-configuration-p
- @xref{Window Configurations, window-configuration-p}.
- @item window-live-p
- @xref{Deleting Windows, window-live-p}.
- @item windowp
- @xref{Basic Windows, windowp}.
- @item booleanp
- @xref{nil and t, booleanp}.
- @item string-or-null-p
- @xref{Predicates for Strings, string-or-null-p}.
- @end table
- The most general way to check the type of an object is to call the
- function @code{type-of}. Recall that each object belongs to one and
- only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
- Data Types}). But @code{type-of} knows nothing about non-primitive
- types. In most cases, it is more convenient to use type predicates than
- @code{type-of}.
- @defun type-of object
- This function returns a symbol naming the primitive type of
- @var{object}. The value is one of the symbols @code{bool-vector},
- @code{buffer}, @code{char-table}, @code{compiled-function},
- @code{cons}, @code{finalizer}, @code{float}, @code{font-entity},
- @code{font-object}, @code{font-spec}, @code{frame}, @code{hash-table},
- @code{integer}, @code{marker}, @code{overlay}, @code{process},
- @code{string}, @code{subr}, @code{symbol}, @code{vector},
- @code{window}, or @code{window-configuration}.
- @example
- (type-of 1)
- @result{} integer
- @group
- (type-of 'nil)
- @result{} symbol
- (type-of '()) ; @r{@code{()} is @code{nil}.}
- @result{} symbol
- (type-of '(x))
- @result{} cons
- @end group
- @end example
- @end defun
- @node Equality Predicates
- @section Equality Predicates
- @cindex equality
- Here we describe functions that test for equality between two
- objects. Other functions test equality of contents between objects of
- specific types, e.g., strings. For these predicates, see the
- appropriate chapter describing the data type.
- @defun eq object1 object2
- This function returns @code{t} if @var{object1} and @var{object2} are
- the same object, and @code{nil} otherwise.
- If @var{object1} and @var{object2} are integers with the same value,
- they are considered to be the same object (i.e., @code{eq} returns
- @code{t}). If @var{object1} and @var{object2} are symbols with the
- same name, they are normally the same object---but see @ref{Creating
- Symbols} for exceptions. For other types (e.g., lists, vectors,
- strings), two arguments with the same contents or elements are not
- necessarily @code{eq} to each other: they are @code{eq} only if they
- are the same object, meaning that a change in the contents of one will
- be reflected by the same change in the contents of the other.
- @example
- @group
- (eq 'foo 'foo)
- @result{} t
- @end group
- @group
- (eq 456 456)
- @result{} t
- @end group
- @group
- (eq "asdf" "asdf")
- @result{} nil
- @end group
- @group
- (eq "" "")
- @result{} t
- ;; @r{This exception occurs because Emacs Lisp}
- ;; @r{makes just one multibyte empty string, to save space.}
- @end group
- @group
- (eq '(1 (2 (3))) '(1 (2 (3))))
- @result{} nil
- @end group
- @group
- (setq foo '(1 (2 (3))))
- @result{} (1 (2 (3)))
- (eq foo foo)
- @result{} t
- (eq foo '(1 (2 (3))))
- @result{} nil
- @end group
- @group
- (eq [(1 2) 3] [(1 2) 3])
- @result{} nil
- @end group
- @group
- (eq (point-marker) (point-marker))
- @result{} nil
- @end group
- @end example
- @noindent
- The @code{make-symbol} function returns an uninterned symbol, distinct
- from the symbol that is used if you write the name in a Lisp expression.
- Distinct symbols with the same name are not @code{eq}. @xref{Creating
- Symbols}.
- @example
- @group
- (eq (make-symbol "foo") 'foo)
- @result{} nil
- @end group
- @end example
- @end defun
- @defun equal object1 object2
- This function returns @code{t} if @var{object1} and @var{object2} have
- equal components, and @code{nil} otherwise. Whereas @code{eq} tests
- if its arguments are the same object, @code{equal} looks inside
- nonidentical arguments to see if their elements or contents are the
- same. So, if two objects are @code{eq}, they are @code{equal}, but
- the converse is not always true.
- @example
- @group
- (equal 'foo 'foo)
- @result{} t
- @end group
- @group
- (equal 456 456)
- @result{} t
- @end group
- @group
- (equal "asdf" "asdf")
- @result{} t
- @end group
- @group
- (eq "asdf" "asdf")
- @result{} nil
- @end group
- @group
- (equal '(1 (2 (3))) '(1 (2 (3))))
- @result{} t
- @end group
- @group
- (eq '(1 (2 (3))) '(1 (2 (3))))
- @result{} nil
- @end group
- @group
- (equal [(1 2) 3] [(1 2) 3])
- @result{} t
- @end group
- @group
- (eq [(1 2) 3] [(1 2) 3])
- @result{} nil
- @end group
- @group
- (equal (point-marker) (point-marker))
- @result{} t
- @end group
- @group
- (eq (point-marker) (point-marker))
- @result{} nil
- @end group
- @end example
- Comparison of strings is case-sensitive, but does not take account of
- text properties---it compares only the characters in the strings.
- @xref{Text Properties}. Use @code{equal-including-properties} to also
- compare text properties. For technical reasons, a unibyte string and
- a multibyte string are @code{equal} if and only if they contain the
- same sequence of character codes and all these codes are either in the
- range 0 through 127 (@acronym{ASCII}) or 160 through 255
- (@code{eight-bit-graphic}). (@pxref{Text Representations}).
- @example
- @group
- (equal "asdf" "ASDF")
- @result{} nil
- @end group
- @end example
- However, two distinct buffers are never considered @code{equal}, even if
- their textual contents are the same.
- @end defun
- The test for equality is implemented recursively; for example, given
- two cons cells @var{x} and @var{y}, @code{(equal @var{x} @var{y})}
- returns @code{t} if and only if both the expressions below return
- @code{t}:
- @example
- (equal (car @var{x}) (car @var{y}))
- (equal (cdr @var{x}) (cdr @var{y}))
- @end example
- Because of this recursive method, circular lists may therefore cause
- infinite recursion (leading to an error).
- @defun equal-including-properties object1 object2
- This function behaves like @code{equal} in all cases but also requires
- that for two strings to be equal, they have the same text properties.
- @example
- @group
- (equal "asdf" (propertize "asdf" 'asdf t))
- @result{} t
- @end group
- @group
- (equal-including-properties "asdf"
- (propertize "asdf" 'asdf t))
- @result{} nil
- @end group
- @end example
- @end defun
|