GNU Emacs Lisp Bytecode Reference Manual Collated and edited by Rocky Bernstein with contibutions from Pipcet, Chris Wellons, Stefan Monnier, Hallvard Breien Furuseth, Vladimir Kazanov, Andrea Corallo, and the Emacs community. 1 i Short Contents 1 Introduction to Emacs Lisp Byte Code and LAP :::::::::::: 1 2 Emacs Lisp Bytecode Environment ::::::::::::::::::::::: 7 3 Emacs Lisp Bytecode Instructions ::::::::::::::::::::::: 39 4 Instruction Changes Between Emacs Releases ::::::::::::: 166 5 Opcode Table ::::::::::::::::::::::::::::::::::::::: 174 A :::::::::::::::::::::::::::::::::::::::::::::::::: 183 ii Table of Contents 1 Introduction to Emacs Lisp Byte Code and LAP :::::::::::::::::::::::::::::::::::: 1 1.1 Why is Emacs Lisp Bytecode Important and How is Emacs as a Program Different? :::::::::::::::::::::::::::::::::::: 2 1.2 Emacs Lisp Bytecode and LAP ::::::::::::::::::::::::::::::::: 3 Example showing use of byte-compile-lapcode :::::::::::::::::: 3 1.3 Emacs Lisp Virtual Machine :::::::::::::::::::::::::::::::::::: 4 1.4 Wither Bytecode - Its Future ::::::::::::::::::::::::::::::::::: 5 2 Emacs Lisp Bytecode Environment :::::::::::: 7 2.1 Emacs Lisp Bytecode Objects::::::::::::::::::::::::::::::::::: 8 2.1.1 Function Parameter (lambda) List ::::::::::::::::::::::::: 8 2.1.2 Bytecode Unibyte String :::::::::::::::::::::::::::::::::: 10 2.1.3 Constants Vector ::::::::::::::::::::::::::::::::::::::::: 11 2.1.4 Maximum Stack Usage ::::::::::::::::::::::::::::::::::: 12 2.1.5 Docstring::::::::::::::::::::::::::::::::::::::::::::::::: 12 2.1.6 \Interactive" Specification :::::::::::::::::::::::::::::::: 12 Examples showing the \interactive" specification ::::::::::::::::: 13 2.2 Emacs Lisp Bytecode Compiler :::::::::::::::::::::::::::::::: 14 2.3 Emacs Lisp Bytecode Interpreter :::::::::::::::::::::::::::::: 15 2.4 Emacs Lisp Bytecode Bytes ::::::::::::::::::::::::::::::::::: 16 2.5 Emacs Lisp Bytecode Files :::::::::::::::::::::::::::::::::::: 17 2.6 Functions and Commands for working with LAP and Bytecode :: 19 2.6.1 aref ::::::::::::::::::::::::::::::::::::::::::::::::::::: 19 2.6.2 batch-byte-compile ::::::::::::::::::::::::::::::::::::: 20 2.6.3 batch-byte-recompile-directory::::::::::::::::::::::: 20 2.6.4 byte-code ::::::::::::::::::::::::::::::::::::::::::::::: 20 2.6.5 byte-compile :::::::::::::::::::::::::::::::::::::::::::: 20 2.6.6 byte-compile-file :::::::::::::::::::::::::::::::::::::: 21 2.6.7 byte-compile-sexp :::::::::::::::::::::::::::::::::::::: 21 2.6.8 byte-recalc-examples :::::::::::::::::::::::::::::::::: 22 2.6.9 byte-recompile-directory :::::::::::::::::::::::::::::: 22 2.6.10 byte-recompile-file::::::::::::::::::::::::::::::::::: 23 2.6.11 compile-defun:::::::::::::::::::::::::::::::::::::::::: 23 2.6.12 disassemble :::::::::::::::::::::::::::::::::::::::::::: 23 2.6.13 disassemble-file :::::::::::::::::::::::::::::::::::::: 24 2.6.14 disassemble-full :::::::::::::::::::::::::::::::::::::: 24 2.6.15 display-call-tree ::::::::::::::::::::::::::::::::::::: 24 2.6.16 emacs-lisp-byte-compile :::::::::::::::::::::::::::::: 24 2.6.17 functionp :::::::::::::::::::::::::::::::::::::::::::::: 24 2.6.18 make-byte-code :::::::::::::::::::::::::::::::::::::::: 25 2.6.19 symbol-function ::::::::::::::::::::::::::::::::::::::: 26 iii 2.7 Source and Bytecode Optimization :::::::::::::::::::::::::::: 28 2.7.1 Source-to-source Transformations ::::::::::::::::::::::::: 28 2.7.2 Peephole Optimization:::::::::::::::::::::::::::::::::::: 29 2.7.3 Adding an Optimizing Transformation :::::::::::::::::::: 30 2.7.4 Constant Folding ::::::::::::::::::::::::::::::::::::::::: 31 2.7.5 Dead Code Elimination ::::::::::::::::::::::::::::::::::: 32 2.7.6 Strength Reduction ::::::::::::::::::::::::::::::::::::::: 33 2.8 LAP Decompiler :::::::::::::::::::::::::::::::::::::::::::::: 33 2.8.1 It's GNU Emacs, so of course I have the source code!:::::: 34 2.8.2 Isn't it simpler to just disassemble? ::::::::::::::::::::::: 34 3 Emacs Lisp Bytecode Instructions :::::::::::: 39 3.1 Instruction-Description Format :::::::::::::::::::::::::::::::: 39 3.1.1 Instruction Jargon :::::::::::::::::::::::::::::::::::::::: 39 3.1.2 Instruction Description Fields::::::::::::::::::::::::::::: 40 3.2 Argument-Packing Instructions :::::::::::::::::::::::::::::::: 42 stack-ref (1{7) :::::::::::::::::::::::::::::::::::::::::::::::: 42 varref (8{15) ::::::::::::::::::::::::::::::::::::::::::::::::::: 44 varset (16{23) :::::::::::::::::::::::::::::::::::::::::::::::::: 45 varbind (24{31)::::::::::::::::::::::::::::::::::::::::::::::::: 46 call (32{39) :::::::::::::::::::::::::::::::::::::::::::::::::::: 47 unbind (40{47) :::::::::::::::::::::::::::::::::::::::::::::::::: 49 3.3 Constants-Vector Retrieval Instructions :::::::::::::::::::::::: 50 constant (192{255) ::::::::::::::::::::::::::::::::::::::::::::: 50 constant2 (129) :::::::::::::::::::::::::::::::::::::::::::::::: 51 3.4 Exception-Handling Instructions ::::::::::::::::::::::::::::::: 52 pophandler (48) :::::::::::::::::::::::::::::::::::::::::::::::: 52 pushconditioncase (49) :::::::::::::::::::::::::::::::::::::::: 53 pushcatch (50):::::::::::::::::::::::::::::::::::::::::::::::::: 54 3.5 Control-Flow Instructions:::::::::::::::::::::::::::::::::::::: 55 goto (130) :::::::::::::::::::::::::::::::::::::::::::::::::::::: 55 goto-if-nil (131) :::::::::::::::::::::::::::::::::::::::::::::: 56 goto-if-not-nil (132) ::::::::::::::::::::::::::::::::::::::::: 57 goto-if-nil-else-pop (133) ::::::::::::::::::::::::::::::::::: 58 goto-if-not-nil-else-pop (134) ::::::::::::::::::::::::::::::: 59 return (135) :::::::::::::::::::::::::::::::::::::::::::::::::::: 60 switch (183) :::::::::::::::::::::::::::::::::::::::::::::::::::: 61 3.6 Function-Call Instructions ::::::::::::::::::::::::::::::::::::: 62 3.6.1 Lisp Function Instructions :::::::::::::::::::::::::::::::: 62 symbolp (57) ::::::::::::::::::::::::::::::::::::::::::::::::: 62 consp (58) ::::::::::::::::::::::::::::::::::::::::::::::::::: 63 stringp (59) ::::::::::::::::::::::::::::::::::::::::::::::::: 64 listp (60) ::::::::::::::::::::::::::::::::::::::::::::::::::: 65 eq (61) ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 66 memq (62) :::::::::::::::::::::::::::::::::::::::::::::::::::: 67 not (63):::::::::::::::::::::::::::::::::::::::::::::::::::::: 68 symbol-value (74) ::::::::::::::::::::::::::::::::::::::::::: 69 iv symbol-function (75) ::::::::::::::::::::::::::::::::::::::: 70 set (76):::::::::::::::::::::::::::::::::::::::::::::::::::::: 71 fset (77) :::::::::::::::::::::::::::::::::::::::::::::::::::: 72 get (78):::::::::::::::::::::::::::::::::::::::::::::::::::::: 73 equal (154) :::::::::::::::::::::::::::::::::::::::::::::::::: 74 member (157) ::::::::::::::::::::::::::::::::::::::::::::::::: 75 assq (158) ::::::::::::::::::::::::::::::::::::::::::::::::::: 76 numberp (167) :::::::::::::::::::::::::::::::::::::::::::::::: 77 integerp (168)::::::::::::::::::::::::::::::::::::::::::::::: 78 3.6.2 List Function Instructions :::::::::::::::::::::::::::::::: 79 nth (56):::::::::::::::::::::::::::::::::::::::::::::::::::::: 79 car (64):::::::::::::::::::::::::::::::::::::::::::::::::::::: 80 cdr (65):::::::::::::::::::::::::::::::::::::::::::::::::::::: 81 cons (66) :::::::::::::::::::::::::::::::::::::::::::::::::::: 82 list1 (67) ::::::::::::::::::::::::::::::::::::::::::::::::::: 83 list2 (68) ::::::::::::::::::::::::::::::::::::::::::::::::::: 84 list3 (69) ::::::::::::::::::::::::::::::::::::::::::::::::::: 85 list4 (70) ::::::::::::::::::::::::::::::::::::::::::::::::::: 86 listN (175) :::::::::::::::::::::::::::::::::::::::::::::::::: 87 length (71) :::::::::::::::::::::::::::::::::::::::::::::::::: 88 aref (72) :::::::::::::::::::::::::::::::::::::::::::::::::::: 89 aset (73) :::::::::::::::::::::::::::::::::::::::::::::::::::: 90 nthcdr (155) ::::::::::::::::::::::::::::::::::::::::::::::::: 91 elt (156) :::::::::::::::::::::::::::::::::::::::::::::::::::: 92 nreverse (159)::::::::::::::::::::::::::::::::::::::::::::::: 93 setcar (160) ::::::::::::::::::::::::::::::::::::::::::::::::: 94 setcdr (161) ::::::::::::::::::::::::::::::::::::::::::::::::: 95 car-safe (162)::::::::::::::::::::::::::::::::::::::::::::::: 96 cdr-safe (163)::::::::::::::::::::::::::::::::::::::::::::::: 97 nconc (164) :::::::::::::::::::::::::::::::::::::::::::::::::: 98 3.6.3 Arithmetic Function Instructions:::::::::::::::::::::::::: 99 sub1 (83) :::::::::::::::::::::::::::::::::::::::::::::::::::: 99 add1 (84) ::::::::::::::::::::::::::::::::::::::::::::::::::: 100 eqlsign (85) :::::::::::::::::::::::::::::::::::::::::::::::: 101 gtr (86) :::::::::::::::::::::::::::::::::::::::::::::::::::: 102 lss (87) :::::::::::::::::::::::::::::::::::::::::::::::::::: 103 leq (88) :::::::::::::::::::::::::::::::::::::::::::::::::::: 104 geq (89) :::::::::::::::::::::::::::::::::::::::::::::::::::: 105 diff (90) ::::::::::::::::::::::::::::::::::::::::::::::::::: 106 negate (91) ::::::::::::::::::::::::::::::::::::::::::::::::: 107 plus (92) ::::::::::::::::::::::::::::::::::::::::::::::::::: 108 mult (95) ::::::::::::::::::::::::::::::::::::::::::::::::::: 109 max (93) :::::::::::::::::::::::::::::::::::::::::::::::::::: 110 min (94) :::::::::::::::::::::::::::::::::::::::::::::::::::: 111 quo (165) ::::::::::::::::::::::::::::::::::::::::::::::::::: 112 rem (166) ::::::::::::::::::::::::::::::::::::::::::::::::::: 113 3.6.4 String Function Instructions ::::::::::::::::::::::::::::: 114 substring (79) ::::::::::::::::::::::::::::::::::::::::::::: 114 v concat2