26.13.2 往返格式规范

两种机制中更为通用的一种由变量 format-alist 控制,该变量是一个 文件格式 规范列表,用于描述文件中用于表示 Emacs 缓冲区数据的文本形式。读取与写入的描述是配对的,因此我们称之为“往返(round-trip)”规范(非配对规范参见 see 分步格式规范)。

Variable: format-alist

该列表为每个已定义的文件格式保存一条格式定义。每条格式定义为如下形式的列表:

(name doc-string regexp from-fn to-fn modify mode-fn preserve)

格式定义中各元素的含义如下:

name

该格式的名称。

doc-string

该格式的文档字符串。

regexp

用于识别采用此格式的文件的正则表达式。若为 nil,则该格式不会被自动应用。

from-fn

用于解码该格式数据的 Shell 命令或函数(即将文件数据转换为 Emacs 常规数据表示形式)。

Shell 命令以字符串形式表示;Emacs 会将该命令作为过滤器执行转换。

from-fn 为函数,它会接收两个参数 beginend,指定缓冲区中需要转换的区域。该函数应通过原地编辑的方式修改文本。由于这可能改变文本长度,from-fn 应当返回修改后的结束位置。

from-fn 的一项职责是确保文件开头不再匹配 regexp,否则可能会被重复调用。此外,from-fn 不得涉及正在解码的文件或缓冲区之外的其他缓冲区或文件,否则用于格式处理的内部缓冲区可能被覆盖。

to-fn

用于编码该格式数据的 Shell 命令或函数——即将 Emacs 常规数据表示形式转换为该格式。

to-fn 为字符串,则表示一条 Shell 命令;Emacs 会将该命令作为过滤器执行转换。

to-fn 为函数,它会接收三个参数:beginend 指定缓冲区中需要转换的区域,buffer 指定目标缓冲区。转换方式有两种:

  • 通过原地编辑缓冲区。这种情况下,to-fn 应当返回被修改文本区域的结束位置。
  • 返回注解列表。该列表元素形式为 (position . string),其中 position 为待写入文本中的相对位置,string 为要在该位置添加的注解。to-fn 返回时,列表必须按位置升序排列。

    write-region 实际将缓冲区文本写入文件时,会在对应位置插入指定的注解。整个过程不会修改缓冲区内容。

to-fn 不得涉及正在编码的文件或缓冲区之外的其他缓冲区或文件,否则用于格式处理的内部缓冲区可能被覆盖。

modify

一个标志位;若编码函数会修改缓冲区则为 t,若通过返回注解列表实现则为 nil

mode-fn

访问从该格式转换而来的文件后需要调用的次要模式函数。该函数接收一个整数参数 1,用于告知次要模式函数启用该模式。

preserve

一个标志位;若 format-write-file 不应将该格式从 buffer-file-format 中移除则为t

函数 insert-file-contents 在读取指定文件时会自动识别文件格式。它将文件开头的文本与格式定义中的正则表达式进行匹配,若匹配成功则调用对应格式的解码函数,之后再次检查所有已知格式,直到没有格式可应用为止。

通过 find-file-noselect 或相关命令访问文件时同样会执行格式转换(因为其内部调用了 insert-file-contents);同时会为每个解码的格式调用对应的模式函数,并将格式名称列表保存到缓冲区局部变量 buffer-file-format 中。

Variable: buffer-file-format

该变量记录所访问文件的格式。更准确地说,它是访问当前缓冲区对应文件时解码所用的文件格式名称列表。该变量在所有缓冲区中均为缓冲区局部变量。

write-region向文件写入数据时,会先按照buffer-file-format列表中的顺序,调用对应格式的编码函数。

Command: format-write-file file format &optional confirm

该命令以 format 指定的格式将当前缓冲区内容写入文件 file,其中 format 为格式名称列表。它会以 format 为基础,追加 buffer-file-formatpreserve 标志为非 nil 且未出现在 format 中的元素,构建实际使用的格式。随后更新 buffer-file-format 为该格式,作为后续保存的默认格式。除 format 参数外,该命令与 write-file 类似。其中 confirm 的含义与交互处理方式和 write-file 的对应参数一致,see Definition of write-file

Command: format-find-file file format

该命令打开文件 file 并按照 format 指定的格式进行转换。若后续保存该缓冲区,format 会作为默认格式。

参数 format 为格式名称列表。若 formatnil,则不执行转换。交互模式下,为 format 直接按 RET 即指定为 nil

Command: format-insert-file file format &optional beg end

该命令插入文件 file 的内容,并按照 format 指定的格式进行转换。若 begendnil,则指定读取文件的部分区域,用法与 insert-file-contents 相同(see 从文件读取)。

返回值与 insert-file-contents 一致:为包含文件绝对路径和插入数据长度(转换后)的列表。

参数 format 为格式名称列表。若 formatnil,则不执行转换。交互模式下,为 format 直接按 RET 即指定为 nil

Variable: buffer-auto-save-file-format

该变量指定自动保存所用的格式。其值为格式名称列表,与 buffer-file-format 形式相同;但在写入自动保存文件时会替代 buffer-file-format 使用。若值为 t(默认值),则自动保存使用与常规保存相同的格式。该变量在所有缓冲区中均为缓冲区局部变量。


emacs

Emacs

org-mode

Orgmode

Donations

打赏

Copyright

© Jasper Hsu

Creative Commons

Creative Commons

Attribute

Attribute

Noncommercial

Noncommercial

Share Alike

Share Alike