From ddd17794fd65dcb90074eee60c7cad43612a75cb Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 16 Dec 2025 04:04:18 +0000 Subject: [PATCH] Add documentation for missing APIs: tp-add-to-layers, tp-add-to-all-layers, tp-intervals, tp-intervals-map, tp-region-layer-props, tp-plist, tp-empty-p Co-authored-by: Kinneyzhang <38454496+Kinneyzhang@users.noreply.github.com> --- README.md | 213 +++++++++++++++++++++++++++++++++++++++++++++++++++ README_CN.md | 213 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 426 insertions(+) diff --git a/README.md b/README.md index 3d03265..a933fca 100644 --- a/README.md +++ b/README.md @@ -246,6 +246,21 @@ A complete overview of all tp.el functions organized by category: | [`tp-layer-count`](#tp-layer-count) | Count layers in region | | [`tp-layer-exists-p`](#tp-layer-exists-p) | Check if layer exists in region | | [`tp-layer-top`](#tp-layer-top) | Get name of top (visible) layer | +| [`tp-region-layer-props`](#tp-region-layer-props---get-layer-properties-in-region) | Get properties for a specific layer in region | + +#### Property Layer Manipulation Functions +| Function | Description | +|----------|-------------| +| [`tp-add-to-layers`](#tp-add-to-layers---add-properties-to-specific-layers) | Add/merge properties to specific layers by index or name | +| [`tp-add-to-all-layers`](#tp-add-to-all-layers---add-properties-to-all-layers) | Add/merge properties to all existing layers | + +#### Utility Functions +| Function | Description | +|----------|-------------| +| [`tp-intervals`](#tp-intervals---get-text-property-intervals) | Get all text property intervals in a region | +| [`tp-intervals-map`](#tp-intervals-map---apply-function-to-intervals) | Apply function to all intervals in a region | +| [`tp-plist`](#tp-plist---get-all-properties-in-region) | Get all properties present in a region | +| [`tp-empty-p`](#tp-empty-p---check-if-object-has-properties) | Check if object has no text properties | --- @@ -1731,6 +1746,204 @@ Get name of the top (visible) layer. --- +#### `tp-add-to-layers` - Add Properties to Specific Layers + +```elisp +;; Buffer/string region +(tp-add-to-layers IDX-OR-LAYER-NAME-LIST START END PLIST &optional OBJECT) + +;; Entire string +(tp-add-to-layers IDX-OR-LAYER-NAME-LIST STRING PROP VAL ...) +``` + +Add or merge properties to specific layers in a region or string. + +- **IDX-OR-LAYER-NAME-LIST** is a list of layer indices (integers) or layer names (symbols). For indices: 0 means top layer, -1 means bottom layer. +- Properties are deeply merged into the specified layers (nested plists are merged, not replaced). +- OBJECT defaults to current buffer for region form. +- Returns the modified string or nil for buffer operations. + +**Examples:** + +```elisp +(progn + (tp-layer-reset) + (tp-define-layer layer1 (face (:foreground "red"))) + (tp-define-layer layer2 (face (:foreground "blue"))) + (with-temp-buffer + (insert "Hello World") + (tp-push-layer 1 10 'layer1) + (tp-push-layer 1 10 'layer2) + ;; Add underline to both layers + (tp-add-to-layers '(0 1) 1 10 '(face (:underline t))) + (tp-at 5))) +;; Both layers now have underline merged with their colors +``` + +--- + +#### `tp-add-to-all-layers` - Add Properties to All Layers + +```elisp +;; Buffer/string region +(tp-add-to-all-layers START END PLIST &optional OBJECT) + +;; Entire string +(tp-add-to-all-layers STRING PROP VAL ...) +``` + +Add or merge properties to all layers in a region or string. + +- Properties are deeply merged into all existing layers. +- OBJECT defaults to current buffer for region form. +- Returns the modified string or nil for buffer operations. + +**Examples:** + +```elisp +(let ((str (copy-sequence "Hello World"))) + (tp-define-layer layer1 (face bold)) + (tp-define-layer layer2 (face italic)) + (tp-push-layer 0 5 'layer1 str) + (tp-push-layer 0 5 'layer2 str) + ;; Add underline to all layers + (tp-add-to-all-layers 0 5 '(face (:underline t)) str) + str) +``` + +--- + +#### `tp-intervals` - Get Text Property Intervals + +```elisp +(tp-intervals START END &optional OBJECT) +``` + +Get all text property intervals from START to END in OBJECT. + +- Returns a list of (START END PROPERTIES) for each interval. +- Uses `object-intervals` (requires Emacs 28.1+). +- OBJECT can be a buffer or string; nil defaults to current buffer. + +**Examples:** + +```elisp +(with-temp-buffer + (insert "Hello World") + (tp-set 1 6 '(face bold)) + (tp-set 7 12 '(face italic)) + (tp-intervals 1 12)) +;; => ((0 5 (face bold)) (6 11 (face italic))) +``` + +--- + +#### `tp-intervals-map` - Apply Function to Intervals + +```elisp +(tp-intervals-map FUNCTION START END &optional OBJECT) +``` + +Apply FUNCTION to all intervals between START and END in OBJECT. + +- FUNCTION receives four arguments: interval-start, interval-end, top-props (visible layer properties), and below-props-lst (list of hidden layers). +- OBJECT can be a buffer or string; nil defaults to current buffer. +- Returns list of function results (nil values are removed). + +**Examples:** + +```elisp +(with-temp-buffer + (insert "Hello World") + (tp-set 1 6 '(face bold)) + (tp-set 7 12 '(face italic)) + (tp-intervals-map + (lambda (start end props belows) + (list start end (plist-get props 'face))) + 1 12)) +;; => ((0 5 bold) (6 11 italic)) +``` + +--- + +#### `tp-region-layer-props` - Get Layer Properties in Region + +```elisp +(tp-region-layer-props START END LAYER-NAME &optional OBJECT) +``` + +Return layer properties for LAYER-NAME in region from START to END. + +- Returns a list of (START END PROPERTIES) for matching intervals. +- OBJECT defaults to current buffer. + +**Examples:** + +```elisp +(progn + (tp-layer-reset) + (tp-define-layer highlight (face (:background "yellow"))) + (with-temp-buffer + (insert "Hello World Test") + (tp-push-layer 1 6 'highlight) + (tp-push-layer 12 16 'highlight) + (tp-region-layer-props 1 16 'highlight))) +;; => ((1 6 (face (:background "yellow") tp-name highlight)) +;; (12 16 (face (:background "yellow") tp-name highlight))) +``` + +--- + +#### `tp-plist` - Get All Properties in Region + +```elisp +;; Buffer/string region +(tp-plist START END &optional OBJECT) + +;; Entire string +(tp-plist STRING) +``` + +Get a property list of all properties present in a region or string. + +- Returns a plist containing all properties found in the range. +- OBJECT defaults to current buffer for region form. + +**Examples:** + +```elisp +(with-temp-buffer + (insert "Hello World") + (tp-set 1 6 '(face bold help-echo "Tip")) + (tp-set 7 12 '(face italic)) + (tp-plist 1 12)) +;; => (face bold help-echo "Tip" face italic) +``` + +--- + +#### `tp-empty-p` - Check if Object Has Properties + +```elisp +(tp-empty-p &optional OBJECT) +``` + +Return t if OBJECT has no text properties. + +- OBJECT can be a string or buffer; nil defaults to current buffer. +- Uses `object-intervals` (requires Emacs 28.1+). + +**Examples:** + +```elisp +(tp-empty-p "plain text") ; => t +(let ((str (copy-sequence "text"))) + (tp-set str 'face 'bold) + (tp-empty-p str)) ; => nil +``` + +--- + ## Practical Examples ### Syntax Highlighting with Multiple Layers diff --git a/README_CN.md b/README_CN.md index 1dffde9..05ae8e6 100644 --- a/README_CN.md +++ b/README_CN.md @@ -245,6 +245,21 @@ tp.el 所有函数按类别组织的完整概览： | [`tp-layer-count`](#tp-layer-count) | 计算区域中的属性层数量 | | [`tp-layer-exists-p`](#tp-layer-exists-p) | 检查区域中是否存在某属性层 | | [`tp-layer-top`](#tp-layer-top) | 获取顶层（可见）属性层的名称 | +| [`tp-region-layer-props`](#tp-region-layer-props---获取区域中的层属性) | 获取区域中特定层的属性 | + +#### 属性层操作函数 +| 函数 | 描述 | +|------|------| +| [`tp-add-to-layers`](#tp-add-to-layers---向特定属性层添加属性) | 通过索引或名称向特定层添加/合并属性 | +| [`tp-add-to-all-layers`](#tp-add-to-all-layers---向所有属性层添加属性) | 向所有现有层添加/合并属性 | + +#### 实用工具函数 +| 函数 | 描述 | +|------|------| +| [`tp-intervals`](#tp-intervals---获取文本属性区间) | 获取区域中的所有文本属性区间 | +| [`tp-intervals-map`](#tp-intervals-map---对区间应用函数) | 对区域中的所有区间应用函数 | +| [`tp-plist`](#tp-plist---获取区域中的所有属性) | 获取区域中存在的所有属性 | +| [`tp-empty-p`](#tp-empty-p---检查对象是否有属性) | 检查对象是否没有文本属性 | --- @@ -1725,6 +1740,204 @@ Emacs 的 `text-property-search-forward` 和 `text-property-search-backward` 的 --- +#### `tp-add-to-layers` - 向特定属性层添加属性 + +```elisp +;; 缓冲区/字符串区域 +(tp-add-to-layers IDX-OR-LAYER-NAME-LIST START END PLIST &optional OBJECT) + +;; 整个字符串 +(tp-add-to-layers IDX-OR-LAYER-NAME-LIST STRING PROP VAL ...) +``` + +向区域或字符串中的特定属性层添加或合并属性。 + +- **IDX-OR-LAYER-NAME-LIST** 是层索引（整数）或层名称（符号）的列表。对于索引：0 表示顶层，-1 表示底层。 +- 属性被深度合并到指定的层中（嵌套的 plist 被合并，而非替换）。 +- OBJECT 在区域形式中默认为当前缓冲区。 +- 返回修改后的字符串或 nil（对于缓冲区操作）。 + +**示例：** + +```elisp +(progn + (tp-layer-reset) + (tp-define-layer layer1 (face (:foreground "red"))) + (tp-define-layer layer2 (face (:foreground "blue"))) + (with-temp-buffer + (insert "Hello World") + (tp-push-layer 1 10 'layer1) + (tp-push-layer 1 10 'layer2) + ;; 向两个层添加下划线 + (tp-add-to-layers '(0 1) 1 10 '(face (:underline t))) + (tp-at 5))) +;; 两个层现在都有下划线与其颜色合并 +``` + +--- + +#### `tp-add-to-all-layers` - 向所有属性层添加属性 + +```elisp +;; 缓冲区/字符串区域 +(tp-add-to-all-layers START END PLIST &optional OBJECT) + +;; 整个字符串 +(tp-add-to-all-layers STRING PROP VAL ...) +``` + +向区域或字符串中的所有属性层添加或合并属性。 + +- 属性被深度合并到所有现有层中。 +- OBJECT 在区域形式中默认为当前缓冲区。 +- 返回修改后的字符串或 nil（对于缓冲区操作）。 + +**示例：** + +```elisp +(let ((str (copy-sequence "Hello World"))) + (tp-define-layer layer1 (face bold)) + (tp-define-layer layer2 (face italic)) + (tp-push-layer 0 5 'layer1 str) + (tp-push-layer 0 5 'layer2 str) + ;; 向所有层添加下划线 + (tp-add-to-all-layers 0 5 '(face (:underline t)) str) + str) +``` + +--- + +#### `tp-intervals` - 获取文本属性区间 + +```elisp +(tp-intervals START END &optional OBJECT) +``` + +从 OBJECT 中获取 START 到 END 之间的所有文本属性区间。 + +- 返回每个区间的 (START END PROPERTIES) 列表。 +- 使用 `object-intervals`（需要 Emacs 28.1+）。 +- OBJECT 可以是缓冲区或字符串；nil 默认为当前缓冲区。 + +**示例：** + +```elisp +(with-temp-buffer + (insert "Hello World") + (tp-set 1 6 '(face bold)) + (tp-set 7 12 '(face italic)) + (tp-intervals 1 12)) +;; => ((0 5 (face bold)) (6 11 (face italic))) +``` + +--- + +#### `tp-intervals-map` - 对区间应用函数 + +```elisp +(tp-intervals-map FUNCTION START END &optional OBJECT) +``` + +对 OBJECT 中 START 到 END 之间的所有区间应用 FUNCTION。 + +- FUNCTION 接收四个参数：interval-start、interval-end、top-props（可见层属性）和 below-props-lst（隐藏层列表）。 +- OBJECT 可以是缓冲区或字符串；nil 默认为当前缓冲区。 +- 返回函数结果列表（nil 值被移除）。 + +**示例：** + +```elisp +(with-temp-buffer + (insert "Hello World") + (tp-set 1 6 '(face bold)) + (tp-set 7 12 '(face italic)) + (tp-intervals-map + (lambda (start end props belows) + (list start end (plist-get props 'face))) + 1 12)) +;; => ((0 5 bold) (6 11 italic)) +``` + +--- + +#### `tp-region-layer-props` - 获取区域中的层属性 + +```elisp +(tp-region-layer-props START END LAYER-NAME &optional OBJECT) +``` + +返回区域 START 到 END 中 LAYER-NAME 的层属性。 + +- 返回匹配区间的 (START END PROPERTIES) 列表。 +- OBJECT 默认为当前缓冲区。 + +**示例：** + +```elisp +(progn + (tp-layer-reset) + (tp-define-layer highlight (face (:background "yellow"))) + (with-temp-buffer + (insert "Hello World Test") + (tp-push-layer 1 6 'highlight) + (tp-push-layer 12 16 'highlight) + (tp-region-layer-props 1 16 'highlight))) +;; => ((1 6 (face (:background "yellow") tp-name highlight)) +;; (12 16 (face (:background "yellow") tp-name highlight))) +``` + +--- + +#### `tp-plist` - 获取区域中的所有属性 + +```elisp +;; 缓冲区/字符串区域 +(tp-plist START END &optional OBJECT) + +;; 整个字符串 +(tp-plist STRING) +``` + +获取区域或字符串中存在的所有属性的属性列表。 + +- 返回包含范围内找到的所有属性的 plist。 +- OBJECT 在区域形式中默认为当前缓冲区。 + +**示例：** + +```elisp +(with-temp-buffer + (insert "Hello World") + (tp-set 1 6 '(face bold help-echo "Tip")) + (tp-set 7 12 '(face italic)) + (tp-plist 1 12)) +;; => (face bold help-echo "Tip" face italic) +``` + +--- + +#### `tp-empty-p` - 检查对象是否有属性 + +```elisp +(tp-empty-p &optional OBJECT) +``` + +如果 OBJECT 没有文本属性，返回 t。 + +- OBJECT 可以是字符串或缓冲区；nil 默认为当前缓冲区。 +- 使用 `object-intervals`（需要 Emacs 28.1+）。 + +**示例：** + +```elisp +(tp-empty-p "plain text") ; => t +(let ((str (copy-sequence "text"))) + (tp-set str 'face 'bold) + (tp-empty-p str)) ; => nil +``` + +--- + ## 实用示例 ### 多属性层语法高亮