lispref/compile.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Emacs Lisp Reference Manual.
   3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
   4 @c See the file elisp.texi for copying conditions.
   5 @setfilename ../info/compile
   6 @node Byte Compilation, Debugging, Loading, Top
   7 @chapter Byte Compilation
   8 @cindex byte-code
   9 @cindex compilation
  10
  11   GNU Emacs Lisp has a @dfn{compiler} that translates functions written
  12 in Lisp into a special representation called @dfn{byte-code} that can be
  13 executed more efficiently.  The compiler replaces Lisp function
  14 definitions with byte-code.  When a byte-code function is called, its
  15 definition is evaluated by the @dfn{byte-code interpreter}.
  16
  17   Because the byte-compiled code is evaluated by the byte-code
  18 interpreter, instead of being executed directly by the machine's
  19 hardware (as true compiled code is), byte-code is completely
  20 transportable from machine to machine without recompilation.  It is not,
  21 however, as fast as true compiled code.
  22
  23   In general, any version of Emacs can run byte-compiled code produced
  24 by recent earlier versions of Emacs, but the reverse is not true.  In
  25 particular, if you compile a program with Emacs 19.29, the compiled
  26 code does not run in earlier versions.
  27 @iftex
  28 @xref{Docs and Compilation}.
  29 @end iftex
  30 Files compiled in versions before 19.29 may not work in 19.29 if they
  31 contain character constants with modifier bits, because the bits were
  32 renumbered in Emacs 19.29.
  33
  34   @xref{Compilation Errors}, for how to investigate errors occurring in
  35 byte compilation.
  36
  37 @menu
  38 * Speed of Byte-Code::          An example of speedup from byte compilation.
  39 * Compilation Functions::       Byte compilation functions.
  40 * Docs and Compilation::        Dynamic loading of documentation strings.
  41 * Dynamic Loading::             Dynamic loading of individual functions.
  42 * Eval During Compile::         Code to be evaluated when you compile.
  43 * Byte-Code Objects::           The data type used for byte-compiled functions.
  44 * Disassembly::                 Disassembling byte-code; how to read byte-code.
  45 @end menu
  46
  47 @node Speed of Byte-Code
  48 @section Performance of Byte-Compiled Code
  49
  50   A byte-compiled function is not as efficient as a primitive function
  51 written in C, but runs much faster than the version written in Lisp.
  52 Here is an example:
  53
  54 @example
  55 @group
  56 (defun silly-loop (n)
  57   "Return time before and after N iterations of a loop."
  58   (let ((t1 (current-time-string)))
  59     (while (> (setq n (1- n))
  60               0))
  61     (list t1 (current-time-string))))
  62 @result{} silly-loop
  63 @end group
  64
  65 @group
  66 (silly-loop 100000)
  67 @result{} ("Fri Mar 18 17:25:57 1994"
  68     "Fri Mar 18 17:26:28 1994")  ; @r{31 seconds}
  69 @end group
  70
  71 @group
  72 (byte-compile 'silly-loop)
  73 @result{} @r{[Compiled code not shown]}
  74 @end group
  75
  76 @group
  77 (silly-loop 100000)
  78 @result{} ("Fri Mar 18 17:26:52 1994"
  79     "Fri Mar 18 17:26:58 1994")  ; @r{6 seconds}
  80 @end group
  81 @end example
  82
  83   In this example, the interpreted code required 31 seconds to run,
  84 whereas the byte-compiled code required 6 seconds.  These results are
  85 representative, but actual results will vary greatly.
  86
  87 @node Compilation Functions
  88 @comment  node-name,  next,  previous,  up
  89 @section The Compilation Functions
  90 @cindex compilation functions
  91
  92   You can byte-compile an individual function or macro definition with
  93 the @code{byte-compile} function.  You can compile a whole file with
  94 @code{byte-compile-file}, or several files with
  95 @code{byte-recompile-directory} or @code{batch-byte-compile}.
  96
  97   The byte compiler produces error messages and warnings about each file
  98 in a buffer called @samp{*Compile-Log*}.  These report things in your
  99 program that suggest a problem but are not necessarily erroneous.
 100
 101 @cindex macro compilation
 102   Be careful when byte-compiling code that uses macros.  Macro calls are
 103 expanded when they are compiled, so the macros must already be defined
 104 for proper compilation.  For more details, see @ref{Compiling Macros}.
 105
 106   Normally, compiling a file does not evaluate the file's contents or
 107 load the file.  But it does execute any @code{require} calls at top
 108 level in the file.  One way to ensure that necessary macro definitions
 109 are available during compilation is to require the file that defines
 110 them (@pxref{Named Features}).  To avoid loading the macro definition files
 111 when someone @emph{runs} the compiled program, write
 112 @code{eval-when-compile} around the @code{require} calls (@pxref{Eval
 113 During Compile}).
 114
 115 @defun byte-compile symbol
 116 This function byte-compiles the function definition of @var{symbol},
 117 replacing the previous definition with the compiled one.  The function
 118 definition of @var{symbol} must be the actual code for the function;
 119 i.e., the compiler does not follow indirection to another symbol.
 120 @code{byte-compile} returns the new, compiled definition of
 121 @var{symbol}.
 122
 123   If @var{symbol}'s definition is a byte-code function object,
 124 @code{byte-compile} does nothing and returns @code{nil}.  Lisp records
 125 only one function definition for any symbol, and if that is already
 126 compiled, non-compiled code is not available anywhere.  So there is no
 127 way to ``compile the same definition again.''
 128
 129 @example
 130 @group
 131 (defun factorial (integer)
 132   "Compute factorial of INTEGER."
 133   (if (= 1 integer) 1
 134     (* integer (factorial (1- integer)))))
 135 @result{} factorial
 136 @end group
 137
 138 @group
 139 (byte-compile 'factorial)
 140 @result{}
 141 #[(integer)
 142   "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207"
 143   [integer 1 * factorial]
 144   4 "Compute factorial of INTEGER."]
 145 @end group
 146 @end example
 147
 148 @noindent
 149 The result is a byte-code function object.  The string it contains is
 150 the actual byte-code; each character in it is an instruction or an
 151 operand of an instruction.  The vector contains all the constants,
 152 variable names and function names used by the function, except for
 153 certain primitives that are coded as special instructions.
 154 @end defun
 155
 156 @deffn Command compile-defun
 157 This command reads the defun containing point, compiles it, and
 158 evaluates the result.  If you use this on a defun that is actually a
 159 function definition, the effect is to install a compiled version of that
 160 function.
 161 @end deffn
 162
 163 @deffn Command byte-compile-file filename
 164 This function compiles a file of Lisp code named @var{filename} into
 165 a file of byte-code.  The output file's name is made by appending
 166 @samp{c} to the end of @var{filename}.
 167
 168 Compilation works by reading the input file one form at a time.  If it
 169 is a definition of a function or macro, the compiled function or macro
 170 definition is written out.  Other forms are batched together, then each
 171 batch is compiled, and written so that its compiled code will be
 172 executed when the file is read.  All comments are discarded when the
 173 input file is read.
 174
 175 This command returns @code{t}.  When called interactively, it prompts
 176 for the file name.
 177
 178 @example
 179 @group
 180 % ls -l push*
 181 -rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
 182 @end group
 183
 184 @group
 185 (byte-compile-file "~/emacs/push.el")
 186      @result{} t
 187 @end group
 188
 189 @group
 190 % ls -l push*
 191 -rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
 192 -rw-rw-rw-  1 lewis     638 Oct  8 20:25 push.elc
 193 @end group
 194 @end example
 195 @end deffn
 196
 197 @deffn Command byte-recompile-directory directory flag
 198 @cindex library compilation
 199 This function recompiles every @samp{.el} file in @var{directory} that
 200 needs recompilation.  A file needs recompilation if a @samp{.elc} file
 201 exists but is older than the @samp{.el} file.
 202
 203 When a @samp{.el} file has no corresponding @samp{.elc} file, then
 204 @var{flag} says what to do.  If it is @code{nil}, these files are
 205 ignored.  If it is non-@code{nil}, the user is asked whether to compile
 206 each such file.
 207
 208 The returned value of this command is unpredictable.
 209 @end deffn
 210
 211 @defun batch-byte-compile
 212 This function runs @code{byte-compile-file} on files specified on the
 213 command line.  This function must be used only in a batch execution of
 214 Emacs, as it kills Emacs on completion.  An error in one file does not
 215 prevent processing of subsequent files.  (The file that gets the error
 216 will not, of course, produce any compiled code.)
 217
 218 @example
 219 % emacs -batch -f batch-byte-compile *.el
 220 @end example
 221 @end defun
 222
 223 @defun byte-code code-string data-vector max-stack
 224 @cindex byte-code interpreter
 225 This function actually interprets byte-code.  A byte-compiled function
 226 is actually defined with a body that calls @code{byte-code}.  Don't call
 227 this function yourself.  Only the byte compiler knows how to generate
 228 valid calls to this function.
 229
 230 In newer Emacs versions (19 and up), byte-code is usually executed as
 231 part of a byte-code function object, and only rarely due to an explicit
 232 call to @code{byte-code}.
 233 @end defun
 234
 235 @node Docs and Compilation
 236 @section Documentation Strings and Compilation
 237 @cindex dynamic loading of documentation
 238
 239   Functions and variables loaded from a byte-compiled file access their
 240 documentation strings dynamically from the file whenever needed.  This
 241 saves space within Emacs, and makes loading faster because the
 242 documentation strings themselves need not be processed while loading the
 243 file.  Actual access to the documentation strings becomes slower as a
 244 result, but this normally is not enough to bother users.
 245
 246   Dynamic access to documentation strings does have drawbacks:
 247
 248 @itemize @bullet
 249 @item
 250 If you delete or move the compiled file after loading it, Emacs can no
 251 longer access the documentation strings for the functions and variables
 252 in the file.
 253
 254 @item
 255 If you alter the compiled file (such as by compiling a new version),
 256 then further access to documentation strings in this file will give
 257 nonsense results.
 258 @end itemize
 259
 260   If your site installs Emacs following the usual procedures, these
 261 problems will never normally occur.  Installing a new version uses a new
 262 directory with a different name; as long as the old version remains
 263 installed, its files will remain unmodified in the places where they are
 264 expected to be.
 265
 266   However, if you have built Emacs yourself and use it from the
 267 directory where you built it, you will experience this problem
 268 occasionally if you edit and recompile Lisp files.  When it happens, you
 269 can cure the problem by reloading the file after recompiling it.
 270
 271   Byte-compiled files made with Emacs 19.29 will not load into older
 272 versions because the older versions don't support this feature.  You can
 273 turn off this feature by setting @code{byte-compile-dynamic-docstrings}
 274 to @code{nil}.  Once this is done, you can compile files that will load
 275 into older Emacs versions.  You can do this globally, or for one source
 276 file by specifying a file-local binding for the variable.  Here's one
 277 way to do that:
 278
 279 @example
 280 -*-byte-compile-dynamic-docstrings: nil;-*-
 281 @end example
 282
 283 @defvar byte-compile-dynamic-docstrings
 284 If this is non-@code{nil}, the byte compiler generates compiled files
 285 that are set up for dynamic loading of documentation strings.
 286 @end defvar
 287
 288 @cindex @samp{#@@@var{count}}
 289 @cindex @samp{#$}
 290   The dynamic documentation string feature writes compiled files that
 291 use a special Lisp reader construct, @samp{#@@@var{count}}.  This
 292 construct skips the next @var{count} characters.  It also uses the
 293 @samp{#$} construct, which stands for ``the name of this file, as a
 294 string.''  It is best not to use these constructs in Lisp source files.
 295
 296 @node Dynamic Loading
 297 @section Dynamic Loading of Individual Functions
 298
 299 @cindex dynamic loading of functions
 300 @cindex lazy loading
 301   When you compile a file, you can optionally enable the @dfn{dynamic
 302 function loading} feature (also known as @dfn{lazy loading}).  With
 303 dynamic function loading, loading the file doesn't fully read the
 304 function definitions in the file.  Instead, each function definition
 305 contains a place-holder which refers to the file.  The first time each
 306 function is called, it reads the full definition from the file, to
 307 replace the place-holder.
 308
 309   The advantage of dynamic function loading is that loading the file
 310 becomes much faster.  This is a good thing for a file which contains
 311 many separate commands, provided that using one of them does not imply
 312 you will soon (or ever) use the rest.  A specialized mode which provides
 313 many keyboard commands often has that usage pattern: a user may invoke
 314 the mode, but use only a few of the commands it provides.
 315
 316   The dynamic loading feature has certain disadvantages:
 317
 318 @itemize @bullet
 319 @item
 320 If you delete or move the compiled file after loading it, Emacs can no
 321 longer load the remaining function definitions not already loaded.
 322
 323 @item
 324 If you alter the compiled file (such as by compiling a new version),
 325 then trying to load any function not already loaded will get nonsense
 326 results.
 327 @end itemize
 328
 329   If you compile a new version of the file, the best thing to do is
 330 immediately load the new compiled file.  That will prevent any future
 331 problems.
 332
 333   The byte compiler uses the dynamic function loading feature if the
 334 variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
 335 time.  Do not set this variable globally, since dynamic loading is
 336 desirable only for certain files.  Instead, enable the feature for
 337 specific source files with file-local variable bindings, like this:
 338
 339 @example
 340 -*-byte-compile-dynamic: t;-*-
 341 @end example
 342
 343 @defvar byte-compile-dynamic
 344 If this is non-@code{nil}, the byte compiler generates compiled files
 345 that are set up for dynamic function loading.
 346 @end defvar
 347
 348 @defun fetch-bytecode function
 349 This immediately finishes loading the definition of @var{function} from
 350 its byte-compiled file, if it is not fully loaded already.  The argument
 351 @var{function} may be a byte-code function object or a function name.
 352 @end defun
 353
 354 @node Eval During Compile
 355 @section Evaluation During Compilation
 356
 357   These features permit you to write code to be evaluated during
 358 compilation of a program.
 359
 360 @defspec eval-and-compile body
 361 This form marks @var{body} to be evaluated both when you compile the
 362 containing code and when you run it (whether compiled or not).
 363
 364 You can get a similar result by putting @var{body} in a separate file
 365 and referring to that file with @code{require}.  Using @code{require} is
 366 preferable if there is a substantial amount of code to be executed in
 367 this way.
 368 @end defspec
 369
 370 @defspec eval-when-compile body
 371 This form marks @var{body} to be evaluated at compile time and not when
 372 the compiled program is loaded.  The result of evaluation by the
 373 compiler becomes a constant which appears in the compiled program.  When
 374 the program is interpreted, not compiled at all, @var{body} is evaluated
 375 normally.
 376
 377 At top level, this is analogous to the Common Lisp idiom
 378 @code{(eval-when (compile eval) @dots{})}.  Elsewhere, the Common Lisp
 379 @samp{#.} reader macro (but not when interpreting) is closer to what
 380 @code{eval-when-compile} does.
 381 @end defspec
 382
 383 @node Byte-Code Objects
 384 @section Byte-Code Function Objects
 385 @cindex compiled function
 386 @cindex byte-code function
 387
 388   Byte-compiled functions have a special data type: they are
 389 @dfn{byte-code function objects}.
 390
 391   Internally, a byte-code function object is much like a vector;
 392 however, the evaluator handles this data type specially when it appears
 393 as a function to be called.  The printed representation for a byte-code
 394 function object is like that for a vector, with an additional @samp{#}
 395 before the opening @samp{[}.
 396
 397   In Emacs version 18, there was no byte-code function object data type;
 398 compiled functions used the function @code{byte-code} to run the byte
 399 code.
 400
 401   A byte-code function object must have at least four elements; there is
 402 no maximum number, but only the first six elements are actually used.
 403 They are:
 404
 405 @table @var
 406 @item arglist
 407 The list of argument symbols.
 408
 409 @item byte-code
 410 The string containing the byte-code instructions.
 411
 412 @item constants
 413 The vector of Lisp objects referenced by the byte code.  These include
 414 symbols used as function names and variable names.
 415
 416 @item stacksize
 417 The maximum stack size this function needs.
 418
 419 @item docstring
 420 The documentation string (if any); otherwise, @code{nil}.  The value may
 421 be a number or a list, in case the documentation string is stored in a
 422 file.  Use the function @code{documentation} to get the real
 423 documentation string (@pxref{Accessing Documentation}).
 424
 425 @item interactive
 426 The interactive spec (if any).  This can be a string or a Lisp
 427 expression.  It is @code{nil} for a function that isn't interactive.
 428 @end table
 429
 430 Here's an example of a byte-code function object, in printed
 431 representation.  It is the definition of the command
 432 @code{backward-sexp}.
 433
 434 @example
 435 #[(&optional arg)
 436   "^H\204^F^@@\301^P\302^H[!\207"
 437   [arg 1 forward-sexp]
 438   2
 439   254435
 440   "p"]
 441 @end example
 442
 443   The primitive way to create a byte-code object is with
 444 @code{make-byte-code}:
 445
 446 @defun make-byte-code &rest elements
 447 This function constructs and returns a byte-code function object
 448 with @var{elements} as its elements.
 449 @end defun
 450
 451   You should not try to come up with the elements for a byte-code
 452 function yourself, because if they are inconsistent, Emacs may crash
 453 when you call the function.  Always leave it to the byte compiler to
 454 create these objects; it makes the elements consistent (we hope).
 455
 456   You can access the elements of a byte-code object using @code{aref};
 457 you can also use @code{vconcat} to create a vector with the same
 458 elements.
 459
 460 @node Disassembly
 461 @section Disassembled Byte-Code
 462 @cindex disassembled byte-code
 463
 464   People do not write byte-code; that job is left to the byte compiler.
 465 But we provide a disassembler to satisfy a cat-like curiosity.  The
 466 disassembler converts the byte-compiled code into humanly readable
 467 form.
 468
 469   The byte-code interpreter is implemented as a simple stack machine.
 470 It pushes values onto a stack of its own, then pops them off to use them
 471 in calculations whose results are themselves pushed back on the stack.
 472 When a byte-code function returns, it pops a value off the stack and
 473 returns it as the value of the function.
 474
 475   In addition to the stack, byte-code functions can use, bind, and set
 476 ordinary Lisp variables, by transferring values between variables and
 477 the stack.
 478
 479 @deffn Command disassemble object &optional stream
 480 This function prints the disassembled code for @var{object}.  If
 481 @var{stream} is supplied, then output goes there.  Otherwise, the
 482 disassembled code is printed to the stream @code{standard-output}.  The
 483 argument @var{object} can be a function name or a lambda expression.
 484
 485 As a special exception, if this function is used interactively,
 486 it outputs to a buffer named @samp{*Disassemble*}.
 487 @end deffn
 488
 489   Here are two examples of using the @code{disassemble} function.  We
 490 have added explanatory comments to help you relate the byte-code to the
 491 Lisp source; these do not appear in the output of @code{disassemble}.
 492 These examples show unoptimized byte-code.  Nowadays byte-code is
 493 usually optimized, but we did not want to rewrite these examples, since
 494 they still serve their purpose.
 495
 496 @example
 497 @group
 498 (defun factorial (integer)
 499   "Compute factorial of an integer."
 500   (if (= 1 integer) 1
 501     (* integer (factorial (1- integer)))))
 502      @result{} factorial
 503 @end group
 504
 505 @group
 506 (factorial 4)
 507      @result{} 24
 508 @end group
 509
 510 @group
 511 (disassemble 'factorial)
 512      @print{} byte-code for factorial:
 513  doc: Compute factorial of an integer.
 514  args: (integer)
 515 @end group
 516
 517 @group
 518 0   constant 1              ; @r{Push 1 onto stack.}
 519
 520 1   varref   integer        ; @r{Get value of @code{integer}}
 521                             ;   @r{from the environment}
 522                             ;   @r{and push the value}
 523                             ;   @r{onto the stack.}
 524 @end group
 525
 526 @group
 527 2   eqlsign                 ; @r{Pop top two values off stack,}
 528                             ;   @r{compare them,}
 529                             ;   @r{and push result onto stack.}
 530 @end group
 531
 532 @group
 533 3   goto-if-nil 10          ; @r{Pop and test top of stack;}
 534                             ;   @r{if @code{nil}, go to 10,}
 535                             ;   @r{else continue.}
 536 @end group
 537
 538 @group
 539 6   constant 1              ; @r{Push 1 onto top of stack.}
 540
 541 7   goto     17             ; @r{Go to 17 (in this case, 1 will be}
 542                             ;   @r{returned by the function).}
 543 @end group
 544
 545 @group
 546 10  constant *              ; @r{Push symbol @code{*} onto stack.}
 547
 548 11  varref   integer        ; @r{Push value of @code{integer} onto stack.}
 549 @end group
 550
 551 @group
 552 12  constant factorial      ; @r{Push @code{factorial} onto stack.}
 553
 554 13  varref   integer        ; @r{Push value of @code{integer} onto stack.}
 555
 556 14  sub1                    ; @r{Pop @code{integer}, decrement value,}
 557                             ;   @r{push new value onto stack.}
 558 @end group
 559
 560 @group
 561                             ; @r{Stack now contains:}
 562                             ;   @minus{} @r{decremented value of @code{integer}}
 563                             ;   @minus{} @r{@code{factorial}}
 564                             ;   @minus{} @r{value of @code{integer}}
 565                             ;   @minus{} @r{@code{*}}
 566 @end group
 567
 568 @group
 569 15  call     1              ; @r{Call function @code{factorial} using}
 570                             ;   @r{the first (i.e., the top) element}
 571                             ;   @r{of the stack as the argument;}
 572                             ;   @r{push returned value onto stack.}
 573 @end group
 574
 575 @group
 576                             ; @r{Stack now contains:}
 577                             ;   @minus{} @r{result of recursive}
 578                             ;        @r{call to @code{factorial}}
 579                             ;   @minus{} @r{value of @code{integer}}
 580                             ;   @minus{} @r{@code{*}}
 581 @end group
 582
 583 @group
 584 16  call     2              ; @r{Using the first two}
 585                             ;   @r{(i.e., the top two)}
 586                             ;   @r{elements of the stack}
 587                             ;   @r{as arguments,}
 588                             ;   @r{call the function @code{*},}
 589                             ;   @r{pushing the result onto the stack.}
 590 @end group
 591
 592 @group
 593 17  return                  ; @r{Return the top element}
 594                             ;   @r{of the stack.}
 595      @result{} nil
 596 @end group
 597 @end example
 598
 599 The @code{silly-loop} function is somewhat more complex:
 600
 601 @example
 602 @group
 603 (defun silly-loop (n)
 604   "Return time before and after N iterations of a loop."
 605   (let ((t1 (current-time-string)))
 606     (while (> (setq n (1- n))
 607               0))
 608     (list t1 (current-time-string))))
 609      @result{} silly-loop
 610 @end group
 611
 612 @group
 613 (disassemble 'silly-loop)
 614      @print{} byte-code for silly-loop:
 615  doc: Return time before and after N iterations of a loop.
 616  args: (n)
 617
 618 0   constant current-time-string  ; @r{Push}
 619                                   ;   @r{@code{current-time-string}}
 620                                   ;   @r{onto top of stack.}
 621 @end group
 622
 623 @group
 624 1   call     0              ; @r{Call @code{current-time-string}}
 625                             ;   @r{ with no argument,}
 626                             ;   @r{ pushing result onto stack.}
 627 @end group
 628
 629 @group
 630 2   varbind  t1             ; @r{Pop stack and bind @code{t1}}
 631                             ;   @r{to popped value.}
 632 @end group
 633
 634 @group
 635 3   varref   n              ; @r{Get value of @code{n} from}
 636                             ;   @r{the environment and push}
 637                             ;   @r{the value onto the stack.}
 638 @end group
 639
 640 @group
 641 4   sub1                    ; @r{Subtract 1 from top of stack.}
 642 @end group
 643
 644 @group
 645 5   dup                     ; @r{Duplicate the top of the stack;}
 646                             ;   @r{i.e., copy the top of}
 647                             ;   @r{the stack and push the}
 648                             ;   @r{copy onto the stack.}
 649 @end group
 650
 651 @group
 652 6   varset   n              ; @r{Pop the top of the stack,}
 653                             ;   @r{and bind @code{n} to the value.}
 654
 655                             ; @r{In effect, the sequence @code{dup varset}}
 656                             ;   @r{copies the top of the stack}
 657                             ;   @r{into the value of @code{n}}
 658                             ;   @r{without popping it.}
 659 @end group
 660
 661 @group
 662 7   constant 0              ; @r{Push 0 onto stack.}
 663 @end group
 664
 665 @group
 666 8   gtr                     ; @r{Pop top two values off stack,}
 667                             ;   @r{test if @var{n} is greater than 0}
 668                             ;   @r{and push result onto stack.}
 669 @end group
 670
 671 @group
 672 9   goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0}
 673                             ;   @r{(this exits the while loop).}
 674                             ;   @r{else pop top of stack}
 675                             ;   @r{and continue}
 676 @end group
 677
 678 @group
 679 12  constant nil            ; @r{Push @code{nil} onto stack}
 680                             ;   @r{(this is the body of the loop).}
 681 @end group
 682
 683 @group
 684 13  discard                 ; @r{Discard result of the body}
 685                             ;   @r{of the loop (a while loop}
 686                             ;   @r{is always evaluated for}
 687                             ;   @r{its side effects).}
 688 @end group
 689
 690 @group
 691 14  goto     3              ; @r{Jump back to beginning}
 692                             ;   @r{of while loop.}
 693 @end group
 694
 695 @group
 696 17  discard                 ; @r{Discard result of while loop}
 697                             ;   @r{by popping top of stack.}
 698                             ;   @r{This result is the value @code{nil} that}
 699                             ;   @r{was not popped by the goto at 9.}
 700 @end group
 701
 702 @group
 703 18  varref   t1             ; @r{Push value of @code{t1} onto stack.}
 704 @end group
 705
 706 @group
 707 19  constant current-time-string  ; @r{Push}
 708                                   ;   @r{@code{current-time-string}}
 709                                   ;   @r{onto top of stack.}
 710 @end group
 711
 712 @group
 713 20  call     0              ; @r{Call @code{current-time-string} again.}
 714 @end group
 715
 716 @group
 717 21  list2                   ; @r{Pop top two elements off stack,}
 718                             ;   @r{create a list of them,}
 719                             ;   @r{and push list onto stack.}
 720 @end group
 721
 722 @group
 723 22  unbind   1              ; @r{Unbind @code{t1} in local environment.}
 724
 725 23  return                  ; @r{Return value of the top of stack.}
 726
 727      @result{} nil
 728 @end group
 729 @end example
 730
 731