Mercurial > emacs
changeset 84054:0c703c647d76
Move here from ../../lispref
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:18:34 +0000 |
| parents | 95843e85b633 |
| children | dae84f6dfb22 |
| files | doc/lispref/compile.texi |
| diffstat | 1 files changed, 886 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispref/compile.texi Thu Sep 06 04:18:34 2007 +0000 @@ -0,0 +1,886 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004, +@c 2005, 2006, 2007 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/compile +@node Byte Compilation, Advising Functions, Loading, Top +@chapter Byte Compilation +@cindex byte compilation +@cindex byte-code +@cindex compilation (Emacs Lisp) + + Emacs Lisp has a @dfn{compiler} that translates functions written +in Lisp into a special representation called @dfn{byte-code} that can be +executed more efficiently. The compiler replaces Lisp function +definitions with byte-code. When a byte-code function is called, its +definition is evaluated by the @dfn{byte-code interpreter}. + + Because the byte-compiled code is evaluated by the byte-code +interpreter, instead of being executed directly by the machine's +hardware (as true compiled code is), byte-code is completely +transportable from machine to machine without recompilation. It is not, +however, as fast as true compiled code. + + Compiling a Lisp file with the Emacs byte compiler always reads the +file as multibyte text, even if Emacs was started with @samp{--unibyte}, +unless the file specifies otherwise. This is so that compilation gives +results compatible with running the same file without compilation. +@xref{Loading Non-ASCII}. + + In general, any version of Emacs can run byte-compiled code produced +by recent earlier versions of Emacs, but the reverse is not true. + +@vindex no-byte-compile + If you do not want a Lisp file to be compiled, ever, put a file-local +variable binding for @code{no-byte-compile} into it, like this: + +@example +;; -*-no-byte-compile: t; -*- +@end example + + @xref{Compilation Errors}, for how to investigate errors occurring in +byte compilation. + +@menu +* Speed of Byte-Code:: An example of speedup from byte compilation. +* Compilation Functions:: Byte compilation functions. +* Docs and Compilation:: Dynamic loading of documentation strings. +* Dynamic Loading:: Dynamic loading of individual functions. +* Eval During Compile:: Code to be evaluated when you compile. +* Compiler Errors:: Handling compiler error messages. +* Byte-Code Objects:: The data type used for byte-compiled functions. +* Disassembly:: Disassembling byte-code; how to read byte-code. +@end menu + +@node Speed of Byte-Code +@section Performance of Byte-Compiled Code + + A byte-compiled function is not as efficient as a primitive function +written in C, but runs much faster than the version written in Lisp. +Here is an example: + +@example +@group +(defun silly-loop (n) + "Return time before and after N iterations of a loop." + (let ((t1 (current-time-string))) + (while (> (setq n (1- n)) + 0)) + (list t1 (current-time-string)))) +@result{} silly-loop +@end group + +@group +(silly-loop 100000) +@result{} ("Fri Mar 18 17:25:57 1994" + "Fri Mar 18 17:26:28 1994") ; @r{31 seconds} +@end group + +@group +(byte-compile 'silly-loop) +@result{} @r{[Compiled code not shown]} +@end group + +@group +(silly-loop 100000) +@result{} ("Fri Mar 18 17:26:52 1994" + "Fri Mar 18 17:26:58 1994") ; @r{6 seconds} +@end group +@end example + + In this example, the interpreted code required 31 seconds to run, +whereas the byte-compiled code required 6 seconds. These results are +representative, but actual results will vary greatly. + +@node Compilation Functions +@comment node-name, next, previous, up +@section The Compilation Functions +@cindex compilation functions + + You can byte-compile an individual function or macro definition with +the @code{byte-compile} function. You can compile a whole file with +@code{byte-compile-file}, or several files with +@code{byte-recompile-directory} or @code{batch-byte-compile}. + + The byte compiler produces error messages and warnings about each file +in a buffer called @samp{*Compile-Log*}. These report things in your +program that suggest a problem but are not necessarily erroneous. + +@cindex macro compilation + Be careful when writing macro calls in files that you may someday +byte-compile. Macro calls are expanded when they are compiled, so the +macros must already be defined for proper compilation. For more +details, see @ref{Compiling Macros}. If a program does not work the +same way when compiled as it does when interpreted, erroneous macro +definitions are one likely cause (@pxref{Problems with Macros}). +Inline (@code{defsubst}) functions are less troublesome; if you +compile a call to such a function before its definition is known, the +call will still work right, it will just run slower. + + Normally, compiling a file does not evaluate the file's contents or +load the file. But it does execute any @code{require} calls at top +level in the file. One way to ensure that necessary macro definitions +are available during compilation is to require the file that defines +them (@pxref{Named Features}). To avoid loading the macro definition files +when someone @emph{runs} the compiled program, write +@code{eval-when-compile} around the @code{require} calls (@pxref{Eval +During Compile}). + +@defun byte-compile symbol +This function byte-compiles the function definition of @var{symbol}, +replacing the previous definition with the compiled one. The function +definition of @var{symbol} must be the actual code for the function; +i.e., the compiler does not follow indirection to another symbol. +@code{byte-compile} returns the new, compiled definition of +@var{symbol}. + + If @var{symbol}'s definition is a byte-code function object, +@code{byte-compile} does nothing and returns @code{nil}. Lisp records +only one function definition for any symbol, and if that is already +compiled, non-compiled code is not available anywhere. So there is no +way to ``compile the same definition again.'' + +@example +@group +(defun factorial (integer) + "Compute factorial of INTEGER." + (if (= 1 integer) 1 + (* integer (factorial (1- integer))))) +@result{} factorial +@end group + +@group +(byte-compile 'factorial) +@result{} +#[(integer) + "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" + [integer 1 * factorial] + 4 "Compute factorial of INTEGER."] +@end group +@end example + +@noindent +The result is a byte-code function object. The string it contains is +the actual byte-code; each character in it is an instruction or an +operand of an instruction. The vector contains all the constants, +variable names and function names used by the function, except for +certain primitives that are coded as special instructions. + +If the argument to @code{byte-compile} is a @code{lambda} expression, +it returns the corresponding compiled code, but does not store +it anywhere. +@end defun + +@deffn Command compile-defun &optional arg +This command reads the defun containing point, compiles it, and +evaluates the result. If you use this on a defun that is actually a +function definition, the effect is to install a compiled version of that +function. + +@code{compile-defun} normally displays the result of evaluation in the +echo area, but if @var{arg} is non-@code{nil}, it inserts the result +in the current buffer after the form it compiled. +@end deffn + +@deffn Command byte-compile-file filename &optional load +This function compiles a file of Lisp code named @var{filename} into a +file of byte-code. The output file's name is made by changing the +@samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in +@samp{.el}, it adds @samp{.elc} to the end of @var{filename}. + +Compilation works by reading the input file one form at a time. If it +is a definition of a function or macro, the compiled function or macro +definition is written out. Other forms are batched together, then each +batch is compiled, and written so that its compiled code will be +executed when the file is read. All comments are discarded when the +input file is read. + +This command returns @code{t} if there were no errors and @code{nil} +otherwise. When called interactively, it prompts for the file name. + +If @var{load} is non-@code{nil}, this command loads the compiled file +after compiling it. Interactively, @var{load} is the prefix argument. + +@example +@group +% ls -l push* +-rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el +@end group + +@group +(byte-compile-file "~/emacs/push.el") + @result{} t +@end group + +@group +% ls -l push* +-rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el +-rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc +@end group +@end example +@end deffn + +@deffn Command byte-recompile-directory directory &optional flag force +@cindex library compilation +This command recompiles every @samp{.el} file in @var{directory} (or +its subdirectories) that needs recompilation. A file needs +recompilation if a @samp{.elc} file exists but is older than the +@samp{.el} file. + +When a @samp{.el} file has no corresponding @samp{.elc} file, +@var{flag} says what to do. If it is @code{nil}, this command ignores +these files. If @var{flag} is 0, it compiles them. If it is neither +@code{nil} nor 0, it asks the user whether to compile each such file, +and asks about each subdirectory as well. + +Interactively, @code{byte-recompile-directory} prompts for +@var{directory} and @var{flag} is the prefix argument. + +If @var{force} is non-@code{nil}, this command recompiles every +@samp{.el} file that has a @samp{.elc} file. + +The returned value is unpredictable. +@end deffn + +@defun batch-byte-compile &optional noforce +This function runs @code{byte-compile-file} on files specified on the +command line. This function must be used only in a batch execution of +Emacs, as it kills Emacs on completion. An error in one file does not +prevent processing of subsequent files, but no output file will be +generated for it, and the Emacs process will terminate with a nonzero +status code. + +If @var{noforce} is non-@code{nil}, this function does not recompile +files that have an up-to-date @samp{.elc} file. + +@example +% emacs -batch -f batch-byte-compile *.el +@end example +@end defun + +@defun byte-code code-string data-vector max-stack +@cindex byte-code interpreter +This function actually interprets byte-code. A byte-compiled function +is actually defined with a body that calls @code{byte-code}. Don't call +this function yourself---only the byte compiler knows how to generate +valid calls to this function. + +In Emacs version 18, byte-code was always executed by way of a call to +the function @code{byte-code}. Nowadays, byte-code is usually executed +as part of a byte-code function object, and only rarely through an +explicit call to @code{byte-code}. +@end defun + +@node Docs and Compilation +@section Documentation Strings and Compilation +@cindex dynamic loading of documentation + + Functions and variables loaded from a byte-compiled file access their +documentation strings dynamically from the file whenever needed. This +saves space within Emacs, and makes loading faster because the +documentation strings themselves need not be processed while loading the +file. Actual access to the documentation strings becomes slower as a +result, but this normally is not enough to bother users. + + Dynamic access to documentation strings does have drawbacks: + +@itemize @bullet +@item +If you delete or move the compiled file after loading it, Emacs can no +longer access the documentation strings for the functions and variables +in the file. + +@item +If you alter the compiled file (such as by compiling a new version), +then further access to documentation strings in this file will +probably give nonsense results. +@end itemize + + If your site installs Emacs following the usual procedures, these +problems will never normally occur. Installing a new version uses a new +directory with a different name; as long as the old version remains +installed, its files will remain unmodified in the places where they are +expected to be. + + However, if you have built Emacs yourself and use it from the +directory where you built it, you will experience this problem +occasionally if you edit and recompile Lisp files. When it happens, you +can cure the problem by reloading the file after recompiling it. + + You can turn off this feature at compile time by setting +@code{byte-compile-dynamic-docstrings} to @code{nil}; this is useful +mainly if you expect to change the file, and you want Emacs processes +that have already loaded it to keep working when the file changes. +You can do this globally, or for one source file by specifying a +file-local binding for the variable. One way to do that is by adding +this string to the file's first line: + +@example +-*-byte-compile-dynamic-docstrings: nil;-*- +@end example + +@defvar byte-compile-dynamic-docstrings +If this is non-@code{nil}, the byte compiler generates compiled files +that are set up for dynamic loading of documentation strings. +@end defvar + +@cindex @samp{#@@@var{count}} +@cindex @samp{#$} + The dynamic documentation string feature writes compiled files that +use a special Lisp reader construct, @samp{#@@@var{count}}. This +construct skips the next @var{count} characters. It also uses the +@samp{#$} construct, which stands for ``the name of this file, as a +string.'' It is usually best not to use these constructs in Lisp source +files, since they are not designed to be clear to humans reading the +file. + +@node Dynamic Loading +@section Dynamic Loading of Individual Functions + +@cindex dynamic loading of functions +@cindex lazy loading + When you compile a file, you can optionally enable the @dfn{dynamic +function loading} feature (also known as @dfn{lazy loading}). With +dynamic function loading, loading the file doesn't fully read the +function definitions in the file. Instead, each function definition +contains a place-holder which refers to the file. The first time each +function is called, it reads the full definition from the file, to +replace the place-holder. + + The advantage of dynamic function loading is that loading the file +becomes much faster. This is a good thing for a file which contains +many separate user-callable functions, if using one of them does not +imply you will probably also use the rest. A specialized mode which +provides many keyboard commands often has that usage pattern: a user may +invoke the mode, but use only a few of the commands it provides. + + The dynamic loading feature has certain disadvantages: + +@itemize @bullet +@item +If you delete or move the compiled file after loading it, Emacs can no +longer load the remaining function definitions not already loaded. + +@item +If you alter the compiled file (such as by compiling a new version), +then trying to load any function not already loaded will usually yield +nonsense results. +@end itemize + + These problems will never happen in normal circumstances with +installed Emacs files. But they are quite likely to happen with Lisp +files that you are changing. The easiest way to prevent these problems +is to reload the new compiled file immediately after each recompilation. + + The byte compiler uses the dynamic function loading feature if the +variable @code{byte-compile-dynamic} is non-@code{nil} at compilation +time. Do not set this variable globally, since dynamic loading is +desirable only for certain files. Instead, enable the feature for +specific source files with file-local variable bindings. For example, +you could do it by writing this text in the source file's first line: + +@example +-*-byte-compile-dynamic: t;-*- +@end example + +@defvar byte-compile-dynamic +If this is non-@code{nil}, the byte compiler generates compiled files +that are set up for dynamic function loading. +@end defvar + +@defun fetch-bytecode function +If @var{function} is a byte-code function object, this immediately +finishes loading the byte code of @var{function} from its +byte-compiled file, if it is not fully loaded already. Otherwise, +it does nothing. It always returns @var{function}. +@end defun + +@node Eval During Compile +@section Evaluation During Compilation + + These features permit you to write code to be evaluated during +compilation of a program. + +@defspec eval-and-compile body@dots{} +This form marks @var{body} to be evaluated both when you compile the +containing code and when you run it (whether compiled or not). + +You can get a similar result by putting @var{body} in a separate file +and referring to that file with @code{require}. That method is +preferable when @var{body} is large. Effectively @code{require} is +automatically @code{eval-and-compile}, the package is loaded both when +compiling and executing. + +@code{autoload} is also effectively @code{eval-and-compile} too. It's +recognized when compiling, so uses of such a function don't produce +``not known to be defined'' warnings. + +Most uses of @code{eval-and-compile} are fairly sophisticated. + +If a macro has a helper function to build its result, and that macro +is used both locally and outside the package, then +@code{eval-and-compile} should be used to get the helper both when +compiling and then later when running. + +If functions are defined programmatically (with @code{fset} say), then +@code{eval-and-compile} can be used to have that done at compile-time +as well as run-time, so calls to those functions are checked (and +warnings about ``not known to be defined'' suppressed). +@end defspec + +@defspec eval-when-compile body@dots{} +This form marks @var{body} to be evaluated at compile time but not when +the compiled program is loaded. The result of evaluation by the +compiler becomes a constant which appears in the compiled program. If +you load the source file, rather than compiling it, @var{body} is +evaluated normally. + +@cindex compile-time constant +If you have a constant that needs some calculation to produce, +@code{eval-when-compile} can do that at compile-time. For example, + +@lisp +(defvar my-regexp + (eval-when-compile (regexp-opt '("aaa" "aba" "abb")))) +@end lisp + +@cindex macros, at compile time +If you're using another package, but only need macros from it (the +byte compiler will expand those), then @code{eval-when-compile} can be +used to load it for compiling, but not executing. For example, + +@lisp +(eval-when-compile + (require 'my-macro-package)) ;; only macros needed from this +@end lisp + +The same sort of thing goes for macros and @code{defsubst} functions +defined locally and only for use within the file. They are needed for +compiling the file, but in most cases they are not needed for +execution of the compiled file. For example, + +@lisp +(eval-when-compile + (unless (fboundp 'some-new-thing) + (defmacro 'some-new-thing () + (compatibility code)))) +@end lisp + +@noindent +This is often good for code that's only a fallback for compatibility +with other versions of Emacs. + +@strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common +Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the +Common Lisp @samp{#.} reader macro (but not when interpreting) is closer +to what @code{eval-when-compile} does. +@end defspec + +@node Compiler Errors +@section Compiler Errors +@cindex compiler errors + + Byte compilation outputs all errors and warnings into the buffer +@samp{*Compile-Log*}. The messages include file names and line +numbers that identify the location of the problem. The usual Emacs +commands for operating on compiler diagnostics work properly on +these messages. + + However, the warnings about functions that were used but not +defined are always ``located'' at the end of the file, so these +commands won't find the places they are really used. To do that, +you must search for the function names. + + You can suppress the compiler warning for calling an undefined +function @var{func} by conditionalizing the function call on an +@code{fboundp} test, like this: + +@example +(if (fboundp '@var{func}) ...(@var{func} ...)...) +@end example + +@noindent +The call to @var{func} must be in the @var{then-form} of the +@code{if}, and @var{func} must appear quoted in the call to +@code{fboundp}. (This feature operates for @code{cond} as well.) + + Likewise, you can suppress a compiler warning for an unbound variable +@var{variable} by conditionalizing its use on a @code{boundp} test, +like this: + +@example +(if (boundp '@var{variable}) ...@var{variable}...) +@end example + +@noindent +The reference to @var{variable} must be in the @var{then-form} of the +@code{if}, and @var{variable} must appear quoted in the call to +@code{boundp}. + + You can suppress any compiler warnings using the construct +@code{with-no-warnings}: + +@c This is implemented with a defun, but conceptually it is +@c a special form. + +@defspec with-no-warnings body@dots{} +In execution, this is equivalent to @code{(progn @var{body}...)}, +but the compiler does not issue warnings for anything that occurs +inside @var{body}. + +We recommend that you use this construct around the smallest +possible piece of code. +@end defspec + +@node Byte-Code Objects +@section Byte-Code Function Objects +@cindex compiled function +@cindex byte-code function + + Byte-compiled functions have a special data type: they are +@dfn{byte-code function objects}. + + Internally, a byte-code function object is much like a vector; +however, the evaluator handles this data type specially when it appears +as a function to be called. The printed representation for a byte-code +function object is like that for a vector, with an additional @samp{#} +before the opening @samp{[}. + + A byte-code function object must have at least four elements; there is +no maximum number, but only the first six elements have any normal use. +They are: + +@table @var +@item arglist +The list of argument symbols. + +@item byte-code +The string containing the byte-code instructions. + +@item constants +The vector of Lisp objects referenced by the byte code. These include +symbols used as function names and variable names. + +@item stacksize +The maximum stack size this function needs. + +@item docstring +The documentation string (if any); otherwise, @code{nil}. The value may +be a number or a list, in case the documentation string is stored in a +file. Use the function @code{documentation} to get the real +documentation string (@pxref{Accessing Documentation}). + +@item interactive +The interactive spec (if any). This can be a string or a Lisp +expression. It is @code{nil} for a function that isn't interactive. +@end table + +Here's an example of a byte-code function object, in printed +representation. It is the definition of the command +@code{backward-sexp}. + +@example +#[(&optional arg) + "^H\204^F^@@\301^P\302^H[!\207" + [arg 1 forward-sexp] + 2 + 254435 + "p"] +@end example + + The primitive way to create a byte-code object is with +@code{make-byte-code}: + +@defun make-byte-code &rest elements +This function constructs and returns a byte-code function object +with @var{elements} as its elements. +@end defun + + You should not try to come up with the elements for a byte-code +function yourself, because if they are inconsistent, Emacs may crash +when you call the function. Always leave it to the byte compiler to +create these objects; it makes the elements consistent (we hope). + + You can access the elements of a byte-code object using @code{aref}; +you can also use @code{vconcat} to create a vector with the same +elements. + +@node Disassembly +@section Disassembled Byte-Code +@cindex disassembled byte-code + + People do not write byte-code; that job is left to the byte compiler. +But we provide a disassembler to satisfy a cat-like curiosity. The +disassembler converts the byte-compiled code into humanly readable +form. + + The byte-code interpreter is implemented as a simple stack machine. +It pushes values onto a stack of its own, then pops them off to use them +in calculations whose results are themselves pushed back on the stack. +When a byte-code function returns, it pops a value off the stack and +returns it as the value of the function. + + In addition to the stack, byte-code functions can use, bind, and set +ordinary Lisp variables, by transferring values between variables and +the stack. + +@deffn Command disassemble object &optional buffer-or-name +This command displays the disassembled code for @var{object}. In +interactive use, or if @var{buffer-or-name} is @code{nil} or omitted, +the output goes in a buffer named @samp{*Disassemble*}. If +@var{buffer-or-name} is non-@code{nil}, it must be a buffer or the +name of an existing buffer. Then the output goes there, at point, and +point is left before the output. + +The argument @var{object} can be a function name, a lambda expression +or a byte-code object. If it is a lambda expression, @code{disassemble} +compiles it and disassembles the resulting compiled code. +@end deffn + + Here are two examples of using the @code{disassemble} function. We +have added explanatory comments to help you relate the byte-code to the +Lisp source; these do not appear in the output of @code{disassemble}. +These examples show unoptimized byte-code. Nowadays byte-code is +usually optimized, but we did not want to rewrite these examples, since +they still serve their purpose. + +@example +@group +(defun factorial (integer) + "Compute factorial of an integer." + (if (= 1 integer) 1 + (* integer (factorial (1- integer))))) + @result{} factorial +@end group + +@group +(factorial 4) + @result{} 24 +@end group + +@group +(disassemble 'factorial) + @print{} byte-code for factorial: + doc: Compute factorial of an integer. + args: (integer) +@end group + +@group +0 constant 1 ; @r{Push 1 onto stack.} + +1 varref integer ; @r{Get value of @code{integer}} + ; @r{from the environment} + ; @r{and push the value} + ; @r{onto the stack.} +@end group + +@group +2 eqlsign ; @r{Pop top two values off stack,} + ; @r{compare them,} + ; @r{and push result onto stack.} +@end group + +@group +3 goto-if-nil 10 ; @r{Pop and test top of stack;} + ; @r{if @code{nil}, go to 10,} + ; @r{else continue.} +@end group + +@group +6 constant 1 ; @r{Push 1 onto top of stack.} + +7 goto 17 ; @r{Go to 17 (in this case, 1 will be} + ; @r{returned by the function).} +@end group + +@group +10 constant * ; @r{Push symbol @code{*} onto stack.} + +11 varref integer ; @r{Push value of @code{integer} onto stack.} +@end group + +@group +12 constant factorial ; @r{Push @code{factorial} onto stack.} + +13 varref integer ; @r{Push value of @code{integer} onto stack.} + +14 sub1 ; @r{Pop @code{integer}, decrement value,} + ; @r{push new value onto stack.} +@end group + +@group + ; @r{Stack now contains:} + ; @minus{} @r{decremented value of @code{integer}} + ; @minus{} @r{@code{factorial}} + ; @minus{} @r{value of @code{integer}} + ; @minus{} @r{@code{*}} +@end group + +@group +15 call 1 ; @r{Call function @code{factorial} using} + ; @r{the first (i.e., the top) element} + ; @r{of the stack as the argument;} + ; @r{push returned value onto stack.} +@end group + +@group + ; @r{Stack now contains:} + ; @minus{} @r{result of recursive} + ; @r{call to @code{factorial}} + ; @minus{} @r{value of @code{integer}} + ; @minus{} @r{@code{*}} +@end group + +@group +16 call 2 ; @r{Using the first two} + ; @r{(i.e., the top two)} + ; @r{elements of the stack} + ; @r{as arguments,} + ; @r{call the function @code{*},} + ; @r{pushing the result onto the stack.} +@end group + +@group +17 return ; @r{Return the top element} + ; @r{of the stack.} + @result{} nil +@end group +@end example + +The @code{silly-loop} function is somewhat more complex: + +@example +@group +(defun silly-loop (n) + "Return time before and after N iterations of a loop." + (let ((t1 (current-time-string))) + (while (> (setq n (1- n)) + 0)) + (list t1 (current-time-string)))) + @result{} silly-loop +@end group + +@group +(disassemble 'silly-loop) + @print{} byte-code for silly-loop: + doc: Return time before and after N iterations of a loop. + args: (n) + +0 constant current-time-string ; @r{Push} + ; @r{@code{current-time-string}} + ; @r{onto top of stack.} +@end group + +@group +1 call 0 ; @r{Call @code{current-time-string}} + ; @r{ with no argument,} + ; @r{ pushing result onto stack.} +@end group + +@group +2 varbind t1 ; @r{Pop stack and bind @code{t1}} + ; @r{to popped value.} +@end group + +@group +3 varref n ; @r{Get value of @code{n} from} + ; @r{the environment and push} + ; @r{the value onto the stack.} +@end group + +@group +4 sub1 ; @r{Subtract 1 from top of stack.} +@end group + +@group +5 dup ; @r{Duplicate the top of the stack;} + ; @r{i.e., copy the top of} + ; @r{the stack and push the} + ; @r{copy onto the stack.} +@end group + +@group +6 varset n ; @r{Pop the top of the stack,} + ; @r{and bind @code{n} to the value.} + + ; @r{In effect, the sequence @code{dup varset}} + ; @r{copies the top of the stack} + ; @r{into the value of @code{n}} + ; @r{without popping it.} +@end group + +@group +7 constant 0 ; @r{Push 0 onto stack.} +@end group + +@group +8 gtr ; @r{Pop top two values off stack,} + ; @r{test if @var{n} is greater than 0} + ; @r{and push result onto stack.} +@end group + +@group +9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0} + ; @r{(this exits the while loop).} + ; @r{else pop top of stack} + ; @r{and continue} +@end group + +@group +12 constant nil ; @r{Push @code{nil} onto stack} + ; @r{(this is the body of the loop).} +@end group + +@group +13 discard ; @r{Discard result of the body} + ; @r{of the loop (a while loop} + ; @r{is always evaluated for} + ; @r{its side effects).} +@end group + +@group +14 goto 3 ; @r{Jump back to beginning} + ; @r{of while loop.} +@end group + +@group +17 discard ; @r{Discard result of while loop} + ; @r{by popping top of stack.} + ; @r{This result is the value @code{nil} that} + ; @r{was not popped by the goto at 9.} +@end group + +@group +18 varref t1 ; @r{Push value of @code{t1} onto stack.} +@end group + +@group +19 constant current-time-string ; @r{Push} + ; @r{@code{current-time-string}} + ; @r{onto top of stack.} +@end group + +@group +20 call 0 ; @r{Call @code{current-time-string} again.} +@end group + +@group +21 list2 ; @r{Pop top two elements off stack,} + ; @r{create a list of them,} + ; @r{and push list onto stack.} +@end group + +@group +22 unbind 1 ; @r{Unbind @code{t1} in local environment.} + +23 return ; @r{Return value of the top of stack.} + + @result{} nil +@end group +@end example + + +@ignore + arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289 +@end ignore