Emacs Lisp - ewoc使用介绍
文章目录
介绍
Ewoc 是 Emacs’s Widget for Object Collections的简写，它可以根据lisp对象的结构绘制和更新buffer的文本，就像MVC设计模式中的视图层。其中，生成的buffer的文本分为三个部分：特定的头部文本，lisp对象代表的数据元素的文本，特定的底部文本。一个ewoc对象的信息包含在以下内容中：
- 用于产生文本的buffer
- buffer中文本的起始位置
- 头部和底部文本的内容
- 一个双向链接的结点链，每一个结点包含：
- 一个数据元素（单个lisp对象）
- 结点链中上一个和下一个结点的链接
- 一个将数据元素的文本插入到buffer中的打印函数
使用 ewoc-create 来定义一个ewoc对象，然后用其他的ewoc函数构建结点的结构并在buffer中显示。一旦在buffer中显示了文本，便可使用其他函数负责buffer的光标位置和结点间的数据通信。
让结点包含数据元素就像给变量设置值。通常结点包含数据元素的行为发生在将结点加入到ewoc对象过程中。可以通过下面两个函数获取和设置数据元素的值：
(ewoc-data node)
⇒ value
(ewoc-set-data node new-value)
⇒ new-value
也可以使用lisp对象(list or vector)或其他结构的索引作为数据元素的值。
当数据改变时，buffer中文本会相应的更新。使用 ewoc-update 函数更新所有结点，或者用 ewoc-invalidate ，使用 ewoc-map 函数给所有的结点增加条件判断。同时，可以使用 ewoc-delete 或 ewoc-filter 函数删除无效的结点并设置新的结点。删除一个结点的同时会删掉该结点在buffer中展示的文本。
函数
这一部分的术语中, ewoc 和 node 分别代表前面提到的两种结构，而 data 代表作为数据元素的lisp对象。三者的关系是：ewoc包含node，node包含data。下面详细介绍ewoc的每个函数。
— ewoc-create pretty-printer &optional header footer nosep
创建并返回一个不包含结点的ewoc对象。 pretty-printer 是包含一个数据元素参数的函数，该数据元素的文本值将被插入到buffer中。(使用 insert 函数插入，不要用 insert-before-markers ，因为它对ewoc包的内部机制有干扰)
通常，该函数会自动在头部文本，底部文本和每一个node的文本后插入新的一行。设置 nosep 参数为 non-nil 可以不插入新行，这在需要将整个ewoc的文本显示在一行时很有用。ewoc创建时会在当前buffer下维护文本，所以在调用创建函数前要先切换到目标buffer。
— ewoc-buffer ewoc
返回维护ewoc文本的buffer。
— ewoc-get-hf ewoc
返回一个由头部文本和底部文本构成的 cons cell (header . footer)。
— ewoc-enter-first ewoc data
— ewoc-enter-last ewoc data
分别在ewoc的结点链的开头和结尾添加包含数据元素的新结点。
— ewoc-enter-before ewoc node data
— ewoc-enter-after ewoc node data
分别在指定结点的前面和后面添加一个包含数据元素的新结点。
— ewoc-prev ewoc node
— ewoc-next ewoc node
分别返回指定结点的前一个和后一个结点。
— ewoc-nth ewoc n
返回以0开始的索引n的结点，n为负值时从最后开始索引。n超出范围时返回nil。
— ewoc-data node
获取并返回node包含的数据元素。
— ewoc-set-data node
设置node包含的数据元素值为data。
— ewoc-locate ewoc &optional pos guess
确定并返回包含光标位置的结点。如果ewoc没有结点，返回nil。如果 pos 在第一个结点之前，返回第一个结点；在最后一个结点之后，返回最后一个结点。可选参数 guess 是有可能在pos附近的结点，它不会改变函数的结果但会让函数执行的更快。
— ewoc-location node
返回结点的起始位置。
— ewoc-goto-prev ewoc arg
— ewoc-goto-next ewoc arg
分别移动光标到上arg个或下arg个结点。如果已经在第一个结点或ewoc为空, ewoc-goto-prev 不移动光标并返回nil，同样 ewoc-goto-next 不超过最后一个结点。除了以上特殊情况，函数返回移动到的结点。
— ewoc-goto-node ewoc node
移动光标到结点的起始位置。
— ewoc-refresh ewoc
重新生成ewoc的文本。执行过程是：删除header和footer之间的文本，然后为每一个结点依次调用 pretty-printer 函数生成文本。
— ewoc-invalidate ewoc &rest nodes
和 ewoc-refresh 类似，但只更新 nodes 列表内的结点而不是所有结点。
— ewoc-delete ewoc &rest nodes
删除所有 nodes 列表内的结点。
— ewoc-filter ewoc predicate &rest args
为ewoc中的每一个数据元素调用 predicate 函数，删除断言为nil的结点。 args 是传递给断言函数的参数。
— ewoc-collect ewoc predicate &rest args
为ewoc中的每一个数据元素调用 predicate 函数，返回断言为non-nil的元素列表。元素在列表中的顺序和buffer中一致。 args 是传递给断言函数的参数。
— ewoc-map map-function ewoc &rest args
为ewoc中的每一个数据元素调用 map-function , 更新map函数返回为non-nil的结点。 args 是传递给map函数的参数。
例子
下面是使用ewoc实现的显示颜色组成的例子，颜色组成由buffer中的三个整数组成的向量表示。
(setq colorcomp-ewoc nil
colorcomp-data nil
colorcomp-mode-map nil
colorcomp-labels ["Red" "Green" "Blue"])
(defun colorcomp-pp (data)
(if data
(let ((comp (aref colorcomp-data data)))
(insert (aref colorcomp-labels data) "\t: #x"
(format "%02X" comp) " "
(make-string (ash comp -2) ?#) "\n"))
(let ((cstr (format "#%02X%02X%02X"
(aref colorcomp-data 0)
(aref colorcomp-data 1)
(aref colorcomp-data 2)))
(samp " (sample text) "))
(insert "Color\t: "
(propertize samp 'face
`(foreground-color . ,cstr))
(propertize samp 'face
`(background-color . ,cstr))
"\n"))))
(defun colorcomp (color)
"Allow fiddling with COLOR in a new buffer.
The buffer is in Color Components mode."
(interactive "sColor (name or #RGB or #RRGGBB): ")
(when (string= "" color)
(setq color "green"))
(unless (color-values color)
(error "No such color: %S" color))
(switch-to-buffer
(generate-new-buffer (format "originally: %s" color)))
(kill-all-local-variables)
(setq major-mode 'colorcomp-mode
mode-name "Color Components")
(use-local-map colorcomp-mode-map)
(erase-buffer)
(buffer-disable-undo)
(let ((data (apply 'vector (mapcar (lambda (n) (ash n -8))
(color-values color))))
(ewoc (ewoc-create 'colorcomp-pp
"\nColor Components\n\n"
(substitute-command-keys
"\n\\{colorcomp-mode-map}"))))
(set (make-local-variable 'colorcomp-data) data)
(set (make-local-variable 'colorcomp-ewoc) ewoc)
(ewoc-enter-last ewoc 0)
(ewoc-enter-last ewoc 1)
(ewoc-enter-last ewoc 2)
(ewoc-enter-last ewoc nil)))
通过定义改变 colorcomp-data 的值，完成选择过程和按键绑定，这个例子可以拓展成一个颜色选择的组件(MVC模式中的模型)。
(defun colorcomp-mod (index limit delta)
(let ((cur (aref colorcomp-data index)))
(unless (= limit cur)
(aset colorcomp-data index (+ cur delta)))
(ewoc-invalidate
colorcomp-ewoc
(ewoc-nth colorcomp-ewoc index)
(ewoc-nth colorcomp-ewoc -1))))
(defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1))
(defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1))
(defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1))
(defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1))
(defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1))
(defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1))
(defun colorcomp-copy-as-kill-and-exit ()
"Copy the color components into the kill ring and kill the buffer.
The string is formatted #RRGGBB (hash followed by six hex digits)."
(interactive)
(kill-new (format "#%02X%02X%02X"
(aref colorcomp-data 0)
(aref colorcomp-data 1)
(aref colorcomp-data 2)))
(kill-buffer nil))
(setq colorcomp-mode-map
(let ((m (make-sparse-keymap)))
(suppress-keymap m)
(define-key m "i" 'colorcomp-R-less)
(define-key m "o" 'colorcomp-R-more)
(define-key m "k" 'colorcomp-G-less)
(define-key m "l" 'colorcomp-G-more)
(define-key m "," 'colorcomp-B-less)
(define-key m "." 'colorcomp-B-more)
(define-key m " " 'colorcomp-copy-as-kill-and-exit)
m))