X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-11;h=5bd9c894e7e8ad8cf16b5d356c90c3789f933217;hb=16d0840d3eada757f529c34fddc0c2fb8f17b9de;hp=93696592bea8e71b0490536f3f7de08925a2a754;hpb=430e0db85cc37821320fe27da9feeacc7961003f;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-11 b/info/lispref.info-11 index 9369659..5bd9c89 100644 --- a/info/lispref.info-11 +++ b/info/lispref.info-11 @@ -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 @@ -50,6 +50,286 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Inline Functions, Next: Related Topics, Prev: Function Cells, Up: Functions + +Inline Functions +================ + + You can define an "inline function" by using `defsubst' instead of +`defun'. An inline function works just like an ordinary function +except for one thing: when you compile a call to the function, the +function's definition is open-coded into the caller. + + Making a function inline makes explicit calls run faster. But it +also has disadvantages. For one thing, it reduces flexibility; if you +change the definition of the function, calls already inlined still use +the old definition until you recompile them. Since the flexibility of +redefining functions is an important feature of XEmacs, you should not +make a function inline unless its speed is really crucial. + + Another disadvantage is that making a large function inline can +increase the size of compiled code both in files and in memory. Since +the speed advantage of inline functions is greatest for small +functions, you generally should not make large functions inline. + + It's possible to define a macro to expand into the same code that an +inline function would execute. But the macro would have a limitation: +you can use it only explicitly--a macro cannot be called with `apply', +`mapcar' and so on. Also, it takes some work to convert an ordinary +function into a macro. (*Note Macros::.) To convert it into an inline +function is very easy; simply replace `defun' with `defsubst'. Since +each argument of an inline function is evaluated exactly once, you +needn't worry about how many times the body uses the arguments, as you +do for macros. (*Note Argument Evaluation::.) + + Inline functions can be used and open-coded later on in the same +file, following the definition, just like macros. + + +File: lispref.info, Node: Related Topics, Prev: Inline Functions, Up: Functions + +Other Topics Related to Functions +================================= + + Here is a table of several functions that do things related to +function calling and function definitions. They are documented +elsewhere, but we provide cross references here. + +`apply' + See *Note Calling Functions::. + +`autoload' + See *Note Autoload::. + +`call-interactively' + See *Note Interactive Call::. + +`commandp' + See *Note Interactive Call::. + +`documentation' + See *Note Accessing Documentation::. + +`eval' + See *Note Eval::. + +`funcall' + See *Note Calling Functions::. + +`ignore' + See *Note Calling Functions::. + +`indirect-function' + See *Note Function Indirection::. + +`interactive' + See *Note Using Interactive::. + +`interactive-p' + See *Note Interactive Call::. + +`mapatoms' + See *Note Creating Symbols::. + +`mapcar' + See *Note Mapping Functions::. + +`mapconcat' + See *Note Mapping Functions::. + +`undefined' + See *Note Key Lookup::. + + +File: lispref.info, Node: Macros, Next: Loading, Prev: Functions, Up: Top + +Macros +****** + + "Macros" enable you to define new control constructs and other +language features. A macro is defined much like a function, but instead +of telling how to compute a value, it tells how to compute another Lisp +expression which will in turn compute the value. We call this +expression the "expansion" of the macro. + + Macros can do this because they operate on the unevaluated +expressions for the arguments, not on the argument values as functions +do. They can therefore construct an expansion containing these +argument expressions or parts of them. + + If you are using a macro to do something an ordinary function could +do, just for the sake of speed, consider using an inline function +instead. *Note Inline Functions::. + +* Menu: + +* Simple Macro:: A basic example. +* Expansion:: How, when and why macros are expanded. +* Compiling Macros:: How macros are expanded by the compiler. +* Defining Macros:: How to write a macro definition. +* Backquote:: Easier construction of list structure. +* Problems with Macros:: Don't evaluate the macro arguments too many times. + Don't hide the user's variables. + + +File: lispref.info, Node: Simple Macro, Next: Expansion, Up: Macros + +A Simple Example of a Macro +=========================== + + Suppose we would like to define a Lisp construct to increment a +variable value, much like the `++' operator in C. We would like to +write `(inc x)' and have the effect of `(setq x (1+ x))'. Here's a +macro definition that does the job: + + (defmacro inc (var) + (list 'setq var (list '1+ var))) + + When this is called with `(inc x)', the argument `var' has the value +`x'--_not_ the _value_ of `x'. The body of the macro uses this to +construct the expansion, which is `(setq x (1+ x))'. Once the macro +definition returns this expansion, Lisp proceeds to evaluate it, thus +incrementing `x'. + + +File: lispref.info, Node: Expansion, Next: Compiling Macros, Prev: Simple Macro, Up: Macros + +Expansion of a Macro Call +========================= + + A macro call looks just like a function call in that it is a list +which starts with the name of the macro. The rest of the elements of +the list are the arguments of the macro. + + Evaluation of the macro call begins like evaluation of a function +call except for one crucial difference: the macro arguments are the +actual expressions appearing in the macro call. They are not evaluated +before they are given to the macro definition. By contrast, the +arguments of a function are results of evaluating the elements of the +function call list. + + Having obtained the arguments, Lisp invokes the macro definition just +as a function is invoked. The argument variables of the macro are bound +to the argument values from the macro call, or to a list of them in the +case of a `&rest' argument. And the macro body executes and returns +its value just as a function body does. + + The second crucial difference between macros and functions is that +the value returned by the macro body is not the value of the macro call. +Instead, it is an alternate expression for computing that value, also +known as the "expansion" of the macro. The Lisp interpreter proceeds +to evaluate the expansion as soon as it comes back from the macro. + + Since the expansion is evaluated in the normal manner, it may contain +calls to other macros. It may even be a call to the same macro, though +this is unusual. + + You can see the expansion of a given macro call by calling +`macroexpand'. + + - Function: macroexpand form &optional environment + This function expands FORM, if it is a macro call. If the result + is another macro call, it is expanded in turn, until something + which is not a macro call results. That is the value returned by + `macroexpand'. If FORM is not a macro call to begin with, it is + returned as given. + + Note that `macroexpand' does not look at the subexpressions of + FORM (although some macro definitions may do so). Even if they + are macro calls themselves, `macroexpand' does not expand them. + + The function `macroexpand' does not expand calls to inline + functions. Normally there is no need for that, since a call to an + inline function is no harder to understand than a call to an + ordinary function. + + If ENVIRONMENT is provided, it specifies an alist of macro + definitions that shadow the currently defined macros. Byte + compilation uses this feature. + + (defmacro inc (var) + (list 'setq var (list '1+ var))) + => inc + + (macroexpand '(inc r)) + => (setq r (1+ r)) + + (defmacro inc2 (var1 var2) + (list 'progn (list 'inc var1) (list 'inc var2))) + => inc2 + + (macroexpand '(inc2 r s)) + => (progn (inc r) (inc s)) ; `inc' not expanded here. + + +File: lispref.info, Node: Compiling Macros, Next: Defining Macros, Prev: Expansion, Up: Macros + +Macros and Byte Compilation +=========================== + + You might ask why we take the trouble to compute an expansion for a +macro and then evaluate the expansion. Why not have the macro body +produce the desired results directly? The reason has to do with +compilation. + + When a macro call appears in a Lisp program being compiled, the Lisp +compiler calls the macro definition just as the interpreter would, and +receives an expansion. But instead of evaluating this expansion, it +compiles the expansion as if it had appeared directly in the program. +As a result, the compiled code produces the value and side effects +intended for the macro, but executes at full compiled speed. This would +not work if the macro body computed the value and side effects +itself--they would be computed at compile time, which is not useful. + + In order for compilation of macro calls to work, the macros must be +defined in Lisp when the calls to them are compiled. The compiler has a +special feature to help you do this: if a file being compiled contains a +`defmacro' form, the macro is defined temporarily for the rest of the +compilation of that file. To use this feature, you must define the +macro in the same file where it is used and before its first use. + + Byte-compiling a file executes any `require' calls at top-level in +the file. This is in case the file needs the required packages for +proper compilation. One way to ensure that necessary macro definitions +are available during compilation is to require the files that define +them (*note Named Features::). To avoid loading the macro definition +files when someone _runs_ the compiled program, write +`eval-when-compile' around the `require' calls (*note Eval During +Compile::). + + +File: lispref.info, Node: Defining Macros, Next: Backquote, Prev: Compiling Macros, Up: Macros + +Defining Macros +=============== + + A Lisp macro is a list whose CAR is `macro'. Its CDR should be a +function; expansion of the macro works by applying the function (with +`apply') to the list of unevaluated argument-expressions from the macro +call. + + It is possible to use an anonymous Lisp macro just like an anonymous +function, but this is never done, because it does not make sense to pass +an anonymous macro to functionals such as `mapcar'. In practice, all +Lisp macros have names, and they are usually defined with the special +form `defmacro'. + + - Special Form: defmacro name argument-list body-forms... + `defmacro' defines the symbol NAME as a macro that looks like this: + + (macro lambda ARGUMENT-LIST . BODY-FORMS) + + This macro object is stored in the function cell of NAME. The + value returned by evaluating the `defmacro' form is NAME, but + usually we ignore this value. + + The shape and meaning of ARGUMENT-LIST is the same as in a + function, and the keywords `&rest' and `&optional' may be used + (*note Argument List::). Macros may have a documentation string, + but any `interactive' declaration is ignored since macros cannot be + called interactively. + + File: lispref.info, Node: Backquote, Next: Problems with Macros, Prev: Defining Macros, Up: Macros Backquote @@ -61,7 +341,7 @@ of constants and nonconstant parts. To make this easier, use the macro Backquote allows you to quote a list, but selectively evaluate elements of that list. In the simplest case, it is identical to the -special form `quote' (*note Quoting::.). For example, these two forms +special form `quote' (*note Quoting::). For example, these two forms yield identical results: `(a list of (+ 2 3) elements) @@ -148,19 +428,18 @@ find in Pascal. (cons 'while (cons (list '<= var final) (append body (list (list 'inc var))))))) => for + (for i from 1 to 3 do (setq square (* i i)) (princ (format "\n%d %d" i square))) ==> - (let ((i 1)) (while (<= i 3) (setq square (* i i)) (princ (format "%d %d" i square)) (inc i))) - - - -|1 1 + + -|1 1 -|2 4 -|3 9 => nil @@ -224,8 +503,7 @@ number of times: (defmacro for (var from init to final do &rest body) "Execute a simple for loop: (for i from 1 to 10 do (print i))." - - `(let ((,var ,init) + `(let ((,var ,init) (max ,final)) (while (<= ,var max) ,@body @@ -246,7 +524,7 @@ supposed to refer to the user's binding of `max', really access the binding made by `for'. The way to correct this is to use an uninterned symbol instead of -`max' (*note Creating Symbols::.). The uninterned symbol can be bound +`max' (*note Creating Symbols::). The uninterned symbol can be bound and referred to just like any other symbol, but since it is created by `for', we know that it cannot already appear in the user's program. Since it is not interned, there is no way the user can put it into the @@ -274,7 +552,7 @@ Evaluating Macro Arguments in Expansion Another problem can happen if you evaluate any of the macro argument expressions during the computation of the expansion, such as by calling -`eval' (*note Eval::.). If the argument is supposed to refer to the +`eval' (*note Eval::). If the argument is supposed to refer to the user's variables, you may have trouble if the user happens to use a variable with the same name as one of the macro arguments. Inside the macro body, the macro argument binding is the most local binding of this @@ -329,7 +607,7 @@ example: (defmacro empty-object () (list 'quote (cons nil nil))) - + (defun initialize (condition) (let ((object (empty-object))) (if condition @@ -458,7 +736,7 @@ and add your group to each of them using the `:group' keyword. The way to declare new customization groups is with `defgroup'. - - Macro: defgroup GROUP MEMBERS DOC [KEYWORD VALUE]... + - Macro: defgroup group members doc [keyword value]... Declare GROUP as a customization group containing MEMBERS. Do not quote the symbol GROUP. The argument DOC specifies the documentation string for the group. @@ -474,7 +752,7 @@ and add your group to each of them using the `:group' keyword. are `custom-variable' for a variable, `custom-face' for a face, and `custom-group' for a group. - In addition to the common keywords (*note Common Keywords::.), you + In addition to the common keywords (*note Common Keywords::), you can use this keyword in `defgroup': `:prefix PREFIX' @@ -492,7 +770,7 @@ Defining Customization Variables Use `defcustom' to declare user-editable variables. - - Macro: defcustom OPTION DEFAULT DOC [KEYWORD VALUE]... + - Macro: defcustom option default doc [keyword value]... Declare OPTION as a customizable user option variable. Do not quote OPTION. The argument DOC specifies the documentation string for the variable. @@ -584,7 +862,7 @@ Keywords::. Here is an example, from the library `paren.el': (defcustom show-paren-mode nil "Toggle Show Paren mode...." :set (lambda (symbol value) - (show-paren-mode (or value 0))) + (show-paren-mode (or value 0))) :initialize 'custom-initialize-default :type 'boolean :group 'paren-showing @@ -621,7 +899,7 @@ example: symbol, one of the customization type names defined in the following sections. After this symbol come a number of arguments, depending on the symbol. Between the type symbol and its arguments, you can -optionally write keyword-value pairs (*note Type Keywords::.). +optionally write keyword-value pairs (*note Type Keywords::). Some of the type symbols do not use any arguments; those are called "simple types". For a simple type, if you do not use any keyword-value @@ -1007,196 +1285,7 @@ the forms are function definitions and variable definitions. * Autoload:: Setting up a function to autoload. * Repeated Loading:: Precautions about loading a file twice. * Named Features:: Loading a library if it isn't already loaded. -* Unloading:: How to "unload" a library that was loaded. +* Unloading:: How to ``unload'' a library that was loaded. * Hooks for Loading:: Providing code to be run when particular libraries are loaded. - -File: lispref.info, Node: How Programs Do Loading, Next: Autoload, Up: Loading - -How Programs Do Loading -======================= - - XEmacs Lisp has several interfaces for loading. For example, -`autoload' creates a placeholder object for a function in a file; -trying to call the autoloading function loads the file to get the -function's real definition (*note Autoload::.). `require' loads a file -if it isn't already loaded (*note Named Features::.). Ultimately, all -these facilities call the `load' function to do the work. - - - Function: load FILENAME &optional MISSING-OK NOMESSAGE NOSUFFIX - This function finds and opens a file of Lisp code, evaluates all - the forms in it, and closes the file. - - To find the file, `load' first looks for a file named - `FILENAME.elc', that is, for a file whose name is FILENAME with - `.elc' appended. If such a file exists, it is loaded. If there - is no file by that name, then `load' looks for a file named - `FILENAME.el'. If that file exists, it is loaded. Finally, if - neither of those names is found, `load' looks for a file named - FILENAME with nothing appended, and loads it if it exists. (The - `load' function is not clever about looking at FILENAME. In the - perverse case of a file named `foo.el.el', evaluation of `(load - "foo.el")' will indeed find it.) - - If the optional argument NOSUFFIX is non-`nil', then the suffixes - `.elc' and `.el' are not tried. In this case, you must specify - the precise file name you want. - - If FILENAME is a relative file name, such as `foo' or - `baz/foo.bar', `load' searches for the file using the variable - `load-path'. It appends FILENAME to each of the directories - listed in `load-path', and loads the first file it finds whose name - matches. The current default directory is tried only if it is - specified in `load-path', where `nil' stands for the default - directory. `load' tries all three possible suffixes in the first - directory in `load-path', then all three suffixes in the second - directory, and so on. - - If you get a warning that `foo.elc' is older than `foo.el', it - means you should consider recompiling `foo.el'. *Note Byte - Compilation::. - - Messages like `Loading foo...' and `Loading foo...done' appear in - the echo area during loading unless NOMESSAGE is non-`nil'. - - Any unhandled errors while loading a file terminate loading. If - the load was done for the sake of `autoload', any function - definitions made during the loading are undone. - - If `load' can't find the file to load, then normally it signals the - error `file-error' (with `Cannot open load file FILENAME'). But - if MISSING-OK is non-`nil', then `load' just returns `nil'. - - You can use the variable `load-read-function' to specify a function - for `load' to use instead of `read' for reading expressions. See - below. - - `load' returns `t' if the file loads successfully. - - - User Option: load-path - The value of this variable is a list of directories to search when - loading files with `load'. Each element is a string (which must be - a directory name) or `nil' (which stands for the current working - directory). The value of `load-path' is initialized from the - environment variable `EMACSLOADPATH', if that exists; otherwise its - default value is specified in `emacs/src/paths.h' when XEmacs is - built. - - The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:' - (or `;', according to the operating system) separates directory - names, and `.' is used for the current default directory. Here is - an example of how to set your `EMACSLOADPATH' variable from a - `csh' `.login' file: - - setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp - - Here is how to set it using `sh': - - export EMACSLOADPATH - EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp - - Here is an example of code you can place in a `.emacs' file to add - several directories to the front of your default `load-path': - - (setq load-path - (append (list nil "/user/bil/emacs" - "/usr/local/lisplib" - "~/emacs") - load-path)) - - In this example, the path searches the current working directory - first, followed then by the `/user/bil/emacs' directory, the - `/usr/local/lisplib' directory, and the `~/emacs' directory, which - are then followed by the standard directories for Lisp code. - - The command line options `-l' or `-load' specify a Lisp library to - load as part of Emacs startup. Since this file might be in the - current directory, Emacs 18 temporarily adds the current directory - to the front of `load-path' so the file can be found there. Newer - Emacs versions also find such files in the current directory, but - without altering `load-path'. - - Dumping Emacs uses a special value of `load-path'. If the value of - `load-path' at the end of dumping is unchanged (that is, still the - same special value), the dumped Emacs switches to the ordinary - `load-path' value when it starts up, as described above. But if - `load-path' has any other value at the end of dumping, that value - is used for execution of the dumped Emacs also. - - Therefore, if you want to change `load-path' temporarily for - loading a few libraries in `site-init.el' or `site-load.el', you - should bind `load-path' locally with `let' around the calls to - `load'. - - - Function: locate-file FILENAME PATH-LIST &optional SUFFIXES MODE - This function searches for a file in the same way that `load' does, - and returns the file found (if any). (In fact, `load' uses this - function to search through `load-path'.) It searches for FILENAME - through PATH-LIST, expanded by one of the optional SUFFIXES - (string of suffixes separated by `:'s), checking for access MODE - (0|1|2|4 = exists|executable|writeable|readable), default readable. - - `locate-file' keeps hash tables of the directories it searches - through, in order to speed things up. It tries valiantly to not - get confused in the face of a changing and unpredictable - environment, but can occasionally get tripped up. In this case, - you will have to call `locate-file-clear-hashing' to get it back - on track. See that function for details. - - - Function: locate-file-clear-hashing PATH - This function clears the hash records for the specified list of - directories. `locate-file' uses a hashing scheme to speed lookup, - and will correctly track the following environmental changes: - - * changes of any sort to the list of directories to be searched. - - * addition and deletion of non-shadowing files (see below) from - the directories in the list. - - * byte-compilation of a .el file into a .elc file. - - `locate-file' will primarily get confused if you add a file that - shadows (i.e. has the same name as) another file further down in - the directory list. In this case, you must call - `locate-file-clear-hashing'. - - - Variable: load-in-progress - This variable is non-`nil' if Emacs is in the process of loading a - file, and it is `nil' otherwise. - - - Variable: load-read-function - This variable specifies an alternate expression-reading function - for `load' and `eval-region' to use instead of `read'. The - function should accept one argument, just as `read' does. - - Normally, the variable's value is `nil', which means those - functions should use `read'. - - - User Option: load-warn-when-source-newer - This variable specifies whether `load' should check whether the - source is newer than the binary. If this variable is true, then - when a `.elc' file is being loaded and the corresponding `.el' is - newer, a warning message will be printed. The default is `nil', - but it is bound to `t' during the initial loadup. - - - User Option: load-warn-when-source-only - This variable specifies whether `load' should warn when loading a - `.el' file instead of an `.elc'. If this variable is true, then - when `load' is called with a filename without an extension, and - the `.elc' version doesn't exist but the `.el' version does, then - a message will be printed. If an explicit extension is passed to - `load', no warning will be printed. The default is `nil', but it - is bound to `t' during the initial loadup. - - - User Option: load-ignore-elc-files - This variable specifies whether `load' should ignore `.elc' files - when a suffix is not given. This is normally used only to - bootstrap the `.elc' files when building XEmacs, when you use the - command `make all-elc'. (This forces the `.el' versions to be - loaded in the process of compiling those same files, so that - existing out-of-date `.elc' files do not make it mess things up.) - - To learn how `load' is used to build XEmacs, see *Note Building -XEmacs::. -