33.19.1 查看文本属性

查看文本属性最简单的方式是查询特定位置字符的特定属性值,可使用函数 get-text-property 实现。 若要获取一个字符的完整属性列表,可使用 text-properties-at。 如需一次性查看多个字符的属性,参见 See 文本属性搜索函数 中相关函数。

这些函数同时支持字符串和缓冲区。需注意,字符串中的位置从 0 开始计数,而缓冲区中的位置从 1 开始。 操作非当前缓冲区时可能会较慢。

Function: get-text-property pos prop &optional object

该函数返回 object(缓冲区或字符串)中 pos 位置之后字符的 prop 属性值。 参数 object 为可选参数,默认值是当前缓冲区。

position 位于 object 的末尾,返回值为 nil,但需注意缓冲区缩窄(narrowing)不会影响该值。 也就是说,如果 object 是缓冲区或 nil,且缓冲区已被缩窄,同时 position 位于缩窄后缓冲区的末尾,返回结果仍可能非 nil

如果严格来说该字符没有 prop 属性,但拥有属性类别(值为符号),则 get-text-property 会返回该符号的 prop 属性值。

Function: get-char-property position prop &optional object

该函数与 get-text-property 类似,区别是它会先检查覆盖层(overlay),再检查文本属性。 See 覆盖层

参数 object 可以是字符串、缓冲区或窗口。 如果是窗口,则使用该窗口中显示的缓冲区来获取文本属性和覆盖层,但仅考虑对该窗口有效的覆盖层。 如果是缓冲区,则先按优先级从高到低检查该缓冲区中的覆盖层,再检查文本属性。 如果是字符串,则仅检查文本属性(因为字符串不存在覆盖层)。

Function: get-pos-property position prop &optional object

该函数与 get-char-property 类似,区别是它会关注属性的粘性(stickiness)和覆盖层的进阶设置,而非 position 位置(即紧随其后)字符的属性。

Function: get-char-property-and-overlay position prop &optional object

该函数与 get-char-property 类似,但会额外返回属性值来源的覆盖层相关信息。

返回值是一个序对(cons cell),其 CAR 部分为属性值(与 get-char-property 传入相同参数时的返回值一致), CDR 部分为找到该属性的覆盖层对象;若属性来自文本属性或未找到该属性,则 CDRnil

position 位于 object 的末尾,返回值的 CARCDR 均为 nil

Variable: char-property-alias-alist

该变量存储一个关联列表(alist),用于将属性名映射到备选属性名列表。 如果字符未直接指定某属性的值,会按顺序查询备选属性名;第一个非 nil 的值将被采用。 该变量的优先级高于 default-text-properties,而 category 属性的优先级高于该变量。

Function: text-properties-at position &optional object

该函数返回字符串或缓冲区 objectposition 位置字符的完整属性列表。 若 objectnil,默认使用当前缓冲区。

position 位于 object 的末尾,返回值为 nil,但需注意缓冲区缩窄不会影响该值。 也就是说,如果 object 是缓冲区或 nil,且缓冲区已被缩窄,同时 position 位于缩窄后缓冲区的末尾,返回结果仍可能非 nil

Variable: default-text-properties

该变量存储一个属性列表,用于提供文本属性的默认值。 当字符既未直接指定某属性的值,也未通过类别符号或 char-property-alias-alist 间接指定时,将使用该列表中存储的值。示例如下:

(setq default-text-properties '(foo 69)
      char-property-alias-alist nil)
;; Make sure character 1 has no properties of its own.
(set-text-properties 1 2 nil)
;; What we get, when we ask, is the default value.
(get-text-property 1 'foo)
     ⇒ 69
Function: object-intervals OBJECT

该函数返回 object 中所有区间(即文本属性)的副本,形式为区间列表。 object 必须是字符串或缓冲区。修改该列表的结构不会改变对象中的区间。

(object-intervals (propertize "foo" 'face 'bold))
     ⇒ ((0 3 (face bold)))

返回列表中的每个元素代表一个区间,每个区间包含三部分:第一部分是起始位置,第二部分是结束位置,第三部分是文本属性本身。