geekinney/tp
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

Update README.md and README_CN.md to document new API functions

Browse Source 
Co-authored-by: Kinneyzhang <38454496+Kinneyzhang@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot] 2025-12-14 12:12:31 +00:00
parent 39c1c6333b
commit 2bf16e1207
2 changed files with 584 additions and 204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

394
README.md
View File

@ -23,11 +23,13 @@
## Features ## Features
- ✅ **Unified Object Support**: Functions like `tp-put`, `tp-match`, `tp-regexp` work on both strings and buffers - ✅ **Unified Object Support**: Functions like `tp-set`, `tp-match`, `tp-regexp` work on both strings and buffers
- ✅ **Clear Semantics**: `tp-reset` (replace all), `tp-set` (replace specified), `tp-add` (deep merge)
- ✅ **Nested Property Access**: Get/set/remove nested sub-properties with path syntax
- ✅ **Innovative Layer System**: Stack, rotate, and manage multiple layers of properties - ✅ **Innovative Layer System**: Stack, rotate, and manage multiple layers of properties
- ✅ **Layer Groups**: Define reusable sets of related layers - ✅ **Layer Groups**: Define reusable sets of related layers
- ✅ **Search & Navigation**: Find and navigate through propertized text - ✅ **Search & Navigation**: Find and navigate through propertized text
- ✅ **Pattern Matching**: Apply properties to string/regexp matches - ✅ **Pattern Matching**: Apply properties to string/regexp matches with reset/add variants
- ✅ **Clean API**: Consistent naming and calling conventions - ✅ **Clean API**: Consistent naming and calling conventions
## Requirements ## Requirements
@ -56,28 +58,58 @@ Or with `use-package`:
### Setting Properties ### Setting Properties
tp.el provides three main functions for setting properties, each with different semantics:
```elisp
;; tp-set: Replace only specified properties, preserve others
(tp-set 1 10 '(face bold help-echo "Hello!"))
;; tp-reset: Completely replace ALL properties
(tp-reset 1 10 '(face bold)) ; Any other properties are removed
;; tp-add: Deep merge nested properties
(tp-add 1 10 '(face (:underline t))) ; Merges with existing face
```
All three functions support four calling conventions:
```elisp ```elisp
;; On current buffer (properties as a list) ;; On current buffer (properties as a list)
(tp-put 1 10 '(face bold help-echo "Hello!")) (tp-set 1 10 '(face bold help-echo "Hello!"))
;; On a specific buffer ;; On a specific buffer
(tp-put 1 10 '(face bold) some-buffer) (tp-set 1 10 '(face bold) some-buffer)
;; On a string with range (0-indexed) ;; On a string with range (0-indexed)
(tp-put 0 5 '(face bold) "Hello World") (tp-set 0 5 '(face bold) "Hello World")
;; => #("Hello World" 0 5 (face bold)) ;; => #("Hello World" 0 5 (face bold))
;; On entire string (flat properties) ;; On entire string (flat properties)
(tp-put "Hello World" 'face 'bold 'help-echo "test") (tp-set "Hello World" 'face 'bold 'help-echo "test")
;; => #("Hello World" 0 11 (face bold help-echo "test")) ;; => #("Hello World" 0 11 (face bold help-echo "test"))
``` ```
### Single-Property Setters
```elisp
;; Set only face property
(tp-set-face 1 10 'bold)
(tp-set-face "Hello" 'italic) ; entire string
;; Set only display property
(tp-set-display 1 10 '(space :width 10))
```
### Getting Properties ### Getting Properties
```elisp ```elisp
;; Get specific property at position ;; Get specific property at position
(tp-get 5 'face) ; => bold (tp-get 5 'face) ; => bold
;; Get nested sub-property
(tp-get 5 'face :foreground) ; => "red"
(tp-get 5 'face :box :color) ; => "blue" (deeply nested)
;; Get specific property from range ;; Get specific property from range
(tp-get 1 10 'face) ; => bold (tp-get 1 10 'face) ; => bold
@ -88,31 +120,44 @@ Or with `use-package`:
(tp-at 5) ; => (face bold help-echo "Hello!") (tp-at 5) ; => (face bold help-echo "Hello!")
``` ```
### Fine-grained Property Manipulation ### Removing Properties
```elisp ```elisp
;; Get sub-property from face ;; Remove entire property
(tp-get-sub 1 'face :foreground) ; => "red" (tp-remove 1 10 'face)
;; Set sub-property on face ;; Remove sub-property
(tp-put-sub 1 6 'face :foreground "blue") (tp-remove 1 10 '(face :underline))
;; Remove sub-property from face ;; Remove nested sub-properties (keep others)
(tp-remove-sub 1 6 'face :foreground) (tp-remove 1 10 '(face :underline (:style :position)))
;; Removes :style and :position from :underline, keeps :color if present
``` ```
### Pattern Matching ### Pattern Matching
```elisp ```elisp
;; Apply properties to all occurrences of "TODO" in buffer ;; Apply properties to all occurrences of "TODO" in buffer
(tp-match "TODO" 'face 'warning) (tp-match "TODO" '(face warning))
;; Apply to string ;; Apply to string
(tp-match "world" "Hello world world" 'face 'bold) (tp-match "world" "Hello world world" '(face bold))
;; => #("Hello world world" 6 11 (face bold) 12 17 (face bold)) ;; => #("Hello world world" 6 11 (face bold) 12 17 (face bold))
;; Match with (PATTERN STRING) format
(tp-match '("world" "Hello world") '(face bold))
;; => #("Hello world" 6 11 (face bold))
;; Using regexp ;; Using regexp
(tp-regexp "\\b[0-9]+\\b" 'face 'font-lock-number-face) (tp-regexp "\\b[0-9]+\\b" '(face font-lock-number-face))
;; Reset variants (replace ALL properties on matches)
(tp-match-reset "TODO" '(face warning))
(tp-regexp-reset "[0-9]+" '(face bold))
;; Add variants (deep merge properties on matches)
(tp-match-add "TODO" '(face (:underline t)))
(tp-regexp-add "[0-9]+" '(face (:weight bold)))
``` ```
--- ---
@ -121,53 +166,137 @@ Or with `use-package`:
### Core Property Functions ### Core Property Functions
#### `tp-put` - Set Text Properties #### `tp-set` - Set Text Properties
Set text properties on a string or buffer region. Set text properties on a string or buffer region. Replaces only the specified properties, preserving others.
```elisp ```elisp
;; Current buffer (properties as a list) ;; Current buffer (properties as a list)
(tp-put START END '(PROPERTY VALUE ...)) (tp-set START END '(PROPERTY VALUE ...))
;; Specific buffer or string ;; Specific buffer or string
(tp-put START END '(PROPERTY VALUE ...) OBJECT) (tp-set START END '(PROPERTY VALUE ...) OBJECT)
;; Entire string (flat properties) ;; Entire string (flat properties)
(tp-put STRING PROPERTY VALUE ...) (tp-set STRING PROPERTY VALUE ...)
``` ```
**Examples:** **Examples:**
```elisp ```elisp
;; Set face on buffer region ;; Set face on buffer region
(tp-put 1 10 '(face bold)) ; => (1 . 10) (tp-set 1 10 '(face bold)) ; => (1 . 10)
;; Set multiple properties ;; Set multiple properties
(tp-put 1 10 '(face bold help-echo "Click me")) (tp-set 1 10 '(face bold help-echo "Click me"))
;; Set on specific buffer ;; Set on specific buffer
(tp-put 1 10 '(face italic) my-buffer) (tp-set 1 10 '(face italic) my-buffer)
;; Set properties on a string (0-indexed) ;; Set properties on a string (0-indexed)
(setq my-string (tp-put 0 5 '(face italic) "Hello World")) (setq my-string (tp-set 0 5 '(face italic) "Hello World"))
;; => #("Hello World" 0 5 (face italic)) ;; => #("Hello World" 0 5 (face italic))
;; Set properties on entire string ;; Set properties on entire string
(tp-put "Hello" 'face 'bold 'mouse-face 'highlight) (tp-set "Hello" 'face 'bold 'mouse-face 'highlight)
;; => #("Hello" 0 5 (face bold mouse-face highlight)) ;; => #("Hello" 0 5 (face bold mouse-face highlight))
``` ```
--- ---
#### `tp-reset` - Replace All Properties
Completely replace ALL text properties with the specified ones.
```elisp
(tp-reset START END '(PROPERTY VALUE ...) &optional OBJECT)
(tp-reset STRING PROPERTY VALUE ...)
```
**Examples:**
```elisp
;; Replace all properties in region
(tp-reset 1 10 '(face bold)) ; Any existing properties are removed
;; On string
(tp-reset "Hello" 'face 'italic)
```
---
#### `tp-add` - Add/Merge Properties
Add or update properties with deep merge support for nested plists.
```elisp
(tp-add START END '(PROPERTY VALUE ...) &optional OBJECT)
(tp-add STRING PROPERTY VALUE ...)
```
**Examples:**
```elisp
;; Add properties (preserves existing, merges nested)
(tp-add 1 10 '(help-echo "tooltip"))
;; Deep merge face properties
(tp-set 1 10 '(face (:foreground "red")))
(tp-add 1 10 '(face (:background "blue")))
;; Result: face is (:foreground "red" :background "blue")
```
---
#### `tp-set-face` - Set Face Property
Set only the face property, preserving other properties.
```elisp
(tp-set-face START END FACE &optional OBJECT)
(tp-set-face STRING FACE)
```
**Examples:**
```elisp
(tp-set-face 1 10 'bold)
(tp-set-face 1 10 '(:foreground "red" :weight bold))
(tp-set-face "Hello" 'italic)
```
---
#### `tp-set-display` - Set Display Property
Set only the display property, preserving other properties.
```elisp
(tp-set-display START END DISPLAY &optional OBJECT)
(tp-set-display STRING DISPLAY)
```
**Examples:**
```elisp
(tp-set-display 1 10 '(space :width 10))
(tp-set-display " " '(space :width 20))
```
---
#### `tp-get` - Get Property Value #### `tp-get` - Get Property Value
Get property value(s) from position or range. Get property value(s) from position or range, with support for nested sub-properties.
```elisp ```elisp
;; Single position ;; Single position
(tp-get POSITION PROPERTY) (tp-get POSITION PROPERTY)
(tp-get POSITION PROPERTY OBJECT) (tp-get POSITION PROPERTY OBJECT)
;; Nested sub-property access
(tp-get POSITION PROPERTY SUB-KEY ...)
;; Range - specific property ;; Range - specific property
(tp-get START END PROPERTY) (tp-get START END PROPERTY)
(tp-get START END PROPERTY OBJECT) (tp-get START END PROPERTY OBJECT)
@ -183,6 +312,11 @@ Get property value(s) from position or range.
;; Get from current buffer ;; Get from current buffer
(tp-get 5 'face) ; => bold (tp-get 5 'face) ; => bold
;; Get nested sub-property
(tp-get 5 'face :foreground) ; => "red"
(tp-get 5 'face :box :color) ; => "blue"
(tp-get 5 'display :width) ; => 10
;; Get from string (0-indexed) ;; Get from string (0-indexed)
(tp-get 0 'face my-string) ; => italic (tp-get 0 'face my-string) ; => italic
@ -244,16 +378,32 @@ Get all text properties at POINT as a plist.
#### `tp-remove` - Remove Property #### `tp-remove` - Remove Property
```elisp Remove a property or nested sub-property from a region.
(tp-remove START END PROPERTY &optional OBJECT)
```
Remove a specific property from a region. ```elisp
;; Remove entire property
(tp-remove START END PROPERTY &optional OBJECT)
;; Remove sub-property
(tp-remove START END '(PROPERTY SUB-KEY) &optional OBJECT)
;; Remove nested sub-properties
(tp-remove START END '(PROPERTY SUB-KEY (NESTED-KEYS...)) &optional OBJECT)
```
**Examples:** **Examples:**
```elisp ```elisp
(tp-remove 1 10 'face) ; Remove face property ;; Remove entire property
(tp-remove 1 10 'face)
;; Remove sub-property from face
(tp-remove 1 10 '(face :underline))
;; Remove specific nested keys, keep others
(tp-remove 1 10 '(face :underline (:style :position)))
;; Removes :style and :position from :underline
;; If :color exists in :underline, it's preserved
``` ```
--- ---
@ -291,35 +441,122 @@ Clear all text properties from a region.
--- ---
### Propertize Functions ### Pattern Matching Functions
#### `tp-propertize` - Create Propertized String #### `tp-match` - Match String
```elisp ```elisp
;; Create propertized string ;; Buffer
(tp-propertize STRING PROPERTY VALUE ...) (tp-match PATTERN '(PROPERTY VALUE ...))
(tp-propertize STRING '(PROPERTY VALUE ...))
;; Apply to region of object ;; String or Buffer object
(tp-propertize OBJECT START END PROPERTY VALUE ...) (tp-match PATTERN OBJECT '(PROPERTY VALUE ...))
;; Pattern as (PATTERN STRING) format
(tp-match '(PATTERN STRING) '(PROPERTY VALUE ...))
```
Set properties on all occurrences of a string pattern.
**Examples:**
```elisp
;; In buffer - returns list of (START . END) pairs
(tp-match "TODO" '(face warning))
;; => ((10 . 14) (50 . 54) ...)
;; On string - returns modified string
(tp-match "o" "Hello World" '(face bold))
;; => #("Hello World" 4 5 (face bold) 7 8 (face bold))
;; Using (PATTERN STRING) format
(tp-match '("world" "Hello world") '(face bold))
;; => #("Hello world" 6 11 (face bold))
```
---
#### `tp-match-reset` - Match and Reset
Reset (completely replace) all properties on matches.
```elisp
(tp-match-reset PATTERN '(PROPERTY VALUE ...) &optional OBJECT)
``` ```
**Examples:** **Examples:**
```elisp ```elisp
;; Simple usage - returns propertized string (tp-match-reset "TODO" '(face warning))
(tp-propertize "Hello" 'face 'bold) ;; Replaces ALL properties on matched text
;; => #("Hello" 0 5 (face bold))
;; With property list
(tp-propertize "World" '(face italic help-echo "greeting"))
;; Apply to substring
(tp-propertize "Hello World" 6 11 'face 'underline)
``` ```
--- ---
#### `tp-match-add` - Match and Add
Add/merge properties on matches with deep merge support.
```elisp
(tp-match-add PATTERN '(PROPERTY VALUE ...) &optional OBJECT)
```
**Examples:**
```elisp
(tp-match-add "TODO" '(face (:underline t)))
;; Merges with existing properties
```
---
#### `tp-regexp` - Match Regexp
```elisp
;; Buffer
(tp-regexp PATTERN '(PROPERTY VALUE ...))
;; String or Buffer object
(tp-regexp PATTERN OBJECT '(PROPERTY VALUE ...))
```
Set properties on all matches of a regular expression.
**Examples:**
```elisp
;; Highlight all numbers in buffer
(tp-regexp "[0-9]+" '(face font-lock-number-face))
;; On string
(tp-regexp "[A-Z]+" "Hello WORLD" '(face bold))
;; => #("Hello WORLD" 6 11 (face bold))
```
---
#### `tp-regexp-reset` - Regexp and Reset
Reset (completely replace) all properties on regexp matches.
```elisp
(tp-regexp-reset PATTERN '(PROPERTY VALUE ...) &optional OBJECT)
```
---
#### `tp-regexp-add` - Regexp and Add
Add/merge properties on regexp matches with deep merge support.
```elisp
(tp-regexp-add PATTERN '(PROPERTY VALUE ...) &optional OBJECT)
```
---
### Propertize Functions
#### `tp-layer-propertize` - Apply Layer to Object #### `tp-layer-propertize` - Apply Layer to Object
```elisp ```elisp
@ -356,59 +593,6 @@ Apply all layers from a layer group to an object.
--- ---
### Pattern Matching Functions
#### `tp-match` - Match String
```elisp
;; Buffer
(tp-match PATTERN PROPERTY VALUE ...)
;; String or Buffer object
(tp-match PATTERN OBJECT PROPERTY VALUE ...)
```
Set properties on all occurrences of a string pattern.
**Examples:**
```elisp
;; In buffer - returns list of (START . END) pairs
(tp-match "TODO" 'face 'warning)
;; => ((10 . 14) (50 . 54) ...)
;; On string - returns modified string
(tp-match "o" "Hello World" 'face 'bold)
;; => #("Hello World" 4 5 (face bold) 7 8 (face bold))
```
---
#### `tp-regexp` - Match Regexp
```elisp
;; Buffer
(tp-regexp PATTERN PROPERTY VALUE ...)
;; String or Buffer object
(tp-regexp PATTERN OBJECT PROPERTY VALUE ...)
```
Set properties on all matches of a regular expression.
**Examples:**
```elisp
;; Highlight all numbers in buffer
(tp-regexp "[0-9]+" 'face 'font-lock-number-face)
;; On string
(tp-regexp "[A-Z]+" "Hello WORLD" 'face 'bold)
;; => #("Hello WORLD" 6 11 (face bold))
```
---
### Search & Navigation Functions ### Search & Navigation Functions
#### `tp-forward` / `tp-backward` #### `tp-forward` / `tp-backward`
@ -845,13 +1029,19 @@ For convenience, tp.el provides these aliases:
| Alias | Original Function | | Alias | Original Function |
|-------|-------------------| |-------|-------------------|
| `tp-set` | `tp-put` | | `tp-put` | `tp-set` |
| `tp-layer-properties` | `tp-layer-props` | | `tp-layer-properties` | `tp-layer-props` |
| `tp-layer-group-define` | `tp-group-define` | | `tp-layer-group-define` | `tp-group-define` |
| `tp-layer-group-properties` | `tp-group-props` | | `tp-layer-group-properties` | `tp-group-props` |
| `tp-layer-group-propertize` | `tp-group-propertize` | | `tp-layer-group-propertize` | `tp-group-propertize` |
| `tp-layer-group-undefine` | `tp-group-undefine` | | `tp-layer-group-undefine` | `tp-group-undefine` |
### Deprecated Functions
| Function | Replacement | Notes |
|----------|-------------|-------|
| `tp-propertize` | `tp-set` | Use `tp-set` for new code |
--- ---
## License ## License

394
README_CN.md
View File

@ -22,11 +22,13 @@
## 功能特性 ## 功能特性
- ✅ **统一对象支持**：`tp-put`、`tp-match`、`tp-regexp` 等函数同时支持字符串和缓冲区 - ✅ **统一对象支持**：`tp-set`、`tp-match`、`tp-regexp` 等函数同时支持字符串和缓冲区
- ✅ **清晰语义**：`tp-reset`（替换全部）、`tp-set`（替换指定）、`tp-add`（深度合并）
- ✅ **嵌套属性访问**：使用路径语法获取/设置/移除嵌套子属性
- ✅ **创新图层系统**：堆叠、轮换和管理多层属性 - ✅ **创新图层系统**：堆叠、轮换和管理多层属性
- ✅ **图层组**：定义可复用的相关图层集合 - ✅ **图层组**：定义可复用的相关图层集合
- ✅ **搜索和导航**：查找并导航带属性的文本 - ✅ **搜索和导航**：查找并导航带属性的文本
- ✅ **模式匹配**：将属性应用到字符串/正则匹配 - ✅ **模式匹配**：将属性应用到字符串/正则匹配，支持 reset/add 变体
- ✅ **简洁 API**：一致的命名和调用约定 - ✅ **简洁 API**：一致的命名和调用约定
## 系统要求 ## 系统要求
@ -55,28 +57,58 @@
### 设置属性 ### 设置属性
tp.el 提供三个主要的属性设置函数，每个有不同的语义：
```elisp
;; tp-set: 只替换指定的属性，保留其他属性
(tp-set 1 10 '(face bold help-echo "Hello!"))
;; tp-reset: 完全替换所有属性
(tp-reset 1 10 '(face bold)) ; 其他任何属性都会被移除
;; tp-add: 深度合并嵌套属性
(tp-add 1 10 '(face (:underline t))) ; 与现有 face 合并
```
这三个函数都支持四种调用约定：
```elisp ```elisp
;; 在当前缓冲区（属性作为列表） ;; 在当前缓冲区（属性作为列表）
(tp-put 1 10 '(face bold help-echo "Hello!")) (tp-set 1 10 '(face bold help-echo "Hello!"))
;; 在特定缓冲区 ;; 在特定缓冲区
(tp-put 1 10 '(face bold) some-buffer) (tp-set 1 10 '(face bold) some-buffer)
;; 在字符串上（0 索引） ;; 在字符串上（0 索引）
(tp-put 0 5 '(face bold) "Hello World") (tp-set 0 5 '(face bold) "Hello World")
;; => #("Hello World" 0 5 (face bold)) ;; => #("Hello World" 0 5 (face bold))
;; 在整个字符串上（平铺属性） ;; 在整个字符串上（平铺属性）
(tp-put "Hello World" 'face 'bold 'help-echo "test") (tp-set "Hello World" 'face 'bold 'help-echo "test")
;; => #("Hello World" 0 11 (face bold help-echo "test")) ;; => #("Hello World" 0 11 (face bold help-echo "test"))
``` ```
### 单属性设置器
```elisp
;; 只设置 face 属性
(tp-set-face 1 10 'bold)
(tp-set-face "Hello" 'italic) ; 整个字符串
;; 只设置 display 属性
(tp-set-display 1 10 '(space :width 10))
```
### 获取属性 ### 获取属性
```elisp ```elisp
;; 获取特定位置的属性 ;; 获取特定位置的属性
(tp-get 5 'face) ; => bold (tp-get 5 'face) ; => bold
;; 获取嵌套子属性
(tp-get 5 'face :foreground) ; => "red"
(tp-get 5 'face :box :color) ; => "blue"（深度嵌套）
;; 获取范围内的特定属性 ;; 获取范围内的特定属性
(tp-get 1 10 'face) ; => bold (tp-get 1 10 'face) ; => bold
@ -87,31 +119,44 @@
(tp-at 5) ; => (face bold help-echo "Hello!") (tp-at 5) ; => (face bold help-echo "Hello!")
``` ```
### 细粒度属性操作 ### 移除属性
```elisp ```elisp
;; 获取 face 的子属性 ;; 移除整个属性
(tp-get-sub 1 'face :foreground) ; => "red" (tp-remove 1 10 'face)
;; 设置 face 的子属性 ;; 移除子属性
(tp-put-sub 1 6 'face :foreground "blue") (tp-remove 1 10 '(face :underline))
;; 移除 face 的子属性 ;; 移除嵌套子属性（保留其他）
(tp-remove-sub 1 6 'face :foreground) (tp-remove 1 10 '(face :underline (:style :position)))
;; 从 :underline 中移除 :style 和 :position，如果存在 :color 则保留
``` ```
### 模式匹配 ### 模式匹配
```elisp ```elisp
;; 将属性应用到缓冲区中所有 "TODO" 出现的位置 ;; 将属性应用到缓冲区中所有 "TODO" 出现的位置
(tp-match "TODO" 'face 'warning) (tp-match "TODO" '(face warning))
;; 应用到字符串 ;; 应用到字符串
(tp-match "world" "Hello world world" 'face 'bold) (tp-match "world" "Hello world world" '(face bold))
;; => #("Hello world world" 6 11 (face bold) 12 17 (face bold)) ;; => #("Hello world world" 6 11 (face bold) 12 17 (face bold))
;; 使用 (PATTERN STRING) 格式匹配
(tp-match '("world" "Hello world") '(face bold))
;; => #("Hello world" 6 11 (face bold))
;; 使用正则表达式 ;; 使用正则表达式
(tp-regexp "\\b[0-9]+\\b" 'face 'font-lock-number-face) (tp-regexp "\\b[0-9]+\\b" '(face font-lock-number-face))
;; reset 变体（替换匹配处的所有属性）
(tp-match-reset "TODO" '(face warning))
(tp-regexp-reset "[0-9]+" '(face bold))
;; add 变体（深度合并匹配处的属性）
(tp-match-add "TODO" '(face (:underline t)))
(tp-regexp-add "[0-9]+" '(face (:weight bold)))
``` ```
--- ---
@ -120,53 +165,137 @@
### 核心属性函数 ### 核心属性函数
#### `tp-put` - 设置文本属性 #### `tp-set` - 设置文本属性
在字符串或缓冲区区域上设置文本属性。 在字符串或缓冲区区域上设置文本属性。只替换指定的属性，保留其他属性。
```elisp ```elisp
;; 当前缓冲区（属性作为列表） ;; 当前缓冲区（属性作为列表）
(tp-put START END '(PROPERTY VALUE ...)) (tp-set START END '(PROPERTY VALUE ...))
;; 特定缓冲区或字符串 ;; 特定缓冲区或字符串
(tp-put START END '(PROPERTY VALUE ...) OBJECT) (tp-set START END '(PROPERTY VALUE ...) OBJECT)
;; 整个字符串（平铺属性） ;; 整个字符串（平铺属性）
(tp-put STRING PROPERTY VALUE ...) (tp-set STRING PROPERTY VALUE ...)
``` ```
**示例：** **示例：**
```elisp ```elisp
;; 在缓冲区区域设置 face ;; 在缓冲区区域设置 face
(tp-put 1 10 '(face bold)) ; => (1 . 10) (tp-set 1 10 '(face bold)) ; => (1 . 10)
;; 设置多个属性 ;; 设置多个属性
(tp-put 1 10 '(face bold help-echo "Click me")) (tp-set 1 10 '(face bold help-echo "Click me"))
;; 在特定缓冲区设置 ;; 在特定缓冲区设置
(tp-put 1 10 '(face italic) my-buffer) (tp-set 1 10 '(face italic) my-buffer)
;; 在字符串上设置属性（0 索引） ;; 在字符串上设置属性（0 索引）
(setq my-string (tp-put 0 5 '(face italic) "Hello World")) (setq my-string (tp-set 0 5 '(face italic) "Hello World"))
;; => #("Hello World" 0 5 (face italic)) ;; => #("Hello World" 0 5 (face italic))
;; 在整个字符串上设置属性 ;; 在整个字符串上设置属性
(tp-put "Hello" 'face 'bold 'mouse-face 'highlight) (tp-set "Hello" 'face 'bold 'mouse-face 'highlight)
;; => #("Hello" 0 5 (face bold mouse-face highlight)) ;; => #("Hello" 0 5 (face bold mouse-face highlight))
``` ```
--- ---
#### `tp-reset` - 替换所有属性
用指定的属性完全替换所有文本属性。
```elisp
(tp-reset START END '(PROPERTY VALUE ...) &optional OBJECT)
(tp-reset STRING PROPERTY VALUE ...)
```
**示例：**
```elisp
;; 替换区域中的所有属性
(tp-reset 1 10 '(face bold)) ; 任何现有属性都会被移除
;; 在字符串上
(tp-reset "Hello" 'face 'italic)
```
---
#### `tp-add` - 添加/合并属性
添加或更新属性，支持嵌套属性列表的深度合并。
```elisp
(tp-add START END '(PROPERTY VALUE ...) &optional OBJECT)
(tp-add STRING PROPERTY VALUE ...)
```
**示例：**
```elisp
;; 添加属性（保留现有，合并嵌套）
(tp-add 1 10 '(help-echo "tooltip"))
;; 深度合并 face 属性
(tp-set 1 10 '(face (:foreground "red")))
(tp-add 1 10 '(face (:background "blue")))
;; 结果: face 是 (:foreground "red" :background "blue")
```
---
#### `tp-set-face` - 设置 Face 属性
只设置 face 属性，保留其他属性。
```elisp
(tp-set-face START END FACE &optional OBJECT)
(tp-set-face STRING FACE)
```
**示例：**
```elisp
(tp-set-face 1 10 'bold)
(tp-set-face 1 10 '(:foreground "red" :weight bold))
(tp-set-face "Hello" 'italic)
```
---
#### `tp-set-display` - 设置 Display 属性
只设置 display 属性，保留其他属性。
```elisp
(tp-set-display START END DISPLAY &optional OBJECT)
(tp-set-display STRING DISPLAY)
```
**示例：**
```elisp
(tp-set-display 1 10 '(space :width 10))
(tp-set-display " " '(space :width 20))
```
---
#### `tp-get` - 获取属性值 #### `tp-get` - 获取属性值
从位置或范围获取属性值。 从位置或范围获取属性值，支持嵌套子属性访问。
```elisp ```elisp
;; 单个位置 ;; 单个位置
(tp-get POSITION PROPERTY) (tp-get POSITION PROPERTY)
(tp-get POSITION PROPERTY OBJECT) (tp-get POSITION PROPERTY OBJECT)
;; 嵌套子属性访问
(tp-get POSITION PROPERTY SUB-KEY ...)
;; 范围 - 特定属性 ;; 范围 - 特定属性
(tp-get START END PROPERTY) (tp-get START END PROPERTY)
(tp-get START END PROPERTY OBJECT) (tp-get START END PROPERTY OBJECT)
@ -182,6 +311,11 @@
;; 从当前缓冲区获取 ;; 从当前缓冲区获取
(tp-get 5 'face) ; => bold (tp-get 5 'face) ; => bold
;; 获取嵌套子属性
(tp-get 5 'face :foreground) ; => "red"
(tp-get 5 'face :box :color) ; => "blue"
(tp-get 5 'display :width) ; => 10
;; 从字符串获取（0 索引） ;; 从字符串获取（0 索引）
(tp-get 0 'face my-string) ; => italic (tp-get 0 'face my-string) ; => italic
@ -243,16 +377,32 @@
#### `tp-remove` - 移除属性 #### `tp-remove` - 移除属性
```elisp 从区域中移除属性或嵌套子属性。
(tp-remove START END PROPERTY &optional OBJECT)
```
从区域中移除特定属性。 ```elisp
;; 移除整个属性
(tp-remove START END PROPERTY &optional OBJECT)
;; 移除子属性
(tp-remove START END '(PROPERTY SUB-KEY) &optional OBJECT)
;; 移除嵌套子属性
(tp-remove START END '(PROPERTY SUB-KEY (NESTED-KEYS...)) &optional OBJECT)
```
**示例：** **示例：**
```elisp ```elisp
(tp-remove 1 10 'face) ; 移除 face 属性 ;; 移除整个属性
(tp-remove 1 10 'face)
;; 从 face 移除子属性
(tp-remove 1 10 '(face :underline))
;; 移除特定嵌套键，保留其他
(tp-remove 1 10 '(face :underline (:style :position)))
;; 从 :underline 移除 :style 和 :position
;; 如果 :underline 中存在 :color，则保留
``` ```
--- ---
@ -290,35 +440,122 @@
--- ---
### 属性化函数 ### 模式匹配函数
#### `tp-propertize` - 创建带属性的字符串 #### `tp-match` - 匹配字符串
```elisp ```elisp
;; 创建带属性的字符串 ;; 缓冲区
(tp-propertize STRING PROPERTY VALUE ...) (tp-match PATTERN '(PROPERTY VALUE ...))
(tp-propertize STRING '(PROPERTY VALUE ...))
;; 应用到对象的区域 ;; 字符串或缓冲区对象
(tp-propertize OBJECT START END PROPERTY VALUE ...) (tp-match PATTERN OBJECT '(PROPERTY VALUE ...))
;; 使用 (PATTERN STRING) 格式
(tp-match '(PATTERN STRING) '(PROPERTY VALUE ...))
```
在所有字符串模式匹配处设置属性。
**示例：**
```elisp
;; 在缓冲区中 - 返回 (START . END) 对的列表
(tp-match "TODO" '(face warning))
;; => ((10 . 14) (50 . 54) ...)
;; 在字符串上 - 返回修改后的字符串
(tp-match "o" "Hello World" '(face bold))
;; => #("Hello World" 4 5 (face bold) 7 8 (face bold))
;; 使用 (PATTERN STRING) 格式
(tp-match '("world" "Hello world") '(face bold))
;; => #("Hello world" 6 11 (face bold))
```
---
#### `tp-match-reset` - 匹配并重置
重置（完全替换）匹配处的所有属性。
```elisp
(tp-match-reset PATTERN '(PROPERTY VALUE ...) &optional OBJECT)
``` ```
**示例：** **示例：**
```elisp ```elisp
;; 简单用法 - 返回带属性的字符串 (tp-match-reset "TODO" '(face warning))
(tp-propertize "Hello" 'face 'bold) ;; 替换匹配文本上的所有属性
;; => #("Hello" 0 5 (face bold))
;; 使用属性列表
(tp-propertize "World" '(face italic help-echo "greeting"))
;; 应用到子字符串
(tp-propertize "Hello World" 6 11 'face 'underline)
``` ```
--- ---
#### `tp-match-add` - 匹配并添加
在匹配处添加/合并属性，支持深度合并。
```elisp
(tp-match-add PATTERN '(PROPERTY VALUE ...) &optional OBJECT)
```
**示例：**
```elisp
(tp-match-add "TODO" '(face (:underline t)))
;; 与现有属性合并
```
---
#### `tp-regexp` - 匹配正则表达式
```elisp
;; 缓冲区
(tp-regexp PATTERN '(PROPERTY VALUE ...))
;; 字符串或缓冲区对象
(tp-regexp PATTERN OBJECT '(PROPERTY VALUE ...))
```
在所有正则表达式匹配处设置属性。
**示例：**
```elisp
;; 高亮缓冲区中的所有数字
(tp-regexp "[0-9]+" '(face font-lock-number-face))
;; 在字符串上
(tp-regexp "[A-Z]+" "Hello WORLD" '(face bold))
;; => #("Hello WORLD" 6 11 (face bold))
```
---
#### `tp-regexp-reset` - 正则匹配并重置
重置（完全替换）正则匹配处的所有属性。
```elisp
(tp-regexp-reset PATTERN '(PROPERTY VALUE ...) &optional OBJECT)
```
---
#### `tp-regexp-add` - 正则匹配并添加
在正则匹配处添加/合并属性，支持深度合并。
```elisp
(tp-regexp-add PATTERN '(PROPERTY VALUE ...) &optional OBJECT)
```
---
### 属性化函数
#### `tp-layer-propertize` - 将图层应用到对象 #### `tp-layer-propertize` - 将图层应用到对象
```elisp ```elisp
@ -355,59 +592,6 @@
--- ---
### 模式匹配函数
#### `tp-match` - 匹配字符串
```elisp
;; 缓冲区
(tp-match PATTERN PROPERTY VALUE ...)
;; 字符串或缓冲区对象
(tp-match PATTERN OBJECT PROPERTY VALUE ...)
```
在所有字符串模式匹配处设置属性。
**示例：**
```elisp
;; 在缓冲区中 - 返回 (START . END) 对的列表
(tp-match "TODO" 'face 'warning)
;; => ((10 . 14) (50 . 54) ...)
;; 在字符串上 - 返回修改后的字符串
(tp-match "o" "Hello World" 'face 'bold)
;; => #("Hello World" 4 5 (face bold) 7 8 (face bold))
```
---
#### `tp-regexp` - 匹配正则表达式
```elisp
;; 缓冲区
(tp-regexp PATTERN PROPERTY VALUE ...)
;; 字符串或缓冲区对象
(tp-regexp PATTERN OBJECT PROPERTY VALUE ...)
```
在所有正则表达式匹配处设置属性。
**示例：**
```elisp
;; 高亮缓冲区中的所有数字
(tp-regexp "[0-9]+" 'face 'font-lock-number-face)
;; 在字符串上
(tp-regexp "[A-Z]+" "Hello WORLD" 'face 'bold)
;; => #("Hello WORLD" 6 11 (face bold))
```
---
### 搜索和导航函数 ### 搜索和导航函数
#### `tp-forward` / `tp-backward` #### `tp-forward` / `tp-backward`
@ -844,13 +1028,19 @@
| 别名 | 原函数 | | 别名 | 原函数 |
|------|--------| |------|--------|
| `tp-set` | `tp-put` | | `tp-put` | `tp-set` |
| `tp-layer-properties` | `tp-layer-props` | | `tp-layer-properties` | `tp-layer-props` |
| `tp-layer-group-define` | `tp-group-define` | | `tp-layer-group-define` | `tp-group-define` |
| `tp-layer-group-properties` | `tp-group-props` | | `tp-layer-group-properties` | `tp-group-props` |
| `tp-layer-group-propertize` | `tp-group-propertize` | | `tp-layer-group-propertize` | `tp-group-propertize` |
| `tp-layer-group-undefine` | `tp-group-undefine` | | `tp-layer-group-undefine` | `tp-group-undefine` |
### 已弃用函数
| 函数 | 替代 | 说明 |
|------|------|------|
| `tp-propertize` | `tp-set` | 新代码请使用 `tp-set` |
--- ---
## 许可证 ## 许可证