X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-7;h=1f075d3c9534edb591e64cfc475cf8f00cfe30e7;hb=fbe115a4387c6e47118c416a9d7d3362ef3f8f4e;hp=780fd807c1d9b79c76371bdcb1292cb9f2a71b91;hpb=430e0db85cc37821320fe27da9feeacc7961003f;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-7 b/info/lispref.info-7 index 780fd80..1f075d3 100644 --- a/info/lispref.info-7 +++ b/info/lispref.info-7 @@ -1,5 +1,5 @@ -This is Info file ../../info/lispref.info, produced by Makeinfo version -1.68 from the input file lispref.texi. +This is ../info/lispref.info, produced by makeinfo version 4.0b from +lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY @@ -60,11 +60,11 @@ vector, or a string. The common property that all sequences have is that each is an ordered collection of elements. This section describes functions that accept any kind of sequence. - - Function: sequencep OBJECT + - Function: sequencep object Returns `t' if OBJECT is a list, vector, bit vector, or string, `nil' otherwise. - - Function: copy-sequence SEQUENCE + - Function: copy-sequence sequence Returns a copy of SEQUENCE. The copy is the same type of object as the original sequence, and it has the same elements in the same order. @@ -115,7 +115,7 @@ functions that accept any kind of sequence. (bit-vector 1 0 1 1 0 1 0 0) => #*10110100 - - Function: length SEQUENCE + - Function: length sequence Returns the number of elements in SEQUENCE. If SEQUENCE is a cons cell that is not a list (because the final CDR is not `nil'), a `wrong-type-argument' error is signaled. @@ -131,7 +131,7 @@ functions that accept any kind of sequence. (length #*01101) => 5 - - Function: elt SEQUENCE INDEX + - Function: elt sequence index This function returns the element of SEQUENCE indexed by INDEX. Legitimate values of INDEX are integers ranging from 0 up to one less than the length of SEQUENCE. If SEQUENCE is a list, then @@ -151,8 +151,8 @@ functions that accept any kind of sequence. (elt [1 2 3 4] -1) error-->Args out of range: [1 2 3 4], -1 - This function generalizes `aref' (*note Array Functions::.) and - `nth' (*note List Elements::.). + This function generalizes `aref' (*note Array Functions::) and + `nth' (*note List Elements::).  File: lispref.info, Node: Arrays, Next: Array Functions, Prev: Sequence Functions, Up: Sequences Arrays Vectors @@ -188,7 +188,7 @@ Type::, *Note Vector Type::, and *Note Bit Vector Type::. * The elements of an array may be referenced or changed with the functions `aref' and `aset', respectively (*note Array - Functions::.). + Functions::). In principle, if you wish to have an array of text characters, you could use either a string or a vector. In practice, we always choose @@ -233,7 +233,7 @@ Functions that Operate on Arrays In this section, we describe the functions that accept strings, vectors, and bit vectors. - - Function: arrayp OBJECT + - Function: arrayp object This function returns `t' if OBJECT is an array (i.e., a string, vector, or bit vector). @@ -244,7 +244,7 @@ vectors, and bit vectors. (arrayp #*101) => t - - Function: aref ARRAY INDEX + - Function: aref array index This function returns the INDEXth element of ARRAY. The first element is at index zero. @@ -263,7 +263,7 @@ vectors, and bit vectors. See also the function `elt', in *Note Sequence Functions::. - - Function: aset ARRAY INDEX OBJECT + - Function: aset array index object This function sets the INDEXth element of ARRAY to be OBJECT. It returns OBJECT. @@ -291,7 +291,7 @@ vectors, and bit vectors. If ARRAY is a string and OBJECT is not a character, a `wrong-type-argument' error results. - - Function: fillarray ARRAY OBJECT + - Function: fillarray array object This function fills the array ARRAY with OBJECT, so that each element of ARRAY is OBJECT. It returns ARRAY. @@ -364,7 +364,7 @@ Functions That Operate on Vectors Here are some functions that relate to vectors: - - Function: vectorp OBJECT + - Function: vectorp object This function returns `t' if OBJECT is a vector. (vectorp [a]) @@ -372,7 +372,7 @@ Functions That Operate on Vectors (vectorp "asdf") => nil - - Function: vector &rest OBJECTS + - Function: vector &rest objects This function creates and returns a vector whose elements are the arguments, OBJECTS. @@ -381,14 +381,14 @@ Functions That Operate on Vectors (vector) => [] - - Function: make-vector LENGTH OBJECT + - Function: make-vector length object This function returns a new vector consisting of LENGTH elements, each initialized to OBJECT. (setq sleepy (make-vector 9 'Z)) => [Z Z Z Z Z Z Z Z Z] - - Function: vconcat &rest SEQUENCES + - Function: vconcat &rest sequences This function returns a new vector containing all the elements of the SEQUENCES. The arguments SEQUENCES may be lists, vectors, or strings. If no SEQUENCES are given, an empty vector is returned. @@ -411,8 +411,8 @@ Functions That Operate on Vectors of the original integers. *Don't use this feature; we plan to eliminate it. If you already use this feature, change your programs now!* The proper way to convert an integer to a decimal - number in this way is with `format' (*note Formatting Strings::.) - or `number-to-string' (*note String Conversion::.). + number in this way is with `format' (*note Formatting Strings::) + or `number-to-string' (*note String Conversion::). For other concatenation functions, see `mapconcat' in *Note Mapping Functions::, `concat' in *Note Creating Strings::, `append' @@ -420,7 +420,7 @@ Functions That Operate on Vectors Functions::. The `append' function provides a way to convert a vector into a list -with the same elements (*note Building Lists::.): +with the same elements (*note Building Lists::): (setq avector [1 two (quote (three)) "four" [five]]) => [1 two (quote (three)) "four" [five]] @@ -458,7 +458,7 @@ Functions That Operate on Bit Vectors Here are some functions that relate to bit vectors: - - Function: bit-vector-p OBJECT + - Function: bit-vector-p object This function returns `t' if OBJECT is a bit vector. (bit-vector-p #*01) @@ -468,27 +468,28 @@ Functions That Operate on Bit Vectors (bit-vector-p "01") => nil - - Function: bitp OBJECT + - Function: bitp object This function returns `t' if OBJECT is either 0 or 1. - - Function: bit-vector &rest OBJECTS + - Function: bit-vector &rest bits This function creates and returns a bit vector whose elements are - the arguments OBJECTS. The elements must be either of the two - integers 0 or 1. + the arguments BITS. Each argument must be a bit, i.e. one of the + two integers 0 or 1. (bit-vector 0 0 0 1 0 0 0 0 1 0) => #*0001000010 (bit-vector) => #* - - Function: make-bit-vector LENGTH OBJECT + - Function: make-bit-vector length bit This function creates and returns a bit vector consisting of - LENGTH elements, each initialized to OBJECT. + LENGTH elements, each initialized to BIT, which must be one of the + two integers 0 or 1. (setq picket-fence (make-bit-vector 9 1)) => #*111111111 - - Function: bvconcat &rest SEQUENCES + - Function: bvconcat &rest sequences This function returns a new bit vector containing all the elements of the SEQUENCES. The arguments SEQUENCES may be lists, vectors, or bit vectors, all of whose elements are the integers 0 or 1. If @@ -512,7 +513,7 @@ Functions That Operate on Bit Vectors Building Lists::. The `append' function provides a way to convert a bit vector into a -list with the same elements (*note Building Lists::.): +list with the same elements (*note Building Lists::): (setq bv #*00001110) => #*00001110 @@ -535,7 +536,7 @@ Type::. You can test whether an arbitrary Lisp object is a symbol with `symbolp': - - Function: symbolp OBJECT + - Function: symbolp object This function returns `t' if OBJECT is a symbol, `nil' otherwise. * Menu: @@ -594,15 +595,15 @@ Symbols::.) In normal usage, the function cell usually contains a function or macro, as that is what the Lisp interpreter expects to see there (*note -Evaluation::.). Keyboard macros (*note Keyboard Macros::.), keymaps -(*note Keymaps::.) and autoload objects (*note Autoloading::.) are also +Evaluation::). Keyboard macros (*note Keyboard Macros::), keymaps +(*note Keymaps::) and autoload objects (*note Autoloading::) are also sometimes stored in the function cell of symbols. We often refer to "the function `foo'" when we really mean the function stored in the function cell of the symbol `foo'. We make the distinction only when necessary. The property list cell normally should hold a correctly formatted -property list (*note Property Lists::.), as a number of functions expect +property list (*note Property Lists::), as a number of functions expect to see a property list there. The function cell or the value cell may be "void", which means that @@ -627,17 +628,17 @@ the symbol `buffer-file-name': Because this symbol is the variable which holds the name of the file being visited in the current buffer, the value cell contents we see are -the name of the source file of this chapter of the XEmacs Lisp Manual. -The property list cell contains the list `(variable-documentation -29529)' which tells the documentation functions where to find the -documentation string for the variable `buffer-file-name' in the `DOC' -file. (29529 is the offset from the beginning of the `DOC' file to -where that documentation string begins.) The function cell contains -the function for returning the name of the file. `buffer-file-name' -names a primitive function, which has no read syntax and prints in hash -notation (*note Primitive Function Type::.). A symbol naming a -function written in Lisp would have a lambda expression (or a byte-code -object) in this cell. +the name of the source file of this chapter of the XEmacs Lisp Reference +Manual. The property list cell contains the list +`(variable-documentation 29529)' which tells the documentation +functions where to find the documentation string for the variable +`buffer-file-name' in the `DOC' file. (29529 is the offset from the +beginning of the `DOC' file to where that documentation string begins.) +The function cell contains the function for returning the name of the +file. `buffer-file-name' names a primitive function, which has no read +syntax and prints in hash notation (*note Primitive Function Type::). A +symbol naming a function written in Lisp would have a lambda expression +(or a byte-code object) in this cell.  File: lispref.info, Node: Definitions, Next: Creating Symbols, Prev: Symbol Components, Up: Symbols @@ -679,7 +680,7 @@ as a variable or function. Thus, you can make a symbol a global variable with `setq', whether you define it first or not. The real purpose of definitions is to guide programmers and programming tools. They inform programmers who read the code that certain symbols are -*intended* to be used as variables, or as functions. In addition, +_intended_ to be used as variables, or as functions. In addition, utilities such as `etags' and `make-docfile' recognize definitions, and add appropriate information to tag tables and the `DOC' file. *Note Accessing Documentation::. @@ -744,7 +745,7 @@ symbol in the obarray bucket. The results would be unpredictable. It is possible for two different symbols to have the same name in different obarrays; these symbols are not `eq' or `equal'. However, this normally happens only as part of the abbrev mechanism (*note -Abbrevs::.). +Abbrevs::). Common Lisp note: In Common Lisp, a single symbol may be interned in several obarrays. @@ -753,7 +754,7 @@ Abbrevs::.). arguments. A `wrong-type-argument' error is signaled if the name is not a string, or if the obarray is not a vector. - - Function: symbol-name SYMBOL + - Function: symbol-name symbol This function returns the string that is SYMBOL's name. For example: @@ -764,7 +765,7 @@ not a string, or if the obarray is not a vector. the name of the symbol, but fails to update the obarray, so don't do it! - - Function: make-symbol NAME + - Function: make-symbol name This function returns a newly-allocated, uninterned symbol whose name is NAME (which must be a string). Its value and function definition are void, and its property list is `nil'. In the @@ -776,7 +777,7 @@ not a string, or if the obarray is not a vector. (eq sym 'foo) => nil - - Function: intern NAME &optional OBARRAY + - Function: intern name &optional obarray This function returns the interned symbol whose name is NAME. If there is no such symbol in the obarray OBARRAY, `intern' creates a new one, adds it to the obarray, and returns it. If OBARRAY is @@ -792,7 +793,7 @@ not a string, or if the obarray is not a vector. (eq sym 'foo) => nil - - Function: intern-soft NAME &optional OBARRAY + - Function: intern-soft name &optional obarray This function returns the symbol in OBARRAY whose name is NAME, or `nil' if OBARRAY has no symbol with that name. Therefore, you can use `intern-soft' to test whether a symbol with a given name is @@ -805,13 +806,10 @@ not a string, or if the obarray is not a vector. => frazzle (intern-soft "frazzle") ; That one cannot be found. => nil - (setq sym (intern "frazzle")) ; Create an interned one. => frazzle - (intern-soft "frazzle") ; That one can be found! => frazzle - (eq sym 'frazzle) ; And it is the same one. => t @@ -819,7 +817,7 @@ not a string, or if the obarray is not a vector. This variable is the standard obarray for use by `intern' and `read'. - - Function: mapatoms FUNCTION &optional OBARRAY + - Function: mapatoms function &optional obarray This function calls FUNCTION for each symbol in the obarray OBARRAY. It returns `nil'. If OBARRAY is omitted, it defaults to the value of `obarray', the standard obarray for ordinary symbols. @@ -837,7 +835,7 @@ not a string, or if the obarray is not a vector. See `documentation' in *Note Accessing Documentation::, for another example using `mapatoms'. - - Function: unintern SYMBOL &optional OBARRAY + - Function: unintern symbol &optional obarray This function deletes SYMBOL from the obarray OBARRAY. If `symbol' is not actually in the obarray, `unintern' does nothing. If OBARRAY is `nil', the current obarray is used. @@ -856,17 +854,17 @@ File: lispref.info, Node: Symbol Properties, Prev: Creating Symbols, Up: Symb Symbol Properties ================= - A "property list" ("plist" for short) is a list of paired elements -stored in the property list cell of a symbol. Each of the pairs + A "property list" ("plist" for short) is a list of paired elements, +often stored in the property list cell of a symbol. Each of the pairs associates a property name (usually a symbol) with a property or value. Property lists are generally used to record information about a symbol, such as its documentation as a variable, the name of the file where it was defined, or perhaps even the grammatical class of the symbol (representing a word) in a language-understanding system. - Many objects other than symbols can have property lists associated -with them, and XEmacs provides a full complement of functions for -working with property lists. *Note Property Lists::. + Some objects which are not symbols also have property lists +associated with them, and XEmacs provides a full complement of +functions for working with property lists. *Note Property Lists::. The property names and values in a property list can be any Lisp objects, but the names are usually symbols. They are compared using @@ -882,16 +880,16 @@ the other two elements are the corresponding values. * Plists and Alists:: Comparison of the advantages of property lists and association lists. -* Symbol Plists:: Functions to access symbols' property lists. +* Object Plists:: Functions to access objects' property lists. * Other Plists:: Accessing property lists stored elsewhere.  -File: lispref.info, Node: Plists and Alists, Next: Symbol Plists, Up: Symbol Properties +File: lispref.info, Node: Plists and Alists, Next: Object Plists, Up: Symbol Properties Property Lists and Association Lists ------------------------------------ - Association lists (*note Association Lists::.) are very similar to + Association lists (*note Association Lists::) are very similar to property lists. In contrast to association lists, the order of the pairs in the property list is not significant since the property names must be distinct. @@ -919,15 +917,23 @@ are pushed on the front of the list and later discarded; this is not possible with a property list.  -File: lispref.info, Node: Symbol Plists, Next: Other Plists, Prev: Plists and Alists, Up: Symbol Properties +File: lispref.info, Node: Object Plists, Next: Other Plists, Prev: Plists and Alists, Up: Symbol Properties -Property List Functions for Symbols +Property List Functions for Objects ----------------------------------- - - Function: symbol-plist SYMBOL + Once upon a time, only symbols had property lists. Now, several +other object types, including strings, extents, faces and glyphs also +have property lists. + + - Function: symbol-plist symbol This function returns the property list of SYMBOL. - - Function: setplist SYMBOL PLIST + - Function: object-plist object + This function returns the property list of OBJECT. If OBJECT is a + symbol, this is identical to `symbol-plist'. + + - Function: setplist symbol plist This function sets SYMBOL's property list to PLIST. Normally, PLIST should be a well-formed property list, but this is not enforced. @@ -940,21 +946,22 @@ Property List Functions for Symbols For symbols in special obarrays, which are not used for ordinary purposes, it may make sense to use the property list cell in a nonstandard fashion; in fact, the abbrev mechanism does so (*note - Abbrevs::.). + Abbrevs::). But generally, its use is discouraged. Use `put' + instead. `setplist' can only be used with symbols, not other + object types. - - Function: get SYMBOL PROPERTY + - Function: get object property &optional default This function finds the value of the property named PROPERTY in - SYMBOL's property list. If there is no such property, `nil' is - returned. Thus, there is no distinction between a value of `nil' - and the absence of the property. + OBJECT's property list. If there is no such property, `default' + (which itself defaults to `nil') is returned. - The name PROPERTY is compared with the existing property names - using `eq', so any object is a legitimate property. + PROPERTY is compared with the existing properties using `eq', so + any object is a legitimate property. See `put' for an example. - - Function: put SYMBOL PROPERTY VALUE - This function puts VALUE onto SYMBOL's property list under the + - Function: put object property value + This function puts VALUE onto OBJECT's property list under the property name PROPERTY, replacing any previous property value. The `put' function returns VALUE. @@ -964,26 +971,36 @@ Property List Functions for Symbols => (a buzzing little bug) (get 'fly 'verb) => transitive - (symbol-plist 'fly) + (object-plist 'fly) => (verb transitive noun (a buzzing little bug)) + - Function: remprop object property + This function removes the entry for PROPERTY from the property + list of OBJECT. It returns `t' if the property was indeed found + and removed, or `nil' if there was no such property. (This + function was probably omitted from Emacs originally because, since + `get' did not allow a DEFAULT, it was very difficult to + distinguish between a missing property and a property whose value + was `nil'; thus, setting a property to `nil' was close enough to + `remprop' for most purposes.) +  -File: lispref.info, Node: Other Plists, Prev: Symbol Plists, Up: Symbol Properties +File: lispref.info, Node: Other Plists, Prev: Object Plists, Up: Symbol Properties -Property Lists Outside Symbols ------------------------------- +Property Lists Not Associated with Objects +------------------------------------------ These functions are useful for manipulating property lists that are stored in places other than symbols: - - Function: getf PLIST PROPERTY &optional DEFAULT + - Function: getf plist property &optional default This returns the value of the PROPERTY property stored in the property list PLIST. For example, (getf '(foo 4) 'foo) => 4 - - Function: putf PLIST PROPERTY VALUE + - Macro: putf plist property value This stores VALUE as the value of the PROPERTY property in the property list PLIST. It may modify PLIST destructively, or it may construct a new list structure without altering the old. The @@ -997,13 +1014,13 @@ stored in places other than symbols: (setq my-plist (putf my-plist 'quux '(a))) => (quux (a) bar t foo 5) - - Function: plists-eq A B + - Function: plists-eq a b This function returns non-`nil' if property lists A and B are `eq'. This means that the property lists have the same values for all the same properties, where comparison between values is done using `eq'. - - Function: plists-equal A B + - Function: plists-equal a b This function returns non-`nil' if property lists A and B are `equal'. @@ -1087,7 +1104,7 @@ function `car'. in it. *Note Functions::. The execution of the function may itself work by evaluating the function definition; or the function may be a Lisp primitive implemented in C, or it may be a byte-compiled function -(*note Byte Compilation::.). +(*note Byte Compilation::). The evaluation of forms takes place in a context called the "environment", which consists of the current values and bindings of all @@ -1096,14 +1113,14 @@ creating a new binding for it, the value of the binding in the current environment is used. *Note Variables::. Evaluation of a form may create new environments for recursive -evaluation by binding variables (*note Local Variables::.). These +evaluation by binding variables (*note Local Variables::). These environments are temporary and vanish by the time evaluation of the form is complete. The form may also make changes that persist; these changes are called "side effects". An example of a form that produces side effects is `(setq foo 1)'. The details of what evaluation means for each kind of form are -described below (*note Forms::.). +described below (*note Forms::). ---------- Footnotes ---------- @@ -1129,13 +1146,13 @@ ability to pass information to them as arguments. The functions and variables described in this section evaluate forms, specify limits to the evaluation process, or record recently returned -values. Loading a file also does evaluation (*note Loading::.). +values. Loading a file also does evaluation (*note Loading::). - - Function: eval FORM + - Function: eval form This is the basic function for performing evaluation. It evaluates FORM in the current environment and returns the result. How the evaluation proceeds depends on the type of the object (*note - Forms::.). + Forms::). Since `eval' is a function, the argument expression that appears in a call to `eval' is evaluated twice: once as preparation before @@ -1155,7 +1172,7 @@ values. Loading a file also does evaluation (*note Loading::.). The number of currently active calls to `eval' is limited to `max-lisp-eval-depth' (see below). - - Command: eval-region START END &optional STREAM + - Command: eval-region start end &optional stream This function evaluates the forms in the current buffer in the region defined by the positions START and END. It reads forms from the region and calls `eval' on them until the end of the region is @@ -1170,7 +1187,7 @@ values. Loading a file also does evaluation (*note Loading::.). `eval-region' always returns `nil'. - - Command: eval-buffer BUFFER &optional STREAM + - Command: eval-buffer buffer &optional stream This is like `eval-region' except that it operates on the whole contents of BUFFER. @@ -1185,7 +1202,7 @@ values. Loading a file also does evaluation (*note Loading::.). This limit, with the associated error when it is exceeded, is one way that Lisp avoids infinite recursion on an ill-defined function. - The default value of this variable is 500. If you set it to a + The default value of this variable is 1000. If you set it to a value less than 100, Lisp will reset it to 100 if the given value is reached. @@ -1243,45 +1260,8 @@ starting with "all other types" which are self-evaluating forms. we find the real function via the symbol. * Function Forms:: Forms that call functions. * Macro Forms:: Forms that call macros. -* Special Forms:: "Special forms" are idiosyncratic primitives, +* Special Forms:: ``Special forms'' are idiosyncratic primitives, most of them extremely important. * Autoloading:: Functions set up to load files containing their real definitions. - -File: lispref.info, Node: Self-Evaluating Forms, Next: Symbol Forms, Up: Forms - -Self-Evaluating Forms ---------------------- - - A "self-evaluating form" is any form that is not a list or symbol. -Self-evaluating forms evaluate to themselves: the result of evaluation -is the same object that was evaluated. Thus, the number 25 evaluates to -25, and the string `"foo"' evaluates to the string `"foo"'. Likewise, -evaluation of a vector does not cause evaluation of the elements of the -vector--it returns the same vector with its contents unchanged. - - '123 ; An object, shown without evaluation. - => 123 - 123 ; Evaluated as usual--result is the same. - => 123 - (eval '123) ; Evaluated "by hand"--result is the same. - => 123 - (eval (eval '123)) ; Evaluating twice changes nothing. - => 123 - - It is common to write numbers, characters, strings, and even vectors -in Lisp code, taking advantage of the fact that they self-evaluate. -However, it is quite unusual to do this for types that lack a read -syntax, because there's no way to write them textually. It is possible -to construct Lisp expressions containing these types by means of a Lisp -program. Here is an example: - - ;; Build an expression containing a buffer object. - (setq buffer (list 'print (current-buffer))) - => (print #) - ;; Evaluate it. - (eval buffer) - -| # - => # -