GNU Emacs Lisp Bytecode Reference Manual .diff (90 ... If we look at the relative ratio of C++to

Embed Size (px)

Text of GNU Emacs Lisp Bytecode Reference Manual .diff (90 ... If we look at the relative ratio of C++to

  • GNU Emacs Lisp Bytecode Reference

    ManualCollated and edited by Rocky Bernstein with contibutions from Pipcet, Chris Wellons,Stefan Monnier, Hallvard Breien Furuseth, and the Emacs community.

    1

  • i

    Short Contents

    1 Introduction to Emacs Lisp Byte Code and LAP . . . . . . . . . . . . 12 Emacs Lisp Bytecode Environment . . . . . . . . . . . . . . . . . . . . . . . 6

    3 Emacs Lisp Bytecode Instructions . . . . . . . . . . . . . . . . . . . . . . . 304 Instruction Changes Between Emacs Releases . . . . . . . . . . . . . 1535 Opcode Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1616 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Instruction Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

    Bytecode Function Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

  • ii

    Table of Contents

    1 Introduction to Emacs Lisp ByteCode and LAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 Why is Emacs Lisp Bytecode Important and How isEmacs as a Program Different? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

    1.2 Emacs Lisp Bytecode and LAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Example showing use of byte-compile-lapcode . . . . . . . . . . . . . . . . . . 3

    1.3 Emacs Lisp Virtual Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 Wither Bytecode - Its Future . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

    2 Emacs Lisp Bytecode Environment . . . . . . . . . . . . 62.1 Emacs Lisp Bytecode Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

    2.1.1 Function Parameter (lambda) List . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.2 Bytecode Unibyte String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.1.3 Constants Vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.1.4 Maximum Stack Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.1.5 Docstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.1.6 Interactive Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Examples showing the interactive specification . . . . . . . . . . . . . . . . . 12

    2.2 Emacs Lisp Bytecode Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.3 Emacs Lisp Bytecode Interpreter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.4 Emacs Lisp Bytecode Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.5 Emacs Lisp Bytecode Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.6 Functions and Commands for working with LAP and Bytecode . . 18

    2.6.1 aref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.6.2 batch-byte-compile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.6.3 batch-byte-recompile-directory . . . . . . . . . . . . . . . . . . . . . . . 192.6.4 byte-code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.6.5 byte-compile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.6.6 byte-compile-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.6.7 byte-compile-sexp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.6.8 byte-recalc-examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.6.9 byte-recompile-directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.6.10 byte-recompile-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.6.11 compile-defun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.6.12 disassemble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.6.13 disassemble-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.6.14 disassemble-full . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.6.15 display-call-tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.6.16 functionp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.6.17 make-byte-code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.6.18 symbol-function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

    2.7 Bytecode Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

  • iii

    2.7.1 Constant Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.7.2 Unreachable Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.7.3 Strength Reduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

    2.8 Bytecode Disassembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

    3 Emacs Lisp Bytecode Instructions . . . . . . . . . . . . 303.1 Instruction-Description Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

    3.1.1 Instruction Jargon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303.1.2 Instruction Description Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

    3.2 Argument-Packing Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33stack-ref (17) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33varref (815) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34varset (1623) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35varbind (2431) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36call (3239) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37unbind (4047) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

    3.3 Constants-Vector Retrieval Instructions . . . . . . . . . . . . . . . . . . . . . . . . 39constant (192255) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39constant2 (129) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

    3.4 Exception-Handling Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41pophandler (48) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41pushconditioncase (49) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42pushcatch (50) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

    3.5 Control-Flow Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44goto (130) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44goto-if-nil (131) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45goto-if-not-nil (132) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46goto-if-nil-else-pop (133) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47goto-if-not-nil-else-pop (134) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48return (135) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49switch (183) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

    3.6 Function-Call Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513.6.1 Lisp Function Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

    symbolp (57) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51consp (58) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52stringp (59) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53listp (60) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54eq (61) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55memq (62) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56not (63) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57symbol-value (74) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58symbol-function (75) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59set (76) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60fset (77) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61get (78) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .