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