Emacs Tips(持续更新)

Records

(setq si (make-record 'salt 5 'x))

(type-of si)                            ; => 'salt

(setq sii (make-record si 5 'z))

(setf (aref si 1) 'saltII)

(type-of sii)                           ; => 'saltII

Finalizer Type

(setq obj (make-finalizer #'(lambda () (message "Do something"))))
(setq obj 1)
(garbage-collect)      ;; 手动执行垃圾回收

Forms

• 自运算form (Self-Evaluating Forms)
  

  自运算 form 就是 list 和 symbol 之外的 form,它们的运算结果是它们自己,比如 number, string 和 vector 对象运算结果就是它们自己.

  这种 form 可以直接写下来,这是很常见的事情,但是对于那些没有读取语法(read syntax)的类型就不怎么常见了,不过还是可以做得到的,比如,

  ;; Build an expression containing a buffer object.
  (setq print-exp (list 'print (current-buffer)))
  ;; ⇒ (print #<buffer eval.texi>)
  ;; Evaluate it.
  (eval print-exp)
  ;; ⊣ #<buffer eval.texi>
  ;; ⇒ #<buffer eval.texi>
  

  symbol 中 nil, t 以及 : 开头的 symbol 都是比较特殊的,它们被 Emacs Lisp 看做常量不可改变,都属于自运算 form.

• List Forms分类 (Classifying Lists)
  

  一个非空列表有可能是一个函数调用,或者是一个 special form,又或者是一个宏调用, Emacs 是根据列表的第一个元素来判断的,其它元素则是组成参数.

  函数,宏以及 special form 三者的运算方式是不一样的.

• 函数的间接调用 (Function Indirection)
  

  如果 list 的第一个元素是 symbol,运算的第一步会检查这个 symbol 的 function cell 并使用里面的内容,如果里面的内容是另外一个 symbol,那么重复这个过程,直到获取到一个 non-symbol.

  这个过程叫做 symbol 函数的间接调用(symbol function indirection),这个过程有可能会是一个无限循环,一个 symbol 的 function cell 最终引用到它自己身上就会发生这种情况.

  正确的情况下,这个 non-symbol 应该是函数, lambda 表达式, 字节码函数(byte-code function), 原函数(primitive function),宏(macro), special form 和 autoload 对象的其中一个.

  不正确的情况 Emacs 会引发一个 invalid-function 错误. fset 和 symbol-function 能够分别设置和获取 symbol 的 function cell.

  比如这个文档的例子,

  ;; Build this function cell linkage:
  ;;   -------------       -----        -------        -------
  ;;  | #<subr car> | <-- | car |  <-- | first |  <-- | erste |
  ;;   -------------       -----        -------        -------
  (symbol-function 'car)
  ;; ⇒ #<subr car>
  (fset 'first 'car)
  ;; ⇒ car
  (fset 'erste 'first)
  ;; ⇒ first
  (erste '(1 2 3))   ; Call the function referenced by ‘erste’.
  ;; ⇒ 1
  

  如果第一个元素是 lambda 表达式,那么就不会发生函数间接调用了.

  indirect-function 能够获取 symbol 的真正含意,比如上面例子的后续,

  (indirect-function 'erste) ; ⇒ #<subr car>
  

• 函数Form (Function Form)
  

  如果 list 的第一个函数是 function, byte-code function 或者 primitive function,那么这个 list 就是一个函数调用(function call).

  function call. 运算的第一步是计算出除了第一个元素之外所有元素的值,也就是参数的值,每个参数都有一个值.下一步就是根据这些值来调用函数: (apply 'FIRST-ELEMENT '(REST-ELEMENT-VALUES ...)).

  函数是用 Lisp 写的,那么参数会被绑定到函数的参数变量上,然后按顺序运算函数体里面的 form,最后一个 form 的值就是函数调用的结果.

• 宏Forms (Macro Forms)
  

  如果 list 的第一个元素是 macro 对象,那么这个 list 就是一个宏调用 (macro call).宏调用的情况下, list 剩余的元素是不会被马上运算的.

  这些元素会做为宏的参数,计算的时机由宏决定.宏的定义实际是计算出一个替代 form (replacement form),这叫做宏的展开式 (expansion of the macro): 一个新的 form 用来替代原来的 form.

  调用宏叫做展开宏调用,或者叫展开宏.宏的展开式可能是以下其中一种 form: 一个自运算常量,一个 symbol 或者是一个 list.如果展开式本身也是一个宏调用,展开处理会一直重复直到不能计算出展开式为止.

  一个宏调用是以运算完展开式为结束,然而,并非一得到宏的展开式就马上进行运算,因为其它 Lisp 的程序也会展开宏调用,并且它们"可能"会运算展开式.

  通常,宏的参数不会在计算宏的展开式中进行计算,而是应该做为宏的展开式的一部分,在展开式被运算的时候一起被运算.

  (defmacro mcadr (x)
    (list 'car (list 'cdr x)))
  ;; or using backquote
  
  (defmacro mcadr (x)
    `(car (cdr ,x)))
  
  
  (mcadr (cons 0 '(1 2 3))) ;; 展开式是 (car (cdr (cons 0 '(1 2 3))))
  

  注意上面上面的展示式有 (cons 0 '(1 2 3)),与宏调用发生时候传入的参数是一样的,并不是被运算后的 '(0 1 2 3).

• Special Forms (Special Forms)
  

  Special Form 是原函数的一种,它们的参数是不会被全部运算的.大部份 special forms 是用来定义控制结构或者执行变量绑定,这些都是函数不能做的.

  每个 special form 都有自己的运算规则,可以通过 special-form-p 来判断对象是不是 special form, 比如 (special-form-p 'and).

• 自动加载 (Autoloading)
  

  自动加载特性允许调用一个定义未被加载进 Emacs 的函数或者宏,自动加载对象指定了包含了定义的文件,它做为一个函数定义对应的 symbol 出现,调用这个 symbol 会自动加载指定的文件,然后调用真正的函数定义.

引用 (Quoting)

反向引用 (Backquote)

'(a (+ 1 2))
`(a (+ 1 2))

`(a ,(+ 1 2)) ; => '(a 3)

`(a ,@'(1 2)) ; => '(a 1 2)
`(a ,@(+ 1 2)) ; => '(a . 3)

(cons 'a '(1 2))  ; => '(a 1 2)
(cons 'a (+ 1 2)) ; => '(a . 3)

运算 (Eval)

(eval '(+ a 1) '((a . 1))) ; => 2

延迟运算 (Deferred Eval)

按序计算 (Sequencing)

模式匹配条件 (Pattern-Matching Conditional)

生成器 (Generators)

#!/usr/bin/env python3
def gen(x):
    while x > 0:
        print("%s was passed\n" % (yield x))
        x = x - 1
    return -1          # 引发 StopIteration 异常时候的返回值


def client(n):
    g1 = gen(n)
    g1.send(None)      # 等于 next(g1)
    while 1:
        try:
            res = g1.send(100)
            print("The return value %s from generator" % res)
        except StopIteration as e:
            return e.value


client(5)

g1 = gen(5)
# g1.send(None)
g1.close()

for i in gen(5):
    print("value is %s" i)


def subgen_wrapper(n):
    res = yield from gen(n)
    print("result is %s" % res)


for i in subgen_wrapper(5):
    print(i)

(require 'generator)
(setq lexical-binding t)

(iter-defun gen (x)
  (while (> x 0)
    (message (format "return yes %s\n" (iter-yield x)))
    (setq x (1- x)))
  -1)

(defun client (n)
  (let ((g1 (gen n)))
    (condition-case e
        (while t
          (message (format "the return value %s from generator\n" (iter-next g1 100))))
      (iter-end-of-sequence
       (print (cdr e))))))

(client 5)

(setq g1 (gen 5))
(iter-close g1)

(setq res (iter-do (i (gen 5))
            (message (format "value is %s\n" i))))  ;; res 为 -1

(iter-defun subgen-wrapper (n)
  (message (format "result is %s" (iter-yield-from (gen n)))))

(setq res (iter-do (i (subgen-wrapper 5))
            (message (format "value is %s\n" i))))

非本地退出 (Nonlocal Exits)

写于 2018/9/4

什么是函数 (What is a Function)

Lambda表达式 (Lambda Expressions)

• Lambda的组件 (Lambda Components)
  

  一个 lambda 表达式就是以下形式的一个列表.

  (lambda (ARG-VARIABLES...)
    [DOCUMENTATION-STRING]
    [INTERACTIVE-DECLARATION]
    BODY-FORMS...)
  

  第一个元素 lambda 是必定要有的,目的是为了与其他列表进行区分,以及告诉 Emacs 这个列表是一个函数.

  第二个元素 (ARG-VARIABLES...) 就是一个 symbol list,这些 symbols 都是参数(arguments)的名字.

  在调用函数的时候,参数的值就会根据该列表来进行匹配,形成 local bindings.

  第三个元素 DOCUMENTATION-STRING 是可选的,是一个 string 对象,用来描述该函数.

  第四个元素 INTERACTIVE-DECLARATION 也是可选的,是一个形式为 (interactive CODE-STRING) 的列表.

  这是用来声明在函数成为命令时候提供参数的方式,成为命令的函数可以通过 M-x 来调用或者被绑定到一个按键上.

  剩下部分就是函数体,在 Lisp 下我们叫做 a list of Lisp forms to evaluate,函数的返回值就是 BODY-FORMS 里的最后一个 form.

• 参数列表 (Argument List)
  

  参数列表的完整语法如下,

  (REQUIRED-VARS...
   [&optional [OPTIONAL-VARS...]]
   [&rest [REST-VAR]])
  

  REQUIRED-VARS... 是必要参数列表,在其他语言可能叫做 POSITION ARGUMENTS.

  定义函数的时候有多少个 REQUIRED-VAR,调用的时候就需要传入多少个实际参数(actual argument),否则会有 wrong-number-of-arguments 错误.

  &optional 后面的 OPTIONAL-VARS... 是可选参数,调用时候的参数数量不能超过定义时候的数量,并且传入的参数序号一定要和定义的匹配.

  &rest 后面跟着只有一个 REST-VAR,调用时传入的实际参数数量为大于等于0.

  结合上面的描述你会发现 &optional 以及 &rest 的参数在调用时是可以不传入的,不传入的情况下默认值是 nil.

  函数没有办法区分显示传入 nil 以及默认 nil.

  比如有一个这样的参数列表:

  (a b &optional c d &rest e)
  

  调用时候的参数数量:

  • 2个: a 和 b 分别绑定, c,d,e 都为 nil;
  • 3个: a, b 和 c 分别绑定, d,e 为 nil;
  • 大于等于5个: a,b,c,d 分别绑定传入的前四个参数,剩下的参数都被打包成一个列表和 e 进行绑定.

  和 Python 这些语言不一样, Emacs Lisp 不能在不传入 c, d 的情况下直接给 e 传入参数,必须给 c,d 传入 nil.

  和 Common Lisp 不同, Emacs Lisp 的函数不支持用户给可选参数设定默认值,也不支持原生定义关键字参数(keyword arguments),

  其实 Emacs Lisp 里面也是有使用了关键字参数的函数,比如 make-hash-table,

  EmacsWiki 上有如何自己实现 Keyword Arguments 的话题: 把 &rest 当作 plist 处理来实现类似与 Common Lisp 的关键字参数.

  比如这下面使用 Emacs 的关键字(keyword)类型作为参数列表中的关键字,

  (defun keyword-support-func (&rest keywords)
    (let ((key1 (plist-get keywords :key1))
          (key2 (plist-get keywords :key2)))
      (+ key1 key2)))
  
  (keyword-support-func :key2 2 :key1 1)
  

  也不一定要用关键字类型的,能够正确访问就可以,比如下面用普通 symbol 作为关键字,

  (defun keyword-support-func (&rest keywords)
    (let ((key1 (plist-get keywords 'key1))
          (key2 (plist-get keywords 'key2)))
      (+ key1 key2)))
  
  (keyword-support-func 'key2 2 'key1 1)
  

  不过这样不符合(Common Lisp 的)"规范",因此在实际中看到的都是第一种.

  除此以外可以通过 cl-lib 的 cl-defun 宏来使用 Common Lisp 那样的函数定义方式.

• 函数文档 (Function Documentation)
  

  lambda 表达式有一个可选的文档字符串,该字符串不影响函数执行,就是一个注释,它会被 Emacs 里面的帮助文档功能适用,比如 apropos 会显示文档字符串的第一行,

  所以第一行文档字符串应该用一两句话来总结函数的意图.写文档字符串的时候需要注意几点:

  1. 文档字符串的第一行总是会自动缩进,比如下面这样,

  (defun fn-example (arg)
    "This is an examnple only to show the indetation of
  the documentation string."
    )
  

  这样是正确的,但是有人会这么做,

  (defun fn-example (arg)
    "This is an examnple only to show the indetation of
     the documentation string."
    )
  

  这是错误的,虽然在源代码中看起来不错,但这在帮助功能的显示下会十分难看.

  1. 最后一行可以指定调用规范,比如

  (defun fn-example (arg)
    "This is the example only to show how document looks like.
  
  \(fn-example ARG)"
    )
  

  \ 的使用是为了避免和 Emacs 的动作命令(motion commands)搞混.

函数名字 (Function Names)

定义函数 (Defining Functions)

调用函数 (Calling Functions)

(defun example (a b c)
  (+ a b c))

(defun partial-example (c)
  (+ 1 2 c))

(((lambda (x)
    (lambda (y)
      (+ x y))) 1) 2)

(funcall
 ((lambda (y)
    (lambda (x) (+ y x)))
  2)
 1)

匿名函数 (Anonymous Functions)

通用函数 (Generic Functions)

(cl-defgeneric genericFunc (a)
  "Example for generaic" nil
  (message "Body as default method"))

(genericFunc 0) ;; 如果没有提供方法,那么就调用提供的函数体,作为默认方法

;; 提供方法,方法的参数可以和通用函数定义的不一样,因为目前而言定义通用函数时的参数不会被处理的

;; 提供主要实现, primary implementation

(cl-defmethod genericFunc ((a (eql 1))) ; (eql 1) 表示判断实际参数a是否等于1
  1)

(cl-defmethod genericFunc ((c (eql 2)))
  2)

(genericFunc 1) ; => 1
(genericFunc 2) ; => 2


;; 提供辅助实现, auxiliary method

(cl-defmethod genericFunc :before ((c (eql 3)))
  3)
;; 使用辅助实现要求通用函数提供函数体,否则会有 No primary method 报错
;; 辅助函数对通用函数有一个要求: 通用函数的参数数量要和辅助方法的参数数量一样,因为辅助方法的参数会传入到通用函数里面,这个时候需要参数数量一致.

闭包 (Closures)

#'(closure (t) (x) (* x x)) ; => 相当于 (lambda (x) (* x x))
(funcall #'(closure (t) (x) (* x x)) 2) ; => 相当于 ((lambda (x) (* x x)) 2)

Advising Functions

废弃函数 (Obsolete Functions)

内联函数 (Inline Functions)

(defun fake-inline-func () (message "hello")) ;; 这不是内联函数,只是用来演示,真正的内联函数请用 =defsubst= 或者 =define-inline=

(defun caller ()
  (fake-inline-func))

;; 被编译后,上面的部分等于以下

(defun caller ()
  (message "hello"))

Declare Form

声明函数 (Declaring Functions)

(declare-function shell-mode "shell" ()) ;; or shell.,el for 2nd argument

函数安全 (Function Safety)

宏例子 (Defining Macros)

(defmacro myif (cond-expr if-branch else-branch)
  (list 'if cond-expr
        if-branch
        else-branch))

(defmacro myif (cond-expr if-branch else-branch)
  `(if ,cond-expr
       ,if-branch
     ,else-branch))

(defmacro test-macro (&rest body)
  `(let ((a 1)
         (b 2))
     ,@body))

(test-macro
 (let ((c (+ a b))
       (d (- b a)))
   (+ c d))))       ;; => 4

宏的展开式 (Expansion)

(defmacro prefixed-setq (name value)
  `(set (intern (format "prefixed-%s" (symbol-name (quote ,name)))) ,value))

(prefixed-setq var 1)
;; (macroexpand-1 '(prefixed-setq var 1)) => (set (intern (format "prefixed-%s" (symbol-name (quote var)))) 1)
(+ prefixed-var 1)

宏和编译 (Compiling Macros)

(defmacro myif (cond-expr if-branch else-branch)
  (message "Some imporant side effects just like me")
  (list 'if cond-expr
        if-branch
        else-branch))

(if cond-expr if-branch else-branch)

(defmacro myif-mod (cond-expr if-branch else-branch)
  (if (eq system-type 'windows-nt)
      (list 'or (list 'and cond-expr if-branch)
            else-branch)
    (list 'if cond-expr
          if-branch
          else-branch)))
;; 在 Windows 上编译得到 form 只会为: (or (and cond-expr if-branch) else-branch),
;; 在其它系统上编译得到的 form 只会为: (if cond-expr if-branch else-branch)

(eval-when-compile
  (require 'macro-definition))

宏的问题 (Problems With Macros)

• 时机错误 (Wrong Time)
  

  这是最常见的问题之一: 在展开宏的时候处理想要完成事情,而不是在展开式本身进行处理.

  假设有一个宏想要设置缓冲区为 multibyte 缓冲区,

  (defmacro my-set-buffer-multibyte (arg)
    (if (fboundp 'set-buffer-multibyte)
        (set-buffer-multibyte arg)))
  

  在直译模式下这个宏是能够正确完成任务的,然后在编译后是不行的,理由可以参考上面的 宏和编译.

  正确的做法是,

  (defmacro my-set-buffer-multibyte (arg)
    (if (fboundp 'set-buffer-multibyte)
        `(set-buffer-multibyte ,arg)))
  

• 重复运算宏的参数 (Argument Evaluation)
  

  定义宏的时候需要注意运行展开式的时候参数的运算次数.

  比如定义一个 for 循环结构,

  (defmacro for (var from init to final do &rest body)
    "Execute a simple \"for\" loop.
       For example, (for i from 1 to 10 do (print i))."
    (list 'let (list (list var init))
          (cons 'while
                (cons (list '<= var final)
                      (append body (list (list 'setq var (list '1+ var)))))))))
  

  它的 backquote 版本如下,

  (defmacro for (var from init to final do &rest body)
    `(let ((,var ,init))
       (while (<= ,var ,final)
         ,@body
         (setq ,var (1+ ,var)))))
  

  下面是它的一个调用的展开式,

  (for i from 1 to 3 do
       (setq square (* i i))
       (princ (format "\n%d %d" i square)))
  ↦
  (let ((i 1))
    (while (<= i 3)
      (setq square (* i i))
      (princ (format "\n%d %d" i square))
      (setq var (1+ var))))
  
  ⊣1       1
  ⊣2       4
  ⊣3       9
  ⇒ nil
  

  from, to 以及 do 就是语法糖(syntactic sugar),可以无视它们.

  这里有一个问题,在每一轮迭代中,参数 final 都会进行运算,

  如果 final 是常量的话没有问题;

  如果是一个复杂的 form, 比如一个耗时的函数调用,那么这会造成严重的性能问题,

  并且如果 final 存在副作用,多次执行可能照成一些意想不到的结果.

  正确的做法应该是把 final 的计算放到循环之外,

  (defmacro for (var from init to final do &rest body)
    `(let ((,var ,init)
           (max ,final))
       (while (<= ,var max)
         ,@body
         (setq ,var (1+ ,var)))))
  

  不过这样会引入另外一个问题,下个小节接着讨论它.

• 展开式的局部变量覆盖用户定义的变量 (Surprising Local Vars)
  

  上一个章节说的引入的问题是引入了新的变量 max,如果使用该宏的时候用户也定义了一个 max 的变量,

  (let ((max 0))
    (for x from 0 to 10 do
         (let ((this (frob x)))
           (if (< max this)
               (setq max this)))))
  

  通过观察这个 form 的展开式可以看到用户的 max 被 for 宏里面的 max 遮掩了,因此用户定义的 max 就没用了.

  解决这个问题的核心在于如何避免临时宏的变量 max 不会和用户的变量发生冲突,正好 Lisp 有 uninterned symbol,

  这种 symbol 可以被绑定以及被引用,并且不会和任何其它的 symbol 发生冲突,哪怕是同名的 symbol,

  如果不进行绑定的话,这种 symbol 就没法引用了.

  可以利用这特性来解决上面的问题,

  (defmacro for (var from init to final do &rest body)
    (let ((tempvar (make-symbol "max")))
      `(let ((,var ,init)
             (,tempvar ,final))
         (while (<= ,var ,tempvar)
           ,@body
           (setq ,var (1+ ,var))))))
  

  uninterned symbol max (make-symbol 生成的 max) 不会和 interned symbol max (用户定义的 max) 发生冲突.

• 展开时运算参数 (Eval During Expansion)
  

  PS: 标题是 "Eval During Expansion", During 说明了 Expansion

  另外一个问题,就是不要在展开时通过调用 eval 这样的方式去对参数(arguments)进行运算,

  因为一旦用户传入的变量名字和参数名字一样就会出现问题,

  比如下面要引用 用户传入的变量 所指向的 变量,

  (defmacro foo (a)
    (list 'setq (eval a) t))
  
  (setq x 'b)
  
  (foo x)  ;; -> (setq b t)
  
  (setq a 'c)
  
  (foo a) ;;-> (setq a t), 这是因为用户传入的参数和宏定义的参数发生冲突了
  

  因此定义的宏最好 别 在展开过程中运算参数.

• 重复展开 (Repeated Expansion)
  

  如果在直译函数里面执行宏调用,那么每次调用都会展开;对于编译函数,那么宏调用只会在编译时展开一次,之后编译函数只会调用编译好的展开式.

  因为这个原因,如果宏的定义有副作用,那么宏调用的次数不同就有可能会产生不同结果,直译函数每次都会产生副作用,而编译函数只有编译的时候才会产生副作用.

  因此尽量不要在宏展开的时候使用副作用(可以在展开式中使用),比如,

  (defmacro my-message (msg)
    `(message msg))
  
  ;; NOT THIS
  (defmacro wrong-message (msg)
    (message msg))
  

  只有一种副作用不能避免: 构建 Lisp 对象.这是大部份宏的重点,这是没问题的,只有一种情况需要注意:

  构建的对象是宏展开式的一个被引用常量(quoted constant)的一部分.

缩进宏 (Indenting Macros)

更多的宏例子

程序的加载过程 (How Programs Do Loading)

加载后缀 (Load Suffixes)

库的查找 (Library Search)

加载非 ASCII 字符 (Loading Non-ASCII)

自动加载 (Autoload)

;; source.el

;;;###autoload
(defun fn-to-call () (message "Hello"))

(provide 'source)

编译字节函数 (Compilation Functions)

文档字符串和编译 (Docs and Compilation)

动态加载个别函数 (Dynamic Loading)

在编译期间运行 (Eval During Compile)

编译器错误 (Compiler Errors)

字节码函数对象 (Byte-Code Objects)

;; backward-sexp 的字节码

#[256                                   ;; ARGDESC
  "\211\204^G^@\300\262^A\301^A[!\207"  ;; BYTE-CODE
  [1 forward-sexp]                      ;; CONSTANTS
  3                                     ;; STACKSIZE
  1793299                               ;; DOCSTRING
  "^p"]                                 ;; INTERACTIVE

反汇编字节码(Disassembly)

(defun my-abs (num)
  (cond ((> num 0) num)
        ((= num 0) num)
        ((< num 0) (- num))))

byte code for my-abs:
  doc:   ...
  args: (arg1)
0       dup
1       constant  0
2       gtr
3       goto-if-nil 1
6       return
7:1     dup
8       constant  0
9       eqlsign
10      goto-if-nil 2
13      return
14:2    dup
15      constant  0
16      lss
17      goto-if-nil-else-pop 3
20      dup
21      negate
22:3    return

#[257
  "\211\300V\203^G^@\207\211\300U\203^N^@\207\211\300W\205^V^@\211[\207"
  [0]
  3
  "\n\n(fn NUM)"]

Debugger

• 错误调试 (Error Debugging)
  

  设定调试的入口,也就是什么时候才唤醒调试器.

  • debug-on-error

    设定该变量为 t ,可以在 debug-ignored-errors 以外的错误发生时进入调试, debug-ignored-errors 告诉调试器无视哪些错误.

    如果值是一个错误条件的列表,那么只有引发列表中的错误才会进入调试.

    当这个变量的值为 non-nil 的时候, Emacs 是不会为进程过滤函数和哨兵 (process filter functions and sentinels)创建错误处理器,也就是它们一旦有错误就会进入调试.

  • eval-expression-debug-on-error

    如果该变量为 t, 那么在执行 eval-expression 命令,默认 M-:,的时候动态绑定 debug-on-error 为 t,其它时候 debug-on-error 的值还是原来的值.

    也就是针对执行 eval-expression 发生的错误进行调试.

  • debug-on-signal

    正常来说, condition-case 捕捉到的错误是不会唤醒调试器的,因为 condition-case 在调试器之前处理了错误.

    假如 debug-on-signal 这个变量设定为 non-nil,那么调试器就可以无视 condition-case 在第一时间处理错误.

    这个变量可以在 Emacs 的 --eval 选项进行设定,如果运行时候发生了错误,那么 Emacs 就会弹出一个 backtrace.

    最好不要在编码中设定这个变量,因为会导致所有 condition-case 语句失去处理错误的机会,包括你计划外的部分.

    如果需要调试 condition-case 里面的代码,可以考虑使用 condition-case-unless-debug.

  • debug-on-event

    如果给该变量设定一个特别事件(special event),那么 Emacs 就会在接受到事件的第一时间绕过 special-event-map 进入调试器.

    目前值支持对应 SIGUSER1 和 SIGUSER2 的值,当设定好 inhibit-quit 并且在 Emacs 没有响应时候这个变量十分有用.

  • debug-on-message

    给该变量设定用来匹配回显区域(echo area)的消息(message)的正则表达式(regular expression),如果匹配就会进入调试.用来查找造成该消息的原因就很有用.

    比如,

    (setq debug-on-message
          ".*\"q\".*")
    
    (defun test ()
      (message "\"q\""))
    
    (test)
    

• 无限循环 (Infinite Loops)
  

  当程序死循环的时候,可以通过 C-g,也就是调用 keyboard-quit 来终止程序.这样直接停止的话是获取不了死循环的信息,可以设置 debug-on-quit 为 non-nil 来在 C-g 的时候进入调试.

• 函数调试器 (Function Debugging)
  

  如果想在调用特定函数的时候进入调试,可以通过使用 debug-on-entry 函数添加想要的调试的函数,比如 (debug-on-entry 'example).

  有一点要注意的是, debug-on-entry 不能直接添加 C 语言实现的原函数和 Special Forms,间接是可以的,也就是 Lisp 函数用它们作为 subroutine.

  如果要取消对某个参数的调试,可以通过 cancel-debug-on-entry 来取消,比如 (cancel-debug-on-entry 'example).

• 直接调试 (Explicit Debug)
  

  可以在源代码中想要调试的位置添加 (debug) 来作为 breakpoint,然后可以通过 eval-defun 等方式运行调试.

• 使用调试器 (Using Debugger)
  

  进入 Emacs 调试器的时候会打开一个 *Backtrace* 缓冲区,它是一个使用了特别 major mode 的只读(read-only)缓冲区.

  这个 major mode 是 Debugger mode,把字母定义成调试命令.在该 mode 下依然可以做其它正常的 Emacs 操作,不过做这些操作之前最好用 q 命令退出调试.

  q 命令可以 *Backtrace* 缓冲区 并且退出调试.默认情况下,退出只是隐藏 *Backtrace* 缓冲区,也就是该缓冲区没有被杀掉.

  要杀掉的话就设定 debugger-bury-or-kill 为 'kill.

  (and
   (require 'debug)
   (setq debugger-bury-or-kill 'kill))
  

  在进入调试的时候会根据 eval-expression-debug-on-error 临时设置 debug-on-error 变量,如果前者为 non-nil,那么 debug-on-error 就会为 t.

  这意味如果在调试的时候出现了更多错误, Emacs 将会触发另外的 backtraces,如果不想这样的话可以在 debugger-mode-hook 里面把 eval-expression-debug-on-error 设置为 nil 或者把 debug-on-error 设置为 nil.

  关于如何查看调试器

  Backtrace 缓冲区 展示运行中的函数以及它们的参数值,可以该缓冲区在上面通过移动 Emacs 指针到对应的行来选择一个栈帧(stack frame),栈帧是指 Lisp 直译器储存特定函数的调用信息(information about a particular invocation of a function)的位置.

  正在工作的栈帧被认为是当前帧(我也不太知道怎么翻译和理解,原文: The frame whose line point is on is considered the “current frame”.),只有一些调试命令可以操作当前栈帧.

  Backtrace 的栈帧是倒着的,也就是要从底往上读(read from bottom up)才是正确的执行顺序,也就是正序第一行就是当前栈帧.

  某些行的前面会有星号,一个星号表示一个函数调用的出口,该栈帧会在这个出口再次调用调试器,没错,调试器是一个递归编辑,每次进入一个栈帧就是进入一个子调试器,简单点就是调试器会在带星号的栈帧停下进行调试.

  有一些函数名字会有下划线,这意味着调试器知道它们的源代码位置,可以通过鼠标点击或者指针加 <RET> 来浏览源代码.

  其中是没有发生报错和因为报错而进入调试模式,两种的顶行显示是不一样的.

  (setq debug-on-error t)
  
  (defun raise-error (a)
    (+ a nil))
  
  (raise-error (raise-error 1))
  

  

  Figure 1: 报错的时候

  上面可以看到一些行的前面有些"单词"会画上下划线,那些都是 Lisp 定义的函数或者宏,也是执行时候所调用的内容,从下往上看就是调用顺序.

  调试的时候可以根据这个"大纲"来快速定位问题发生的位置.

  (defun no-error (a)
    (+ a 1))
  
  (debug-on-entry 'no-error)
  
  (no-error (no-error 1))
  

  

  Figure 2: 没有错误的时候

  两者的提示是不一样的,除此以外,有一些命令在报错的时候是不可以执行的.比如 r 命令就不可以,因为错误是不能返回的.

  调试器本身一定要经过编译运行,因为需要假设调试器自身需要使用多少个栈帧.如果是直译运行调试器,假设就会失败.

• 调试器命令 (Debugger Commands)
  

  如果能理解 Emacs Lisp的调试器是一个递归编辑,每一个进入栈帧都是进入一个子调试器,文档上的说明就很好理解.尽管如此我还是要用自己的话总结一下(我没有了解以前可是一头雾水).

  • c: 执行并且退出当前栈帧的调试,在下一个星号标记的栈帧处停止.
  • d: 进入当前栈帧并且给该栈帧添加星号, debug-on-entry 实际上就是给指定的函数添加星号.进入后可以通过c命令跳出.
  • b: 给当前栈帧添加星号.
  • u: 取消当前栈帧的星号.
  • j: 给当前栈帧添加星号然后和c命令一样执行,不过会无视 debug-on-entry 设定的星号(或者说临时禁止所有函数的break-on-entry). c 和 j 的区别可以通过调试上面没有错误的例子来了解一下.
  • e: 在 minibuffer 读取 Lisp 表达式并且(如果可以的划在当前词法环境)进行运算以及在回显区域(area echo)打印结果.调试器会在外部临时储存和恢复运行时变量值,所以可以随意检查和更改运行时的值.
  • R: 和e命令一样,不同的是R命令会储存计算结果到 *Debugger-record*.
  • q: 终止调试器(最开始的调试器),返回 Emacs 的 top-level.
  • r: 在带星号的栈帧返回时指定它的返回值,用于 mock.
  • l: 显示一个函数列表,这些函数都是会唤醒调试器的.
  • v: 切换显示当前栈帧的本地变量.
• 唤醒调试器 (Invoking the Debugger)
  

  关于 debug 函数的细节.该函数的第一个参数可以用来改变 *Backtrace* 顶部的提示信息 "Debugger entered–XXX".具体看文档就好.

• 调试器内部 (Internals of Debugger)
  

  关于调试器内部使用的函数和变量.

  • debugger 变量: 用来指定调用 debug 函数时候使用的参数,默认是 debug,参考 debug 函数的细节, M-: (info "(elisp) Internals of Debugger").
  • backtrace 函数: debug 函数使用该函数给 *Backtrace* 缓冲区填充,它是用C语言写的,因为必须要访问栈来判断函数调用是否 active,返回值总是 nil,该函数的输出默认到 standard-output 的.
  • debug-on-next-call 变量: non-nil 表示在下一个 eval, apply 或者 funcall 之前调用调试器,进入调试器后把它设置为 nil.调试器的d命令就是通过设置这个变量来工作.如果直接手动设置该变量会进入调试器,可以试试.
  • backtrace-debug 函数: 设置 LEVEL 级别的栈帧的 debug-on-exit flag 为 FLAG, LEVEL 和 FLAG 是函数的参数. FLAG 为 non-nil 则是说在当前栈帧结束后进入调试器.
  • command-debug-status 变量: 记录当前交互命令的调试状态,每一次交互式调用命令就会把这个变量绑定为 nil.调试器可以设置这个变量来给在调试时引发的新调试器调用(debugger invocation)留下信息.
  • backtrace-frame 函数: 返回第 FRAME-NUMBER 层级栈帧的信息.

使用 Edebug 调试

Edebug

• 使用Edebug (Using Edebug)
  

  使用 Edebug 调试需要先 instrument Lisp 代码,最简单的做法就是把指针移动到函数或者宏的定义然后执行 C-u C-M-x ,也就是带前缀参数的 eval-defun 命令.

  一旦完成,任何该函数/宏的调用就会激活 Edebug,定义的源代码的缓冲区就会临时变成 read-only,当行的左边会有一个箭头表示当前执行的行,然后就可以在上面执行调试命令.

  和 Debugger 一样,每一个 list 表达式的前面和后面都是点,和变量引用的后面也是点, Edebug 可以在这些点上面停止执行,叫做停止点(stop points).

  可以通过 <SPC> 来执行直到下一个停止点,当 Edebug 在一个表达式后面停止执行,就会在回显区域里面显示表达式的值.

  其它常用命令有:

  • b: 在停止点设置 breakpoint
  • g: 执行直到到达一个 breakpoint
  • q: 退出 Edebug
  • ?: Edebug 的帮助命令
• Instrumenting
  

  Instrumenting 代码其实就是给源代码插入额外的代码(当然并没有修改源代码),用来在合适的地方唤醒 Edebug.

  如果要移除代码的 instrumentation,只要以不添加 instrumentation 的方式重新运行一遍就好了.(在 instrumenting 之后修改源代码会导致 instrumentation 失效).

  如果接移除单个定义的 instrumentation,可以在定义上面执行 C-M-x,也就是 eval-defun 命令.

  可以通过 M-x edebug-all-defs 来切换 edebug-all-defs 变量,该变量可以控制 eval-defun 是否使用前缀参数来 instrument 定义, nil 表示需要.

  如果 edebug-all-defs 为 non-nil,那么直接移除单个定义的 instrumentation 就需要 C-u C-M-x,为 non-nil 时候还可以配合 eval-region, eval-current-buffer 和 eval-buffers 命令来批量 instrument,

  如果要批量移除 instrumentations 先把 edebug-all-defs 切换回去再次运行命令就可以了(可以用 eval-buffer 体验一下).

  还有一个特定用来控制 eval-region 是否 instrument 的 edebug-all-forms.

  M-x edebug-eval-top-level-form 会无视 edebug-all-defs 和 edebug-all-forms 的值来进行 instrumenting. edebug-defun 是它的别名.

  当 Edebug 激活的时候,命令I (edebug-instrument-callee) 可以根据调用来 instrument 定义(当然只能是没有添加instrumentation的情况下).

  比如,

  (defun fac (n)
    (if (< 0 n)
        (* n (fac (1- n)))
      (return-res 1)))
  
  (defun return-res (n)
    (+ n 0))
  
  (fac 3)
  

  如果 edebug 激活了,上面 instrument fac 只会给 fac 添加 instrumentation,调试的时候可以把指针移动到 (return-res 1) 的前面使用I命令,

  这样在 fac 调用 (return-res 1) 的时候就会进入 return-res .当然只能在 Edebug 知道定义源代码位置的时候才可以使用这命令.

  如果想直接跳进 return-res,可以直接使用i命令,它会先是 instrument 定义并且直接跳转.

  Edebug 知道如何 instrument 所有标准 special forms,但是不能靠它自己判断用户定义宏(user-defined macro)的参数信息.

  因此唯一通过使用 Edebug specifications 来提供信息.当 Edebug 第一次 instrument 代码,它会运行 edebug-setup-hook 钩子然后把这个钩子设置为 nil,可以使用这个钩子提供 Edebug specification.

• Edebug执行模式 (Edebug Execution Modes)
  

  Edebug 有很多个执行模式,比如可以手动逐步执行,可以自动逐步执行,可以手动逐个断点执行,当然也可以自动逐个断点执行,甚至可以无视断点执行.

  在两种情况下可以设定模式,分别是使用对应模式的命令来设定调试时的模式和设定调试开始时的模式.

  文档没有明说, Edebug 和 Debugger 一样都是递归编辑,每运算一次表达式都是进入 Edebug,自己要清楚这一点.

  下面是命令,

  • S: Stop,不再执行调试,等待调试命令.
  • <SPC>: Step,在下一个停止点处停止.
  • n: Next,在下一个表达式的后面的停止点处停止.
  • t: Trace,默认每一秒后运行到下一个停止点,就是 <SPC> 的自动模式.
  • T: Rapid trace, t 的快速执行模式,中间没有停顿.
  • g: Go,运行到下一个断点.
  • c: Continue,在每个断点处停留一秒,然后继续,就是 g 的自动模式.
  • C: Rapid continue: c 的快速执行模式,中间没有停顿.
  • G: Go non-stop,无视断点执行,可以通过 S 停止.

  可以通过 edebug-set-initial-mode 命令设置 edebug-initial-mode 来设定 Edebug 的初始模式.

  对于自动模式的停顿时间,可以通过设置 edebug-sit-for-seconds 变量来修改.

• 跳转 (Jumping)
  

  跳转就是指执行到哪个停止点.命令如下,

  • h: 执行到下一个断点.
  • f: 执行完一个表达式.
  • o: 执行完一个 containing sexp,也就是跳出(step out).
  • i: 跳进一个停字点后面函数或者宏(step in).

  具体说明还是看文档吧.

• Edebug 的杂项命令 (Edebug Misc)
  
  • ?: 帮助命令.
  • C-]: 终止(abort)一个 level 返回到上一个 command level.
  • q: 返回到 top level,也就是停止 edebug 调试器.然而,被 unwind-protect 或者 condition-case 保护的 instrumented code 会恢复 edebug.
  • Q: 像 q 一样,不过无视被保护的代码.
  • r: 重新显示最近的表达式的结果.
  • d: 显示 backtrace,这个 backtrace 不像标准的 Debugger 那样执行命令.继续执行的时候会自动关闭 backtrace.
• 中断 (Breaks)
  

  一旦 Edebug 开始,除了 step mode 可以在下一个停止点停止执行,还有其它三种方法可以停止执行.

  • 断点 (Breakpoints)
    

    可以在任何一个停止点设置断点.关于断点的命令如下:

    • b: 在停止点设置断点.如果使用了前缀参数,断点就是临时的,停止调试后断点就失效了.
    • u: 取消断点.
    • x CONDITION <RET>: 条件断点,只有 CONDITION 结果为 non-nil 才会停止.同样,如果使用了前缀参数的话就是临时的.
    • B: 移动到当前定义的下一个断点.
  • 全局中断条件 (Global Break Condition)
    

    全局中断条件不管在哪里,只要条件符合就停止调试的执行. Edebug 会在每个停止点运算全局中断条件的值,如果结果为 non-nil 就停止或者暂停执行,和断点一样.然而如果运行条件的时候报错是不会停止.

    条件表达式储存在 edebug-global-break-condition 变量里面.可以在已经激活了 Edebug 的源代码缓冲区中使用X命令来添加条件表达式,也可以使用 C-x X X 按键(绑定 edebug-set-global-break-condition)在任何缓冲区中添加条件表达式.

    全局中断条件很容易让调试变慢,如果不使用的话要把 edebug-global-break-condition 设置为 nil.

  • 源码断点 (Source Breakpoints)
    

    上面通过b命令设置的断点会在 reinstrument 定义后被遗忘(除了Emacs,人也可能会忘记),这个时候可以使用"源码断点"(和 Debugger 的 (debug) 的用法一样).

    在想要断点的地方插入 (edebug) 表达式,如果定义没有被 instrument,那么遇到 (edebug) 就会转而调用 debug 函数.可以使用g命令跳转到这种断点身上.

• 捕捉错误 (Trapping Errors)
  

  设置 edebug-on-error 或者 edebug-on-quit 可以快速定位没有被处理错误(unhandled errors),就拿 edebug-on-error 来说,它和 debug-on-error 的设置类似,用下面的例子来演示.

  (setq edebug-on-error t)
  
  ;; 当然要先 instrument fac 的定义,这是必须的
  (defun fac (n)
    (if (< 0 n)
        (* n (fac (1- n)))
      (return-res nil))) ; 错误在这里,会在 (return-res nil)前面的停止点停下
  
  (defun return-res (n)
    (+ n 0))
  
  (fac 3)
  

  在这个例子中可以使用 Rapid Trace 模式来直接运行到错误发生的地方,会发生和注释一样的结果.如果把 edebug-on-error 设置为 nil,是不会停止到错误发生的地方,而是直接在回显区域显示信息.

• Edebug Views
  

  一些用来浏览已经激活 Edebug 的缓冲区和窗口状态的各个方面.

  外部窗口配置(outside window configuration) 集合了窗口(windows)和在 Edebug 外部有效(in effect)的内容(个人认为像是发生调用的地方).

  • v: 切换到外部窗口配置中.
  • p: 临时切换到等待 N 秒(可以通过 C-u N p 设定暂停时间)后返回 Edebug 中.
  • w: 把点(point)返回到到源码缓冲区当前的停止点上.
  • W: 切换是否保存和恢复外部窗口配置,有前缀参数的话就表明只是对被选择窗口切换是否保存和恢复.
• 运算 (Edebug Eval)
  

  当 Edebug 启用的时候,你可以像在没有运行 Edebug 的情况下运算表达式.

  • e EXP <RET>,在 Edebug 外部的上下文运算表达式 EXP.这样 Edebug 可以减少它和运算之间的冲突/干扰(interference).
  • M-: EXP <RET>,在 Edebug 的上下文中运算表达式 EXP.
  • C-x C-e,在 Edebug 外面运算点之前表达式.

  Edebug 支持运算引用由 cl.el 里面 lexical-let, macrolet 和 symbol-macrolet 词法绑定的 symbols 的表达式.

• 运算列表缓冲区 (Eval List)
  

  可以使用运算列表缓冲区(evaluation list buffer),叫做 *edebug* 的缓冲区,来交互运算表达式.也可以设置表达式的运算列表(evaluation list),这样它们在每次 Edebug 更新显示的时候都会更新.

  在 Edebug 激活之后使用 E 命令切换到运算列表缓冲区 – *edebug*,然后在里面添加元素表达式组(evaluation list groups).一个运算表达式组包含一到多条表达式,用注释行(comment lines)分组,如下

  (point)
                                          ; whatever comment you like, but the ';' must be without any prefix.
  this-command
                                          ;
  undefined
                                          ;
  

  再使用 C-c C-u 根据 *edebug* 缓冲区的内容建立新的运算列表(evaluation list),结果如下

  (point)
  264
                                          ;------------------------------------------------------------------------------------------------------
  this-command
  eval-last-sexp
                                          ;------------------------------------------------------------------------------------------------------
  undefined
  "Symbol's value as variable is void: undefined"
                                          ;------------------------------------------------------------------------------------------------------
  

  使用 C-c C-u 运算的话,只有每个组的第一条表达式会执行,结果会显示在第二行,其它行会被删除.如果运算时候发生错误,那么错误信息就会作为结果.

  还可以把指针移动到组内然后使用 C-c C-d 删除分组.

  除了 C-c C-u,还有其它运行模式,看文档就好.

• Edebug 的打印 (Printing in Edebug)
  

  如果尝试在 Edebug 中打印一个包含循环列表结构的值,那么可能会发生错误.

  克服(cope with)循环结构的一个方法就是把 print-length 或者 print-level 来分断显示. Edebug 已经帮你做好了.

  它把这两个变量分别绑定到 edebug-print-length 和 edebug-print-level,默认值都是50.

  也可以通过设置 print-circle 为 non-nil 来打印那种有着共享元素的循环结构体.

  比如

  (setq a '(x y))
  (setcar a a)
  ;; 显示为 #1=(#1# y), #1= 表示用1标记结构,#1#表示引用前一个被标记的结构.这个标记可以用在任何列表或者向量的共享元素上.
  

  相应的 Edebug 有 edebug-print-circle,会把这个变量的值绑定给 print-circle.

• 运行步骤缓冲区 (Trace Buffer)
  

  Edebug 可以把执行步骤记录在叫做 *edebug-trace* 的缓冲区中,一个函数调用和返回的日志,显示函数的名字和它们的参数和值.只要把 edebug-trace 设置为 non-nil 就可以启用该功能.

  比如上面 fac 的记录会是这样,

  { fac args: (3)
  :{ fac args: (2)
  ::{ fac args: (1)
  :::{ fac args: (0)
  :::} fac result: 1
  ::} fac result: 1
  :} fac result: 2
  } fac result: 6
  

  { 和 } 分别表示函数的入口和出口, : 表示递归深度,同一深度的 { 对应同样深度的 }.可以通过重新定义 edebug-print-trace-before 和 edebug-print-trace-after 函数来自定义记录函数入口和出口显示的条目.

  edebug-tracing 和 edebug-trace 函数在 *edebug* 中插入行,不管是否启用 Edebug.插入行也会自动滚动窗口来显示最新行.

• 覆盖测试 (Coverage Testing)
  

  Edebug 还提供不完全的覆盖参数和执行频次(execution frequency)的显示.

  覆盖参数的原理就是比较每个表达式的当前结果和上一次结果,如果返回的两个结果不一样,这个表达式被覆盖了.

  覆盖参数就是需要在大量的各种不同条件下执行程序,并且观察程序是否符合预期, Edebug 会在足够的尝试后告诉开发人员是否每个 form 返回两个不同结果.

  覆盖测试会让执行变慢, edebug-test-coverage 为 non-nil 的时候测试所有被调试的表达式.

  不管是否启用了覆盖测试或者是否 Go-nonstop 执行模式, instrumented function 的所有执行都会伴随频次计数(frequency counting)的执行.

  "C-x X =" (edebug-display-freq-count) 可以显示一个定义的覆盖信息和频次计数. 单纯 = (edebug-temp-display-freq-count) 会临时显示同样的信息,知道输入了另外一个按键.

  还是用那个老例子说明,当然还有先 instrument fac.

  (setq edebug-test-coverage t)
  
  ;; 1. instrument
  ;; 3. move cursor on definition and execute edebug-display-freq-count command
  (defun fac (n)
    (if (< 0 n)
        (* n (fac (1- n)))
      (return-res 1)))
  
  (defun return-res (n)
    (+ n 0))
  
  ;; 2. then execute, can use Rapid Trace mode for a quick travel
  (fac 5)
  

  edebug-display-freq-count 的用法: 先调试运行一遍(否则全部数据为0),然后把指针移动到 instrumentd 定义中,然后执行该命令显示覆盖信息和执行频次.

  结果如下,

  (setq edebug-test-coverage t)
  
  ;; 1. instrument
  ;; 3. move cursor on definition and execute edebug-display-freq-count command
  (defun fac (n)
    (if (< 0 n)
                                          ;#6
        (* n (fac (1- n)))
                                          ;#    5
      (return-res 1)))
                                          ;#  1            = 6
  
  (defun return-res (n)
    (+ n 0))
  
  (fac 5)
  

  执行频次会出现在表达式前面的 ( ,后面的 ) 或者是变量最后一个字母的底下.为了简化显示,如果表达式的频次计数等于同一行中前一个表达式的频次,那么这个频次就不显示.

  跟在频次计数后面的 "=" 号表示表达式每次执行结果都是一样,也就是该表达式没有被覆盖.

  再以文档上的例子来做说明,

  (defun fac (n)
    ;; (edebug) 只是返回了一次,不算覆盖.
    ;; (if (= n 0) ... 执行了6次,每次结果都是 =nil=.
    ;; = 和频次计数是没有关系的,切记.
    (if (= n 0) (edebug))
                                          ;#6           1      = =6
    ;; (< 0 n) 和 (if (< 0 n) ... 的执行频次都是一样,所以 (< 0 n) 没有显示频次
    ;; (< 0 n) 每次的结果都为 t,
    (if (< 0 n)
                                          ;#6
        ;; (* n (fac ...  以及它的子表达式的执行频次都是一样的(并且都在同一行),所以简化显示只显示了第一个表达式的执行频次.
        (* n (fac (1- n)))
                                          ;#    5
      1))
                                          ;#   6
  
  (fac 5)
  

  还可以在 Edebug 调试中的时候使用 = 命令临时显示覆盖信息和频次计数.

• 外部上下文 (The Outside Context)
  

  对于调试中的程序来说, Edebug 尝试变得透明,然而没完全成功.也尝试过在我们运行e命令或者使用运算列表缓冲区的时候通过临时恢复外部上下文来变得透明.

  这个章节主要介绍 Edebug 储存什么上下文并且为什么完全透明.

  • 检查是否停止 (Checking Whether to Stop)
    

    当进入 Edebug 的时候,它在决定是否产生执行信息(trace information)或者停止程序之前就需要储存和恢复一定的数据.

    • 增加 max-lisp-eval-depth 和 max-specpdl-size 都可以减少 Edebug 对栈的影响.不过这样很容易用完栈的空间.
    • 键盘宏的执行状态回被保存和恢复.当 Edebug 激活的时候, executing-kbd-macro 会设置为 nil, 除非 edebug-continue-kbd-macro 为 non-nil.
  • Edebug显示更新 (Edebug Display Update)
    

    当 Edebug 需要显示一些信息的时候,它会储存 Edebug 外部的当前窗口配置.当退出 Edebug 的时候它就会恢复之前的窗口配置.

    只有在 Edebug 暂停的时候 Emacs 才会重新显示(redisplay).通常,当继续执行的时候,程序会在断点处或者单步执行(stepping)后重新进入(re-enter) Edebug,中间没有任何停顿或者输入读取.

    在这写例子中, Emacs 没有任何机会重新显示外部配置.因此,你所看见的就是和最后一次激活 Edebug 时的同一个窗口配置,没有任何中断(interruption).

    用于显示信息的 Edebug 入口也会储存和恢复以下数据(尽管它们中的一些会因为 error and quit signal 的发生而有意不储存).

    • 当前的缓冲区,点的位置(point positions),marks和已经被储存的和恢复的数据.

    • 如果 edebug-save-windows 是 non-nil,那么外部窗口配置就会被储存和恢复.不会在 error 或者 quit 的时候恢复,不过即使 save-excursion 激活时候出现了 error 或者 quit,外部被选中的窗口还是会被重新选择.

      如果 edebug-save-windows 是一个列表,只有被列出的窗口会被储存和恢复.窗口开始以源代码缓冲区的水平滚动位置是不会储存的.然而,它们仍然会被保留并且显示在 Edebug 中.

    • 如果 edebug-save-displayed-buffer-points 为 non-nil,那么每个显示的缓冲区的点都会被保留和恢复.
    • overlay-arrow-position 和 overlay-arrow-string 会被储存和恢复,因此可以安全地从在同一个缓冲区中任何地方的递归编辑(recursive edit)唤醒 Edebug.
    • cursor-in-echo-area 局部绑定 nil,这样指针(cursor)会显示到窗口上.
  • Edebug Recursive Edit
    

    当进入 Edebug 并且读取命令时,会储存和之后恢复以下额外的数据.

    • 当前的匹配数据(Match Data)

    • last-command, this-command, last-command-event, last-input-event, last-event-frame, last-nonmenu-event and trace-mouse. Edebug 的命令不会在 Edebug 之外影响它们.

      Edebug 的执行命令可以改变 this-command-keys 返回 key sequence,并且没有办法从 Lisp 中重置.不能储存和恢复 unread-command-events 的值.

    • command-history 记录着 Edebug 中执行的命令,在北少数情况下这个可以修改执行(execution).
    • Edebug 中的递归深度比外部的递归深度要深,当时对于自动更新的运算列表窗口来说是错的.
    • standard-output 和 standard-input 会被 recursive-edit 命令绑定为 nil,不过 Edebug 会在运算中临时恢复它们.
    • 键盘宏的定义的状态会被保存和恢复.当激活 Edebug 时, defining-kbd-macro 会绑定到 edebug-continue-kbd-macro.
• Edebug and Macros
  
  • Instrumenting Macro Calls
    

    当 Edebug instrument 一个调用 Lisp 宏的表达式,它需要额外的宏信息来保证正确工作.

    那是因为没有一个先验 (a-priori)的方法来判断会运算宏调用的哪些子表达式(宏体可能会发生运算,或者拓展时候发生运算,又或者之后任何时刻).

    因此必须为每一个 Edebug 会遇到的宏定义 Edebug specification 来解释宏的调用格式.做法是给宏定义添加一个 debug 声明.

    Edebug specification 告诉 Edebug 宏的哪些部分需要运算.关于如何为宏定义 Edebug specification,看这里 M-: (info "(elisp) Defining Macros").

    当 instrument 代码的时候要保证 Edebug 知道 specification.如果 instrument 一个文件中的函数,并且这个函数引用了使用 eval-when-compile 导入另外一个文件的宏定义,那么就需要 load 一遍那个文件.

    除了上面的方法外,还可以使用 def-edebug-spec 为宏定义 Edebug specification.添加 debug 更受欢迎以及更方便.不过 def-edebug-spec 可以为 C 实现的 special forms 定义 Edebug specifications.

    如果一个宏没有 Edebug specification, edebug-eval-macro-args 就会参与进来,如果该变量为 nil (默认),运算的时候不会为任何一个参数 instrument;否则全员 instrumented.

  • Specification List
    

    自己看文档

  • Backtracking
    

    自己看文档

  • Specification Examples
    

    自己看文档

• Edebug Options
  

  大部份上面都提过,自己看文档

语法错误 (Syntax Errors)

• 多余的开括号 (Excess Open)
  

  多余开括号的错误提示是 End of file during parsing.

  1. 移动指针到发生错误的文件的最后执行 C-u C-M-u,以此找到错误的函数.
  2. 研究错误的函数,可以根据现有的缩进来判断.
  3. 保证函数的定义有足够的闭括号(一般都是先移动到函数的结尾插入一个闭括号,不要使用 C-M-e 移动,括号不平衡时会报错),否则 C-M-q 会报错或者重新缩进到文件最后.
  4. 移动到函数定义的开始处使用 C-M-q 来重新缩进并且过程哪部分发生右动,通常发生右偏移的起点的前一个点的附近就是少了闭括号或者多了开括号的地方(当然这不一定是对的).一定要细读代码.
  5. 一旦找到了就用 C-_ 撤销(undo) C-M-q,恢复到旧的缩进.
  6. 再次移动到函数定义的起点执行 C-M-q 来检查缩进是否正常,如果缩进没有发生改变就证明括号匹配了.
• 多余的闭括号 (Excess Close)
  

  多余闭括号的错误提示是 Invalid read syntax: ")".

  1. 移动指针到发生错误的文件的起点执行 C-u -1 C-M-u 查找第一个括号不平衡的函数.
  2. 在函数定义的起点使用 C-M-f 来匹配闭括号,执行让指针移动到定义应该结束的地方.很有可能就找到多余的闭括号.
  3. 如果上面还没有找到问题,那么就在函数的定义起点执行 C-M-q 进行缩进并且观察哪部分移动,通常发生左偏移的起点的前面一个点的附近就是多了闭括号或者少了开括号的地方(当然这不一定是对的).一定要细读代码.
  4. 一旦找到了就用 C-_ 撤销 C-M-q,恢复到旧缩进.
  5. 再次移动到函数定义的起点执行 C-M-q 来检查缩进是否正常,如果缩进没有发生改变就证明括号匹配了.

覆盖参数 (Test Coverage)

性能测试 (Profiling)

ERT: Emacs Lisp Regression Testing

• 简介 (Introduction)
  

  ERT 允许组合函数,宏,变量以及其它 Lisp 的东西(construct)来定义测试(tests).测试只不过是调用其它的代码并且检查它们是否与期望的行为一样的 Lisp 代码.

  ERT 会跟踪定义的测试和提供一些运行测试的命令,用于检测定义是否通过测试.

  比如 pp.el 的文档中有这么一些测试用例,

  ;; (pp-to-string '(quote quote))          ; expected: "'quote"
  ;; (pp-to-string '((quote a) (quote b)))  ; expected: "('a 'b)\n"
  ;; (pp-to-string '('a 'b))                ; same as above
  

  用 ERT 写对应上面测试就是这样,

  (ert-deftest pp-test-quote ()
    "Tests the rendering of `quote' symbols in `pp-to-string'."
    (should (equal (pp-to-string '(quote quote)) "'quote"))
    (should (equal (pp-to-string '((quote a) (quote b))) "('a 'b)\n"))
    (should (equal (pp-to-string '('a 'b)) "('a 'b)\n")))
  

  ert-deftest 和 defun 的用法比较像,定义一个名字叫 pp-test-quote 单元测试,加载后可以使用 M-x ert <RET> t <RET> 来运行测试.

  如果三个调用结果全员 non-nil 的话,测试就通过.上面的 should 宏就是 ert 版本的断言语句(assertion).

  每个测试应该有一个用来描述测试功能的名字,比如上面的 pp-test-quote 就是测试 quote,测试的名字不会和函数和变量放在同一个命名空间,所以可以随意选择(还是要符合 Emacs Lisp 的规范,加上前缀表明属于哪一个包).

  当测试不通过, ERT 就会显示测试的名字,还有测试的时候可以根据名字选择测试.

  第一行的 () 目前没有任何意义,以后可能会用它来做拓展,同时也是为了接近 defun 的写法.

  文档 (docstring) 用来描述所测试的功能点(feature).在交互测试中,如果测试失败,文档的第一行会被显示出来,当然文档是可选的.

  测试体,也就是里面那三个表达式,可以是任何 Lisp 代码,可能的话可以有副作用,如果有,不论测试是否通过,应该完成后进行清理,还原成测试之前的状态.

• 如何运行测试 (How to Run Tests)
  

  有两种运行方式,第一种是在启动 Emacs 后交互运行,也就是上面章节提到的方法;第二种就是在命令行中运行,也就是 batch mode.

  前者比较方便,后者可以与用户的自定义独立开;并且允许从 makefiles 中读取测试并且运行,能够根据不同版本的 Emacs 编写测试.

  • 交互运行测试 (Running Tests Interactively)
    

    使用 M-x ert <RET> t <RET> 来运行所有已经加载了的测试.其中 t (也可以是字符串)是测试选择器(test selectors),还有别的选择器可以选.

    假设现有测试如下,

    (ert-deftest pp-test-quote ()
      "Tests the rendering of `quote' symbols in `pp-to-string'."
      (should (equal (pp-to-string '(quote quote)) "'quote"))
      (should (equal (pp-to-string '((quote a) (quote b))) "('a 'b)\n"))
      (should (equal (pp-to-string '('a 'b)) "('a 'b)\n")))
    
    (ert-deftest addition-test ()
      "Addition"
      (should (equal (+ 1 2) 4)))
    

    其中 addition-test 是注定测试不通过的,

    Selector: t
    Passed:  1
    Failed:  1 (1 unexpected)
    Skipped: 0
    Total:   2/2
    
    Started at:   2018-11-01 00:00:17+0800
    Finished.
    Finished at:  2018-11-01 00:00:17+0800
    
    F.
    
    F addition-test
        Addition
        (ert-test-failed
         ((should
           (equal
            (+ 1 2)
            4))
          :form
          (equal 3 4)
          :value nil :explanation
          (different-atoms
           (3 "#x3" "?")
           (4 "#x4" "?"))))
    

    上面运行了两个测试,其中 addition-test 失败了,另外一个测试通过. F 和 . 分别表示一个失败的测试和一个通过的测试.

    上面的 :form 指的是 (equal (+ 1 2) 4) 化简(reduced to)的结果,为 (equal 3 4), :value 是 ( 3 4)= 的结果.

    和上面显示的一样,失败的测试会显示出细节,其中 :explanation 叫做解释 (Explanation). M-: (info "(ert) Understanding Explanations") 有关于如何理解解释.

    在测试结果的缓冲区中,可以做以下命令,

    • TAB 和 S-TAB 在按钮之间循环,函数和宏就是按钮.
    • RET 在按钮处跳转到按钮的定义.
    • r 重新运行指针附近的测试.
    • d 使用调试器重新运行.
    • . 跳转到点附近函数或者宏的定义,和 RET 差不多.
    • b 显示失败测试的 backtrace.
    • l 显示测试中的 should forms.
    • m 假如测试中使用了 message 函数产生信息,可以使用该命令进行显示.
    • L 失败测试的显示的表达式会根据 print-length 和 print-level 进行简短化.该命令可以增加显示限制.
  • 以 Batch Mode 运行测试 (Running Tests in Batch Mode)
    

    可以从命令行或者脚本,又或者是 makefiles 自动运行测试.有两个函数可以做这件事情,分别是 ert-run-tests-batch 和 ert-run-tests-batch-and-exit.

    在命令行下面可以这么用:

    emacs -batch -l ert -l /path/to/tests.el -f ert-run-tests-batch-and-exit
    

    如果测试全员通过就返回 0 状态码,否则就是非 0 状态码.

    还可以先把运行结果重定向到别的文件,比如 output.log,然后使用 ert-summarize-tests-batch-and-exit 产生总结信息,

    emacs -batch -l ert -l tests.el -f ert-run-tests-batch-and-exit >& output.log
    emacs -batch -l ert -f ert-summarize-tests-batch-and-exit output.log
    

    如果 Emacs 没有和 ERT 一起分发,那么需要 -L /path/to/ert 来先加载 ert 库,可能还需要用 -L /path/to/tests.el 来确保测试文件被加载.

  • 测试选择器 (Test Selectors)
    

    运行 ert 的时候需要选择测试选择器,也就是运行符合条件的测试.

    • nil,不选择任何测试.
    • t,选择所有测试.
    • :new,选择所有还没被运行过测试.
    • :failed 和 :passed,分别选择最近的测试结果为 failed 和 passed 的测试.
    • :expected 和 :unexpected,分别选择最近测试结果为 expected 和 unexpected 的测试.
    • 正则表达式字符串,匹配测试名字.
    • 测试,也就是 ert-test 数据类型.
    • symbol ,根据测试名字的 symbol 进行选择.
    • (member TESTS...),根据列表里面的测试进行选择.
    • (eql TEST),根据测试名字的 symbol 选择选择.
    • (and SELECTORS... ),选择符合所有 SELECTORS 的测试.
    • (or SELECTORS... ),选择符合所有 SELECTORS 其中之一的测试.
    • (not SELECTORS... ),选择不符合所有 SELECTORS 的测试.
    • (tag TAG),选择所有拥有 TAG 的测试. Tags 可以在定义测试的时候定义,是可选的.
    • (satisfies PREDICATE), 选择所有满足 PREDICATE 的测试, PREDICATE 是一个接受测试做为参数并且返回布尔值的函数,如果结果为 non-nil 就选择该测试.
• 如何编写测试 (How to Write Tests)
  

  在缓冲区通过 ert-deftest 定义测试,再用 eval-defun 或者 compile-defun 运行测试.

  或者保存到文件中并且加载,还可以先编译.加载后可以像 find-function 查找函数那样查找测试定义.

  • should 宏 (The should Macro)
    

    和断言语句差不多,就是多了参数分析和记录 ERT 会显示的信息.

    上面稍微提到过 should 的用法,就不再说了.除了 should 还有 should-not, should-error 两个宏.

    分别用来检查判断是否返回 nil 和是否引发对应的异常.下面分别是关于减法和除法的测试的例子,都是可以通过的.

    (ert-deftest subtraction-test ()
      (should-not (equal (+ 1 2) 4)))
    
    (ert-deftest divide-by-zero ()
      (should-error (/ 1 0)
                    :type 'arith-error))
    

    其中 should-error 的 :type 参数是可选的,如果不写就意味着接受所有类型的错误.

    should-error 可以返回错误的描述,用来做额外的检查.错误描述的形式为 (ERROR-SYMBOL . DATA).

  • 预期的错误 (Expected Failures)
    

    有些 bugs 难以修复或者是不太重要的,这些 bugs 会被留下来,称之为已知 bugs (known bugs).

    如果有测试用例(test case)触发了 bugs 发生报错, ERT 就在你每次运行测试的时候进行警告.对于已知 bugs 则不会.

    用文档上面例子,如下

    (ert-deftest future-bug ()
      "Test `time-forward' with negative arguments.
         Since this functionality isn't implemented, the test is known to fail."
      :expected-result :failed
      (time-forward -1))
    

    测试上面的例子的时候会显示 f 表示 future-bug 是一个已知 bug,仍然是一个失败的测试,不过不会显示它的错误细节.

    如果没有修复某个 bug 的意愿,可以把它的测试删除,把这个 bug 做为一个 accepted feature,这也是标记已 bug 的一种手段.

    对于意外通过(pass unexpectedly) 的测试和意外错误(unexpected failures)来说, 它们的 ERT 警告都是一样.这样的话就算无意修复了 bug,也会知道要移除 :expected-result 从句来关闭相应的错误提示.

    :expected-result 是在加载测试之后运算它的参数的,所以可以在做判断是需要标记为已知 bug.

  • 测试和环境 (Tests and Their Environment)
    

    一些测试需要先决条件(preconditions)才可以运行.比如需要的 Emacs feature 需要编译才有,参数函数需要一个额外的二进制包并且参数机器上没有这包,等等.

    这种情况下可以利用 skip-unless 宏根据条件来跳过测试.

    (ert-deftest test-dbus ()
      "A test that checks D-BUS functionality."
      (skip-unless (featurep 'dbusbind))
      ;; do the test)
    

    测试结果不应该取决于当前的环境状态,并且每个测试应该保持结束时的环境和开始测试时的环境一样,特别是不能取决于 =Emacs 的自定义变量和钩子.

    如果必须要改变 Emacs 的状态或者外部状态(比如文件),那么应该在测试结束之前撤销这些更改,不管是否通过.

    这么做的目的是防止因为环境变动导致测试失效,或者导致在特定条件下(circumstances)发生错误并且难以重现(reproduce).

    当然不是说不能有副作用(side effect),最好使用 let 绑定,这样副作用的范围就只能在测试阶段中了;也可以为每个测试设置不同的配置.

    正如上面说的,在测试之后撤销对环境的更改,可以这么做,

    • 对缓冲区(buffer)或者窗口配置(window confiugration)产生副作用,测试的时候应该用 with-temp-buffer 临时创建一个缓冲区,用 save-window-excursion.
    • 对于其它方面的可以使用 unwind-protect 保证测试之后清理环境.
    • 对于 *Message* 缓冲区, message 或者类似的函数会打乱该缓冲区的储存,这个也需要恢复到原来状态.

    总的来说就是避免使用 find-file 这种可以自定义的命令(当然除了你是真的想测试它),因为这种命令取决于很多其它自定义变量,也就是上面提到的环境.

    可以使用 with-temp-buffer, insert 或者 insert-file-contents-literally 并且在通过直接运行函数来激活想要的 mode (要先设定对应 mode 的钩子变量为 nil) 来避免 file-file 的问题.

  • 编写测试的技巧 (Useful Techniques)
    

    对于没有副作用和环境依赖的函数,基本就是 (should (eql EXPECTED ACTUAL)) 可以完事,当然也可以 (should (eql ACTUAL EXPECTED)),不过前者更受欢迎.

    对于复杂的测试,比如文档的例子,

    (ert-deftest ert-test-record-backtrace ()
      (let ((test (make-ert-test :body (lambda () (ert-fail "foo")))))
        (let ((result (ert-run-test test)))
          (should (ert-test-failed-p result))
          (with-temp-buffer
            (ert--print-backtrace (ert-test-failed-backtrace result))
            (goto-char (point-min))
            (end-of-line)
            (let ((first-line (buffer-substring-no-properties
                               (point-min) (point))))
              (should (equal first-line
                             "  signal(ert-test-failed (\"foo\"))")))))))
    

    先介绍一下这个例子的几个 forms,

    1. ert-fail 引发测试错误.
    2. make-ert-test 接受一个函数,返回一个匿名测试.
    3. ert-run-test 接受一个测试并且运行它,返回测试结果.
    4. ert-test-failed-p 判断测试结果是否失败.
    5. ert--print-backtrace 接受测试结果,显示失败测试的结果 backtrace.

    这个例子就是通过检查 backtrace 的第一行来测试 ert backtrace 的记录功能,只检查第一行是因为是 backtrace 剩下部分都是依赖于 ERT 的内部.

    通过检查第一行就可以检查到 backtrace 是否正确捕捉到 signal 的结果,而 signal 的结果就是 ert-fail 的结果.

    这个例子告诉我们,先在脑海中构建出测试结构,再根据测试结构编写代码,这样再为该代码写测试(tests)就会变得很容易.

    假如我们可以重写,这里还有几个可以提一下,

    • 如果 ert-run-test 只是接受 symbol 来选择测试的话,可以使用 make-symbol 来生成临时用的 symbol 来避免对 Emacs 造成任何副作用.
    • 还有 ert--print-backtrace 会把 backtrace 打印到另外一个有固定名字的缓冲区中,这样撤销副作用会比较困难.如果可以选择缓冲区名字就可以与环境或测试独立开,不用担心副作用问题.

    以后会在 Emacs 中遇到很多没有根据脑海中测试结构写出来的代码,有时候可以重构代码来提供一个方便测试的接口,而且还有一个好处就是,通常这种接口也更加容易使用.

    这一章节的目的就是 讲如何写出可测试代码 ,网上有不少好的文章,这篇写得十分好.

• 如何调试测试 (How to Debug Tests)
  
  • 理解解释 (Understanding Explanations)
    

    在上面交互运行测试中就提到过 :explanation,实际上 ERT 只会给已经注册了 explanation 函数的谓词(predicates)提供 explanations.

    比如上面写到的 addition-test 中的 equal 就是这一类谓词,如果把 equal 换成 "=" 号,那么结果就是这样了,

    F addition-test
        Addition
        (ert-test-failed
         ((should
           (equal
            (+ 1 2)
            4))
          :form
          (equal 3 4)
          :value nil))
    

    里面的 different-atoms 是所谓的解释,当然还有很多其它类型的解释.

    还有就是可以自定义 explanation 函数.

  • 交互式调试 (Interactive Debugging)
    

    其中 r, ., l, b, m 和 d 命令都在交互运行测试中有提过.这里再补充两个,

    • D 命令,该命令可以选择测试进行删除;
    • 通过 C-u C-M-x instrument 测试的定义,然后回到 ERT 缓冲区 通过 r 或者 d 调试运行(这里使用的调试器是 Debugger).
• 拓展 ERT (Extending ERT)
  
  • 定义 Explanation 函数 (Defining Explanation Functions)
    

    Explanation 就是一个接受和谓语一样多参数并且返回一个 explanation 的函数.返回的结果应该解释为什么会返回这个结果,

    可以是任何结果,不过一定要可以被详细打印的结果.对于不需要解释的输入则返回 nil.

    如何定义呢? 文档上大概就是,先找一个用来表示谓词的 symbol,然后为它定义一个函数,最后把该函数设置为 symbol 的属性.

    反过来想一下,可以获取 equal 的 ert-explainer 属性观察一下,

    (get 'equal 'ert-explainer) ; => ert--explain-equal
    

    参考 equal 的代码如下,

    (defun ert--explain-equal (a b)
      "Explainer function for `equal'."
      ;; Do a quick comparison in C to avoid running our expensive
      ;; comparison when possible.
      (if (equal a b)
          nil
        (ert--explain-equal-rec a b)))
    (put 'equal 'ert-explainer 'ert--explain-equal)
    

  • ERT 的底层代码 (Low-Level Functions for Working with Tests)
    

    ert-run-tests-interactively 和 ert-run-tests-batch 都是基于在 ert.el 中标记为 “Facilities for running a whole set of tests” 部分的 lower-level 代码实现的.

    如果想要使用 ERT 的代码实现一些功能,应该看一下它的 lower level 代码. ert-- 开头是指 ERT 内部使用, ert- 开头是指可以被其它代码使用.目前没有完善的 API.

• 其它测试概念 (Other Testing Concepts)
  
  • Mocks and Stubs
    

    可以先了解一下什么是 mock/stub (叫法不一样而已),最后就是 ERT 官方没有支持 mock/stub,不过 el-mock 提供了,还可以和 ERT 混合使用(不能混用才奇怪).

  • Fixtures and Test Suites
    

    Fixtures 主要用来为测试设置和清理测试环境的,包含 set-up 和 tear-down 两类函数.

    Test suites 主要把相关测试分成一组,方便运行的时候可以一起运行.

    然而 ERT 都没有这两个功能(其实也没有必要, Lisp 的强大可以轻松地解决这两个问题).

    对于 fixtures,可以利用 unwind-protect 宏作为 subroutine 来定义函数或者宏,使用这个定义来实现 fixture,

    文档上有函数版本的伪代码,

    (defun my-fixture (body)
      (unwind-protect
          (progn [set up]
                 (funcall body))
        [tear down]))
    
    (ert-deftest my-test ()
      (my-fixture
       (lambda ()
         [test code])))
    

    宏版本的就自己研究了,都差不多的.

    对于 test suites,经常用来为特定模块运行测试或者根据测试的时间长度来少运行慢的测试,定义测试的时候所有相关模块的所有测试使用相同前缀,或者使用 :tag,然后通过正则测试选择器或者 tag 测试选择器运行所有相关测试.

读取和打印的简介 (Streams Intro)

输入流 (Input Streams)

输入函数 (Input Functions)

输出流 (Output Streams)

输出函数 (Output Functions)

(setq foo (list nil)) ;; => (nil)
(setcar foo foo) ;; => (#0)

影响输出的变量 (Output Variables)

入门Minibuffers (Intro to Minibuffers)

从Minibuffer中读取文本 (Text from MInibuffer)

从Minibuffer中读取对象 (Object from Minibuffer)

Minibuffer历史 (Minibuffer History)

初始输入 (Initial Input)

补全 (Completion)

• 基础补全 (Basic Completion)
  

  这章节的 API 都是和 minibuffer 本身无关的,因为这样,它们能够用在很多其它的地方上.

• Minibuffer补全 (Minibuffer Completion)
  

  用于补全 minibuffer 的基本接口.

• 补全命令 (Completion Commands)
  

  描述用于补全 minibuffer 的按键映射(keymap),命令以及用户选项.

• 高级补全 (High-Level Completion)
  

  针对特定种类(缓冲区/ symbol / 命令 / 颜色,等等)名字的高级补全函数.

• 读取文件名字 (Reading File Names)
  

  描述用于补全文件名字,目录名字还有 shell 命令名字的高级函数.

• 补全相关变量 (Completion Variables)
  

  补全相关的用户选项,修改默认的补全行为.

• 编程补全 (Programmed Completion)
  

  有时候不可能或者不方便提前创建一个包含匹配值的 alist 或者 obarray,这种情况下你可以提供自己的函数来计算指定 string 的补全的可能值.

  这叫做编程补全,比如 Emacs 在补全文件名字的时候就使用了编程补全.这章节就是描述相关的接口.

• 在缓冲区中补全 (Completion in Buffers)
  

  除了在 minibuffer 中补全, Emacs 还允许在缓冲区上进行补全.

  钩子变量 completion-at-point-functions 是一个函数列表,里面的函数都是用于计算用于补全某个点上文本的补全表(completion table).

  Major mode 可以用这个变量来提供补全表.当运行 completion-at-point 的时候,列表上的函数就会被依次调用,不需要传入参数.

  每个函数都应该返回 nil,除非它能够负责该点上的文本的补全,否则就应该返回如下形式的列表 (START END COLLECTION . PROPS).

  START 和 END 界定了被补全的文本, COLLECTION 就是补全表, PROPS 就是一个记录了额外信息的 plist.

  文章余下部分就是讲解编写这些函数需要注意的地方.

Yes-or-No查询 (Yes-or-No Queries)

多重选择查询 (Multiple Queries)

读取密码 (Reading a Password)

在Minibuffer中使用的命令 (Minibuffer Commands)

Minibuffer窗口 (Minibuffer Windows)

Minibuffer内容 (Minibuffer Contents)

递归Minibuffer (Recursive Mini)

Minibuffer杂项 (Minibuffer Misc)

定义命令 (Defining Commands)

• 使用 interactive (Using Interactive)
  

  (interactive arg-descriptor),调用命令的时候会根据 arg-descriptor 读取命令的参数, arg-descriptor 有三种可能:

  • nil 或者放着不管,就是指命令不需要任何参数.

  • string,它的内容是一个由 newlines 分割做为分割符的元素序列,每一个元素代表一个参数,每个元素是一个 Interactive Code 后面跟着一个可选的提示字符串(prompt). Interactive Code 可以在这里看 M-: (info "(elisp)Interactive Codes").

    提示字符串可以使用 % 来获取上一个参数的值.

    如果 arg-descriptor 以 * 字符开头,并且如果在 read-only 缓冲区 调用该命令就会引发错误;

    如果以 @ 字符开头,并且如果按键序列包含任何鼠标事件,那么与第一个事件关联的窗口就会在命令执行前被选中;

    如果以 ^ 字符开头,并且如果命令在 shift-translation 下唤醒,那么命令在执行前就会临时设定 mark 和激活区域(region),或者拓展一个早已激活的区域,

    如果命令在没有 shift-translation 的情况下激活,那么区域尖或被临时激活,然后在运行前取消激活(deactivate).

    可以三个字符一起使用,并且顺序无关要紧.

    比如,

    (defun pesudo-rename (oldname newname)
      (interactive "sOldname to rename: \nsRename %s to: ")
      (message (format "oldname: %s to newname: %s" oldname newname)))
    

  • 一个非 string 的 Lisp 表达式,并且它的运算结果应该是一个参数列表(list of arguments). 比如,

    (defun pesudo-rename (oldname newname)
      (interactive (let* ((name1 (read-string "name1: "))
                          (name2 (read-string (format "reaname %s to name2: " name1))))
                     (list name1 name2)))
      (message (format "Oldname: %s to newname: %s" oldname newname)))
    

    注意的是,参数值不应该包含任何不能被打印然后读取的数据类型,一些功能会保存 command-history 到一个文档里面,可能会在后续会话中被读取, 如果一个命令的参数包含这些数据类型(会使用 #<...> 语法打印),那么这些功能就不会正常工作.

  (interactive-form function) 可以获取函数的 interactive form.

• 通用命令 (Generic Commands)
  

  有些交互函数的实现可以让用户选择实现,这些就是通用命令.

交互式调用 (Interactive Call)

区分交互式调用 (Distinguish Interactive)

命令循环的信息 (Command Loop Info)

命令后调整指针 (Adjusting Point)

输入事件 (Input Events)

• 键盘事件 (Keyboard Events)
  

  从键盘中能够获取的输入类型有两种,普通键(ordinary keys)和功能键(function keys).一个普通键实际上就是对应一个字符;

  字符有可能被修饰过,也就是配合修饰键(meta, control, shift, hyper, super, alt)一起输入.

  输入普通键的时候会产生一个事件,该事件的值就是一个 Lisp 字符对象,也就是一个整数,这种事件叫做字符事件(character event).

  一个字符事件的值是这计算的:

  有524288(\(2^{19}\))个基础字符,从 0 开始对所有基础字符进行编码: 0 ~ 524287,基础字符的编码叫做基础码(basic code),也就是说一个基础码需要 20 位字节;

  有6种修饰键,每种都有它们各自的值;

  如果没有配合修饰键输入,那么字符事件的值就是基础码的其中一个(0 ~ 524287),比如输入 a 键所产生的事件的值就是 ?a,也就是 97.

  如果配合修饰键一起输入,那么 大部分的 字符事件的值就等于所有修饰键事件的值加上基础码:

  meta: 2**27 (the 28th bit);

  control: 2**26 (the 27th bit),但是有一些特殊情况,

  control + ASCII 这种组合对 Emacs Lisp 是有特殊意义的,它们都有自己的值,比如 Ctrl + a 就是1, Ctrl + b 是2, Ctrl + c 是3,如此类推,

  而对于 control + non-ASCII 这种组合才是 control 的值和字符的值加起来,比如 Ctrl + % 的值就是37(?\%)加上 2**26 得到 67108901;

  shift: 2**25 bit (the 26th bit), 要注意 Shift + a 得到的值不等于 ?A, Shift + letter 这种组合不代表切换字符的大小写;

  hyper: 2**24 bit (the 25th bit);

  super: 2**23 bit (the 24th bit);

  alt: 2** 22 bit (the 23th bit),不过注意的是,大部份键盘的 Alt 键都会被当作 meta 来处理的.

  总得来说,一个字符事件需要 28 位字节来储存: 0000 0000 0000 0000 0000 0000 0000.

• 功能键 (Function Keys)
  

  功能键与普通键不一样,采用 symbols 作为表示, symbols 的名字就是功能键的标签,比如 <F1> 键就是用 f1 表示.

  文档上举了几个例子,自行查阅.

• 鼠标事件 (Mouse Events)
  

  Emacs 支持点击事件(click events),拖拽事件(drag events),按钮按下(button-down events)和运动事件(motion events)4个类型的鼠标事件.

  所有类型的事件都是采用 lists 做为表示. list 的 car 结果是事件类型,也就是告诉 Emacs 使用的鼠标按钮以及 modifier keys.

  事件类型还可以区分双击以及三击,剩余的 list 元素包含位置以及时间信息.

  对于按键查找(key lookup)来说只有事件类型是重要的:同类型的两个事件是一定执行同一个命令,命令可以通过 e interactive code 来获取这些事件的全值.

  一个以鼠标事件开头的按键序列会通过当前鼠标所在的窗口的 keymaps 来读取,不是当前缓冲区,这并非暗示在某个窗口点击就会选择那个窗口和或者它的缓冲区,

  这完全是由按键序列的绑定命令来控制的.

• 点击事件 (Click Events)
  

  用户按下鼠标按钮并且在同一个地方释放它,这样会产生一个点击事件.所有鼠标事件都用同一个格式:

  (EVENT-TYPE POSITION CLICK-COUNT)

  • EVENT-TYPE

    一个表示使用了哪个鼠标按钮的 symbol.是 mouse-1, mouse-2 … 其中一个,分别从左到右表示鼠标按钮.

    还可以像功能键那样使用 A- C-, H-, M-, S- 和 s- 来分别表示 alt, control, hyper, meta, shift 和 super 键.

    该 symbol 也表示事件的事件类型,按键绑定根据它们事件类型来描述事件,因此如果有个 mouse-1 的按键绑定,那么这个绑定将会应用于所有事件类型为 mouse-1 的事件上.

  • POSITION

    一个鼠标位置列表,记录发生鼠标点击的位置.

    点击的位置分为两类:

    1. 文本区域(text area), mode line, header line, 条纹(fringe)或者边缘区域(marginal areas);
    2. 滚动条

  M-: (info "elisp(Accessing Mouse)") 有介绍如何获取鼠标事件的位置列表,这里就先不说了.

  如果在第一类位置发生点击事件,那么鼠标位置的 list 就是如下形式:

  (WINDOW POS-OR-AREA (X . Y) TIMESTAMP
          OBJECT TEXT-POS (COL . ROW)
          IMAGE (DX . DY) (WIDTH . HEIGHT))
  

  • WINDOW: 点击发生的窗口.
  • POS-OR-AREA: 如果点击位置在文本区域内,就表示被点击的字符的缓冲区位置,或者如果在文本区域之外就表示窗口位置. 是 mode-line, header-line, vertical-line, left-margin, right-margin, left-fringe 或 right-fringe 的其中之一. 如果事件的前置键(imaginary prefix keys)已经被 Emacs 绑定了的话,那么 POS-OR-AREA 就是一个包含了一个上述 symbol 的 list.
  • X, Y: 点击的相对像素坐标.
  • TIMESTAMP: 点击事件的发生时间,是一个整数,表示从系统初始时间到目前的微秒.
  • OBJECT: 如果点击的位置没有文本就返回 nil;否则就是 (STRING . STRING-POS), STRING 表示被点击的 string 以及它的所有属性, STRING-POS 就是点击的位置.
  • TEXT-POS: 如果在边缘区域或者条纹(fringe)上点击,那么这就是窗口上第一个可见字符的缓冲区位置;如果在 mode line 或者 header line 点击就是 nil;对于其他事件就是距离点击位置的最近缓冲区位置.
  • COL, ROW: 实际的列行坐标.
  • IMAGE: 点击发生的图像对象,如果没有图片就是 nil,否则就是和 find-image 返回值一样的图像对象.
  • DX, DY: 相对于 OBJECT 左上角的相对像素坐标, OBJECT 为 (0 . 0);如果 OBJECT 为 nil,那么就是相对于点击位置字符的坐上角的像素坐标.
  • WIDTH, HEIGHT: 如果 OBJECT 不为 nil 那么就是它的宽高,否则就是这些被点击字符.

  如果在第二类位置发生点击事件,那么鼠标位置的 list 就是如下形式:

  (WINDOW AREA (PORTION . WHOLE) TIMESTAMP PART)
  

  • WINDOW: 滚动条被点击中的窗口.
  • AREA: 值为 vertical-scroll-bar 的 symbol.
  • PORTION: 滚动条顶部到点击位置的像素数量,有些工具,比如 GTK+, Emacs 是不能获取这个值的,这个时候就为 0.
  • TIMESTAMP: 点击时间,同样对于 GTK+ 这些工具无法获取.
  • PART: 滚动条的点击位置,如果在滚动条滑块上就是 handle,如果在滑块以上就是 above-handle,以下就是 below-handle,如果到了滚动条的两端就分别是 up 和 down.

  • CLICK-COUNT

    记录了同一个鼠标按钮快速重复点击的次数.

• 拖拽事件 (Drag Events)
  

  拖拽事件就是用户按下鼠标并且在释放按钮前移动到别的字符的位置,它的形式是这样的:

  (EVENT-TYPE (WINDOW1 START-POSITION) (WINDOW2 END-POSITION))
  

  • EVENT-TYPE: drag- 开头的 symbol,比如 drag-mouse-2.
  • (WINDOW1 START-POSITION) 和 (WINDOW2 END-POSITION) 分别表示按下按钮时候的位置和释放按钮时候的位置,释放时候可能会在窗口的边界外,那么就是一个包含了窗口所处于的frame的 list.

  如果 read-key-sequence 接收了一个没有按键绑定的拖拽事件,那么就把它转化成在拖拽开始位置的发生的点击事件.

• 按钮按下事件 (Button-Down Events)
  

  没有办法在按钮释放以前区分点击和拖拽事件,如果要在按钮按下的时候进行处理,那么就需要处理这个事件,它的形式类似点击事件,除了 EVENT-TYPE 是一个以 down- 开头的 symbol.

  read-key-sequence 会无视没有命令绑定的 button-down 事件,所以命令循环会无视它们.一般使用 button-down 事件的原因是为了在按钮以前通过读取 motion events 来跟踪鼠标的动作(motion).

• 重复事件 (Repeat Events)
  

  在没有移动鼠标的情况下快速按下同一个按钮多于一次, Emacs 会对后续按下动作产生一种叫做 repeat 的鼠标事件.

  最常见的是双击事件(double-click),双击事件的类型包含了 double- 前缀,如果双击左键的时候按着 meta 键,那么事件类型就是 M-double-mouse-1.

  当用户双击的时候 Emacs 会对第一下生成一个普通的点击事件,然后才对第二下生成双击事件.

  如果点击了一下按钮然后再按下并且在释放前拖动鼠标,那么就会产生一个 double-drag 事件,如果 double-drag 没有绑定,那么 Emacs 就会查找普通的 drag 事件的绑定,如果 drag 也没有绑定,那么就会直接忽略.

  在 double-click 或者 double-drag 之前, Emacs 会在用户第二次按下鼠标的时候生成一个 double-down 事件,同样如果没有绑定的话就会使用普通的 button-down 的绑定,如果 button-down 也没有绑定,那么就会直接忽略.

  三次快速点击会产生三击(triple-click)事件,和双击对应,有 triple-drag 以及 triple-down 事件,三次以上也是 triple 事件,可以通过事件列表来看到实际点击次数.

• 动作事件 (Motion Events)
  

  所谓动作事件就是描述鼠标在没有任何按钮活动的情况下的动作.事件形式如下,

  (mouse-movement POSITION)
  

  其中 POSITION 是一个位置 list,表示了鼠标指针的当前位置. track-mouse form 允许动作事件在它的体内产生,之外则不行.

• 焦点事件 (Focus Events)
  

  Emacs 提供通用的方法让用户拥有选择窗口的权力,窗口的选择叫做 focus.在用户切换frame的时候就会产生 "focus" 事件.

  事件形式如下:

  (switch-frame NEW-FRAME)
  

  一些窗口管理器(window managers, WM for short)被设置成只要移动鼠标到一个窗口就足以 focus 到它身上.

  然而 Emacs 不同,需要用户通过鼠标或者键盘在frame上输入才行,只是在frame之间移动是不会产生 focus 事件的.

  Emacs 是不会在按键序列的中间生成一个 focus 事件,因为会打乱(garble)序列.

• 杂项事件 (Misc Events)
  

  一些别的系统事件,具体自己看.

• 分类事件 (Classifying Events)
  

  一些可以帮助判别事件类型的 API, event-modifiers 获取事件的 modifiers, event-basic-type 返回事件描述的按键或者鼠标按钮,移除了所有 modifiers.

  mouse-movement-p 判断对象是否一个动作事件等等.

• 访问鼠标事件 (Accessing Mouse)
  

  一些关于获取鼠标事件数据的 APIs

• 访问滚动条 (Accessing Scroll)
  

  关于滚动事件的 APIs.

• 把事件变为字符串 (Strings of Events)
  

  不建议把事件储存为字符串,之所以存在这种东西是因为历史兼容问题,新的 Lisp 程序最好不要采用这种方式,用向量(vector)来替代字符串(string),具体自行阅读文档.

读取输入 (Reading Input)

特殊事件 (Special Events)

等待结束时间或者输入 (Waiting)

中止 (Quitting)

(defun read-quoted-char (&optional prompt)
  "...DOCUMENTATION..."
  (let ((message-log-max nil) done (first t) (code 0) char)
    (while (not done)
      (let ((inhibit-quit first)
            ...)
        (and prompt (message "%s-" prompt))
        (setq char (read-event))
        (if inhibit-quit (setq quit-flag nil)))
      ...set the variable ‘code’...)
    code))

前缀命令参数 (Prefix Command Arguments)

递归编辑 (Recursive Editing)

禁用命令 (Disabling Commands)

(put 'command-to-be-executed 'disabled t)

命令历史 (Command History)

键盘宏 (Keyboard Macros)

[?\C-e return ?\C-y return]

点附近的文本 (Near Point)

检视缓冲区的内容 (Buffer Contents)

比较文本 (Comparing Text)

插入文本 (Insertion)

插入文本的命令 (Commands for Insertion)

删除文本 (Deletion)

删除文本的命令 (User-Level Deletion)

Kill Ring (The Kill Ring)

• Kill Ring 的概念 (Kill Ring Concepts)
  

  Kill ring 会记录被杀掉的文本到一个列表中,最近的记录会排在第一位,有点类似栈(stack),文档上有个例子:

  '("some text" "a different piece of text" "even older text")
  

  Kill ring 有长度限制, kill-ring-max 可以设置.在列表达到最大限制的时候,新增加一个元素会自动删除列表中最后一个的元素.

  当 kill command 和其它非 kill command 的命令交错使用的时候,每个都会 kill command 都会添加一个新的元素到 kill ring 中.

  如果多个 kill commands 连续地(in succession)使用,那么就会只产生一个元素来添加到 kill ring 中.所有后续的连续 kill commands 会把文本加载第一个 kill command 生成的文本中.

  对于 yanking,只有 kill ring 中开头的元素才会被找回.一些 yank 命令会转换 kill ring 来把别的元素放在开头.

  不过这个转换并不会改变 kill ring 本身,最近的元素还是放在第一位.

• Kill Function (Kill Functions)
  

  kill-region 就是 killing text 的 subroutine,任何调用这个函数的命令都是 kill command.

  它会把最近被杀掉的文本添加到 kill ring 的头部或者添加到最近的文本中,它会根据 last-command 来判断上一个命令是不是一个 kill command,

  再决定是否添加到上一个命令的文本中,还是添加到头部中. kill command 在保存文本之前会先调用 filter-buffer-substring 来对文本进行筛选,所以保存的文本可能会与缓冲区上的不一样.

• Yanking (Yanking)
  

  Yanking 意味插入 kill ring 中的文本,不过并非盲目的插入文本. yank 命令或者相关命令会先使用 insert-for-yank 来对插入的文本进行特殊处理.

  insert-for-yank 类似 insert,不过它会根据文本的 yank-handler 属性以及 yank-handled-properties 还有 yank-excluded-properties 变量来对插入的文本进行处理,

  然后把处理后结果插入到当前缓冲区中.

  yank-handler 的格式如: (FUNCTION [PARAM] [NOEXCLUDE] [UNDO]),第一个以外的元素可以不写

  • FUNCTION: 非 nil 的时候,会被调用来插入文本, nil 的时候是调用 insert.
  • PARAM: 如果该元素为非 nil,它就代替被插入的文本,作为 FUNCTION 的参数.
  • NOEXCLUDE: 如果该元素为非 nil,那么就禁用 yank-handled-properties 和 yank-excluded-properties 对插入文本的处理.
  • UNDO: 如果该元素为非 nil,那么它应该是一个可以被 yank-pop 调用的函数,用来撤销当前文本的插入,该函数需要两个参数:当前区域的起点和结束点. FUNCTION 可以设置 yank-undo-function 来重写 UNDO 的值.
• Yank命令 (Yank Commands)
  

  高级的 yanking 命令,自己阅读.

• 低级 Kill Ring (Low-Level Kill Ring)
  

  一些用来访问 kill ring 的低级函数和变量,方便于关注窗口系统选择的 Lisp 程序员.

• Kill Ring 的内部 (Internals of Kill Ring)
  

  kill-ring 变量以 string 列表的形式保存了 kill ring 的内容,最近的文本必定是放在列表第一位.

  kill-ring-yank-pointer 变量指向 kill ring 列表上的连接(link),连接是一个列表,它的 car 是被找回的文本,

  kill-ring-yank-pointer 可以用来确认 kill ring 的头部.移动 kill-ring-yank-pointer 到别的连接上被成为转换 kill ring (rotating the kill ring).

  当然转换是虚拟的,并不会改变 kill-ring 的值.=kill-ring= 和 kill-ring-yank-pointer 都是普通的列表,

  kill-ring-yank-pointer 和 kill ring 列表上的连接是同一个 Lisp 对象,可以通过 eq 测试.

  
  kill-ring                  ---- kill-ring-yank-pointer
    |                       |
    |                       v
    |     --- ---          --- ---      --- ---
     --> |   |   |------> |   |   |--> |   |   |--> nil
          --- ---          --- ---      --- ---
           |                |            |
           |                |            |
           |                |             -->"yet older text"
           |                |
           |                 --> "a different piece of text"
           |
            --> "some text"
  
  

撤销 (Undo)

维护撤销列表 (Maintaining Undo)

填充 (Filling)

外边距 (Margins)

适应填充 (Adaptive Fill)

自动填充 (Auto Filling)

文本排序 (Sorting)

列 (Columns)

缩进 (Indentation)

• 原函数缩进 (Primitive Indent)
  

  关于获取以及插入缩进的原函数.

• Mode特定的缩进 (Mode-Specific Indent)
  

  Major Mode 的一个重要功能是自定义 <TAB> 按键的缩进.这个章节就是描述 <TAB> 按键的机制以及如何控制它.

  在大部份的编辑模式中, <TAB> 都是绑定到 indent-for-tab-command 命令中.

大小写改变 (Case Changes)

文本属性 (Text Properties)

• 检查属性 (Examining Properties)
  

  主要是关于一些获取某个位置上的文本属性,比如 get-text-property 以及 text-properties-at,后者返回一个属性列表,前者得到某个属性的值,

  具体阅读文档.

• 改变文本属性 (Changing Properties)
  

  这里是关于用于改变缓冲区或者字符串指定范围内的文本属性的函数, set-text-properties 函数可以用来增删改指定范围内的文本的属性.

  因为文本属性被认为是缓冲区内容的一部分,所以改变文本属性会把缓冲区认为被修改过.缓冲区上的文本属性是可以撤销的(undoable).

  还有,在字符串中,位置是从0开始的,而在缓冲区中是从1开始的.

• 文本属性搜索 (Property Search)
  

  通常连续的文本字符的同一个属性会有相同的值,所以说不需要一个一个的检查字符的属性,直接处理一段有着相同属性的字符会更快.

  这章节的函数不会移动点(point),相反会返回一个位置(position)或 nil. 一个位置是处于两个字符之间的,这些函数返回的位置是处于两个不同属性的字符之间的.

• 特殊属性 (Special Properties)
  

  一些有特殊用途的属性,比如上面提到的 face 和 category.

• 格式化用的文本属性 (Format Properties)
  

  这些属性影响填充命令的行为.

• 文本属性的粘性 (Sticky Properties)
  

  当用户在缓冲区上面输入 self-inserting 字符 (可以理解为输入的字符)时候,输入的字符会拥有与输入位置前面的字符一样的属性,这称为属性的继承.

  一个 Lisp 程序可以做到有继承插入或无继承插入,取决于对插入原函数的选择,比如 insert 就是不带继承地插入文本,它会保留被插入字符串的属性,被插入的字符串的属性不会因为在别的缓冲区上改变.

  而 serf-inserting 字符因为输入的时候使用了带继承插入的原函数,所以 self-inserting 字符会继承属性.

  在插入文本的时候,哪些属性被继承,以及是从哪里继承是取决于那些 sticky 属性.在一个字符后面插入并且继承这个字符的属性,这种叫 rear-sticky,

  在文字前面插入并且继承这个字符的属性叫做 front-sticky.如果两边都对同一个属性提供不同的 sticky 值(就是在文本中间进行文本插入的操作),那么前面的一个字符的值优先.

  可以通过 front-sticky 以及 rear-nonsticky 两个属性以及 text-property-default-nonsticky 变量来控制不同文本属性的粘性.

  如果一个字符的 front-sticky 属性的值为 t,那么这个字符的所有属性都是有 front-sticky 粘性的,如果是指定特定属性,比如 (face read-only),这样就是指定 face 属性为粘性,

  在该字符前面插入会导致被插入的文本都继承这个字符的 face 属性.

  read-nonsticky 是让在字符后面插入文本不继承该字符的属性,字符的大部份属性默认都是 rear-sticky,接受的值和上面 front-sticky 描述一样.

• 惰性计算文本属性 (Lazy Properties)
  

  就是在需要这些属性的时候计算出结果.

• 定义可点击文本 (Clickable Text)
  

  设置链接的官方教程,就不总结了,自行阅读.

• 定义以及使用域 (Fields)
  

  所谓域就是缓冲区里面一段连续的字符,并且它们的属性 field 的值都是一样(用 eq 比较).

• 为什么文本属性不是区间 (Not Intervals)
  

  具体不翻译了,自己读.

语法表基础 (Syntax Basics)

语法描述符 (Syntax Descriptors)

"<DESIGNATOR-CHAR><MATCHING-CHAR><PROPERTIE-CHARS>"

语法表函数 (Syntax Table Functions)

语法属性 (Syntax Properties)

动作和语法 (Motion and Syntax)

解析表达式 (Parsing Expressions)

• 根据解析移动 (Motion via Parsing)
  

  根据解析结果移动的相关 API.

• 位置解析 (Position Parse)
  

  根据缓冲区位置来计算出语法状态,用于语法分析(syntactic analysis),比如缩进信息这种有用的信息.

• Parser的状态 (Parser State)
  

  Parser 状态是一个装着11个元素的列表,描述了语法 parser 的状态,像 syntax-ppss 这种函数就会返回一个 parser 状态作为返回值.

  Parser 状态的元素分别有以下含意:

  • 第一个元素: 括号的深度,从0开始计算,如果闭合括号 ) 比 开括号 ( 还要多,那么该元素就是一个负整数.
  • 第二个元素: 最内层的括号分组的开始字符的位置,如果没有最内层表达式就返回 nil,比如 (a b c)),解析表达式内任意一个位置就是开括号 ( 的位置.
  • 第三个元素: 上一个完全子表达式(complete subexpression)的结束处开始的字符位置,否则为 nil, 比如 (a b c),如果点在 a 的后面,那么该元素就是 a 的位置,如果点在 a 上,那么就是 nil.
  • 第四个元素: 如果位置在字符串上就返回该字符串的结尾字符,或者如果结尾的是通用分隔符,那么就返回 t.比如位置处于 "abc" 中,返回就是 34 (").
  • 第五个元素: t 表示位置处于不可嵌套的注释中,否则就是 nil.
  • 第六个元素: 如果端点(end point)跟在一个引用字符后面(我也不太清楚什么是引用字符),那么它就是 t.
  • 第七个元素: 扫瞄时候遇到的最小括号深度(难道不应该都是0吗).
  • 第八个元素: 当前位置的注释风格.
  • 第九个元素: 但位置处于字符串或者注释之中,该值就是开始的位置.
  • 第十个元素: 当前位置从里到外所有开括号的位置.
  • 第十一个元素: 如果上一个被扫瞄到的缓冲区位置是双字符结构(比如注释分隔符或者转义和字符引用符号对)的第一个字符,那么就是该位置上的 syntax code,否则为 nil.
• 底层解析 (Low-Level Parsing)
  

  使用表达式解析器(parser)的最基本方法就是指定开始位置和结束位置之间的范围进行解析: parse-partial-sexp.

• 控制解析 (Control Parsing)
  

  一些控制解析的参数.

语法表内部实现 (Syntax Table Internals)

;; in Lisp Interaction mode
(lisp-interaction-mode)
(aref (syntax-table) ?\*) ;; => (3)

;; in C mode
(c-mode)
(aref (syntax-table) ?\*) ;; => (393217)

(syntax-class '(3)) ;= > 3
(syntax-class '(393217)) ; => 1, 393217 = 1 + (ash 17) + (ash 18), syntax descriptor: ". 23"

分类 (Categories)

基础的线程函数 (Basic Thread Functions)

互斥锁 (Mutexes)

条件变量 (Condition Variables)

;; for thread which is waiting
(with-mutex mutex
  (while (not global-variable)
    (condition-wait cond-var)))

;; for thread which is notifying
(with-mutex mutex
  (setq global-variable (some-computation))
  (condition-notify cond-var))

线程列表 (The Thread List)

创建子进程 (Subprocess Creation)

;; async process
(make-process :name "list-dir" :buffer "ls-buf" :command (list "ls" "/home/saltb0rn"))

;; sync process
(call-process "ls" nil (list "ls-buf" "ls-buf") nil "/home/saltb0rn")
                                        ; 发送当前 buffer 的 (point-min) 到 (point-max) 的文本给 =ls=,可以新建一个 buffer 并且输入 /home/saltb0rn
(call-process-region (point-min) (point-max) "ls" nil "ls-buf")

;; 对于一个以上的参数的命令 cp
(make-process :name "cp-file" :buffer "cp-buf" :command (list "cp" "/home/saltb0rn/a" "/home/saltb0rn/b"))
(call-process "cp" nil (list "cp-buf" "cp-buf") nil "/home/saltb0rn/a" "/home/saltb0rn/b")
;; call-process-region 就不演示了

Shell参数 (Shell Arguments)

(concat "diff -u "
        (shell-quote-argument oldfile)
        " "
        (shell-quote-argument newfile))

创建同步进程 (Synchronous Processes)

创建异步进程 (Asynchronous Processes)

删除进程 (Deleting Processes)

进程信息 (Process Information)

给进程发送输入 (Input to Processes)

给进程发送信号 (Signals to Processes)

接收进程的输出 (Output from Processes)

• 进程关联的缓冲区 (Processes Buffers)
  

  一个进程可以有一个关联的缓冲区,是一个普通的缓冲区,有两个目的:储存进程输出和决定杀掉进程的时机.

  可以根据缓冲区来识别它所关连的进程,因为在实际情况中,一般一个进程关联一个缓冲区,大部份进程也会用缓冲区来编辑发送给进程的输入.

  默认情况下,程序输出会被插入到关联的缓冲区中,当然可以通过自定义的过滤函数来改变这一行为.输出插入的位置由 process-mark 决定,在插入文本后,

  process-mark 会更新为文本的最后一个点,正常情况下 process-mark 就是在缓冲区的结尾.

  杀掉程序关联的缓冲区也会杀掉进程本身,如果进程的 process-query-on-exit-flag 属性是 non-nil, Emacs 会先征求用户的确认.

  征求确认的这个行为是通过 process-kill-buffer-query-function 来完成的,而它又是从 kill-buffer-query-functions 中运行的.

  具体 API 就自己看了.

• 进程过滤函数 (Filter Functions)
  

  一个进程过滤函数就是一个从关联进程接收标准输出的函数.进程的所有输出都会被传入到过滤函数中,默认的过滤函只是把进程输出直接插入到关联的缓冲区中.

  默认情况下,进程的错误输出也会被传入到过滤函数中,除非在创建进程的时候分开了标准输出流和标准错误流.

  过滤函数只有在 Emacs 等待某些事情的时候被调用,因为进程的输出只会在这种情况下到达.具体上面的导读有写,就不再重复了.

  一个过滤函数一定要接收两个参数: 关联的进程和一个字符串,这个字符串表示进程的输出,这个函数可以对输出做任何事情.

  一般情况下,会在过滤函数执行期间禁止中止(quitting)的,否则在命令层面上输入 C-g 或者停止一个用户命令会发生意想不到的情况.

  如果想要允许这一行为,可以把 inhibit-quit 设置为 nil,大部份情况下正确做法应该是使用 with-local-quit 宏.

  如果在过滤函数执行的期间发生错误,错误会被自动捕捉,所以错误不会停止进程的执行,但是如果设置了 debug-on-error 为 non-nil,错误就不会被捕捉.

  这样可以方便使用 Lisp 调试器进行调试.

  很多过滤函数有时候会模仿默认过滤器的行为那样插入输出到进程关联的缓冲区中.这种过滤函数需要确保在插入前保存了当前缓冲区,

  以及选择正确的缓冲区,插入后回复原来的缓冲区,除了这些外,还应该检查缓冲区是否存活,更新 process-marker,在某下情况下还需要更新点的值.

  正确做法应该是这样:

  (defun ordinary-insertion-filter (proc string)
    (when (buffer-live-p (process-buffer proc))
      (with-current-buffer (process-buffer proc)
        (let ((moving (= (point) (process-mark proc))))
          (save-excursion
            ;; Insert the text, advancing the process marker.
            (goto-char (process-mark proc))
            (insert string)
            (set-marker (process-mark proc) (point)))
          (if moving (goto-char (process-mark proc)))))))
  

  如果想在新文本到达的时候显示进程的缓冲区,可以在 with-current-buffer 前插入 (display-buffer (process-buffer proc)).

  还有最后一个表达式的判断并非必须的,可以去掉判断强迫点在缓冲区的尾部,默认的过滤函数使用 insert-before-markers 移动所有 markers,

  包括窗口的点,因为这可能会移动不相关的 markers,所以一般最好只移动窗口的点,有或者设置插入点的类型为 t.

  当执行过滤函数的时候, Emacs 会自动保存以及恢复匹配数据(match data).

  过滤函数接收到的进程输出会有任何不同大小,比如一个程序可能一行内会两次产生相同的输出,然后一次性发送一批 (a batch) 200 个字符的文本,接下来再发送5批40个字符的文本.

  如果过滤函数在子进程的输出查找特定的文本,那么需要注意文本可能会被分开到不同的批次的输出的情况,方法就是把接收的文本插入到一个临时的缓冲区中以供搜索.

  set-process-filter 和 process-filter 分别给进程设置过滤函数和获取进程的过滤函数.

• 解码进程输出 (Decoding Output)
  

  当 Emacs 直接把输出写入多字节(multibyte)缓冲区中,它就会根据进程的输出编码系统(coding system)来解码.

  如果编码系统是 raw-text 或者是 no-conversion, Emacs 会使用 string-to-multibyte 把统一字节(unibyte)输出转换成 multibyte,并且插入处理得到后的 multibyte 文本.

  可以使用 set-process-coding-system 来指定进程使用的编码系统,否则,如果 coding-system-for-read 是 non-nil,

  那么就会使用 coding-system-for-read 指定的编码系统;或者是默认的编码系统.

  如果进程输出的文本包含空字节(null byte), Emacs 默认会使用 no-conversion 做为编码系统.

  最好不要使用哪种类似于 undecided 这种根据数据判断编码系统的编码系统,因为对于异步子进程的输出不完全可靠.

  因为 Emacs 必须分批次处理异步子进程的输出, Emacs 必须尝试检查出每个批次的正确编码系统,但是这并非百分百成功.

  所以,最好自己指定一个编码系统,比如 latin-1-unix,不要 undecided 或者 latin-1.

  在 Emacs 调用一个进程过滤函数时, Emacs 会根据进程的过滤编码系统(filter coding system)给过滤函数提供一个多字节字符串或者统一字符串的进程输出.

  Emacs 会根据进程输出的编码系统来解码输出,这个编码系统通常会产生一个多字节字符串,除了像 binary 和 raw-text 这样的编码系统.

• 接收进程输出 (Accepting Output)
  

  主要是关于 accept-process-output 的用法.

• 进程和线程 (Processes and Threads)
  

  Emacs 的线程是相对于进程后面才得到支持的,由于动态绑定有时候会和 accept-process-output 同时被使用,

  默认情况下,一个进程会被锁定到(be locked to)那个创建了该进程的线程上,进程的输出只能被该线程接收.

  一个 Lisp 程序可以指定进程被锁定到哪个线程上,或者让 Emacs 解锁一个进程,一旦被解锁,进程的输出就可以给任何线程处理.

  一个时间内只可以有一个线程等待指定进程的输出,一旦进程开始等待输出, Emacs 就临时锁定进程直到 accept-process-output 或者 sit-for 返回.

  如果线程结束,所有被锁定到该线程的进程都会被解锁.

  process-thread 返回锁定进程的线程,如果进程已经被解锁就返回 nil; set-process-thread 把进程锁定到线程上.

哨兵:检测进程状态的改变 (Sentinels)

在结束前询问 (Query Before Exit)

系统进程 (System Processes)