# tp.el - Emacs 文本属性操作库

<p align="center">
  <strong>一个功能强大的文本属性操作库，具有创新的图层系统</strong>
</p>

<p align="center">
  <a href="#功能特性">功能特性</a> •
  <a href="#安装">安装</a> •
  <a href="#快速开始">快速开始</a> •
  <a href="#api-参考">API 参考</a> •
  <a href="#图层系统">图层系统</a>
</p>

---

**tp.el** 提供了一个便捷统一的 API 来操作 Emacs 文本属性。灵感来自用于叠加层的 [ov.el](https://github.com/emacsorphanage/ov)，tp.el 提供：

- **统一 API**：所有属性设置函数同时支持 **字符串** 和 **缓冲区**
- **图层系统**：在同一文本区域上堆叠多组属性
- **模式匹配**：将属性应用到匹配字符串或正则表达式的文本

## 功能特性

- ✅ **统一对象支持**：`tp-put`、`tp-match`、`tp-regexp` 等函数同时支持字符串和缓冲区
- ✅ **创新图层系统**：堆叠、轮换和管理多层属性
- ✅ **图层组**：定义可复用的相关图层集合
- ✅ **搜索和导航**：查找并导航带属性的文本
- ✅ **模式匹配**：将属性应用到字符串/正则匹配
- ✅ **简洁 API**：一致的命名和调用约定

## 系统要求

- **Emacs 28.1+**（使用 `object-intervals` 函数）
- **dash.el**（列表操作工具库）

## 安装

```elisp
;; 添加到 load-path
(add-to-list 'load-path "/path/to/tp")
(require 'tp)
```

或使用 `use-package`：

```elisp
(use-package tp
  :load-path "/path/to/tp")
```

---

## 快速开始

### 设置属性

```elisp
;; 在当前缓冲区
(tp-put 1 10 'face 'bold 'help-echo "Hello!")

;; 在字符串上
(tp-put "Hello World" 0 5 'face 'bold)
;; => #("Hello World" 0 5 (face bold))

;; 使用属性列表
(tp-put 1 10 '(face bold help-echo "test"))
```

### 获取属性

```elisp
;; 获取特定属性
(tp-get 5 'face)  ; => bold

;; 获取该位置的所有属性
(tp-at 5)  ; => (face bold help-echo "Hello!")
```

### 模式匹配

```elisp
;; 将属性应用到缓冲区中所有 "TODO" 出现的位置
(tp-match "TODO" 'face 'warning)

;; 应用到字符串
(tp-match "world" "Hello world world" 'face 'bold)
;; => #("Hello world world" 6 11 (face bold) 12 17 (face bold))

;; 使用正则表达式
(tp-regexp "\\b[0-9]+\\b" 'face 'font-lock-number-face)
```

---

## API 参考

### 核心属性函数

#### `tp-put` - 设置文本属性

在字符串或缓冲区区域上设置文本属性。

```elisp
;; 缓冲区（当前缓冲区）
(tp-put START END PROPERTY VALUE ...)
(tp-put START END '(PROPERTY VALUE ...))

;; 字符串或缓冲区对象
(tp-put OBJECT START END PROPERTY VALUE ...)
(tp-put OBJECT START END '(PROPERTY VALUE ...))
```

**示例：**

```elisp
;; 在缓冲区区域设置 face
(tp-put 1 10 'face 'bold)  ; => (1 . 10)

;; 设置多个属性
(tp-put 1 10 'face 'bold 'help-echo "Click me")

;; 在字符串上设置属性
(setq my-string (tp-put "Hello World" 0 5 'face 'italic))
;; => #("Hello World" 0 5 (face italic))

;; 属性作为列表
(tp-put 1 10 '(face bold mouse-face highlight))
```

---

#### `tp-get` - 获取属性值

```elisp
(tp-get POSITION PROPERTY &optional OBJECT)
```

获取 POSITION 位置的 PROPERTY 值。

**示例：**

```elisp
(tp-get 5 'face)           ; 从当前缓冲区获取
(tp-get 0 'face my-string) ; 从字符串获取
```

---

#### `tp-at` - 获取所有属性

```elisp
(tp-at &optional POINT OBJECT)
```

获取 POINT 位置的所有文本属性，返回属性列表。

**示例：**

```elisp
(tp-at 5)  ; => (face bold help-echo "test")
(tp-at 0 my-string)  ; 从字符串获取
```

---

#### `tp-remove` - 移除属性

```elisp
(tp-remove START END PROPERTY &optional OBJECT)
```

从区域中移除特定属性。

**示例：**

```elisp
(tp-remove 1 10 'face)  ; 移除 face 属性
```

---

#### `tp-remove-list` - 移除多个属性

```elisp
(tp-remove-list START END PROPERTIES &optional OBJECT)
```

一次移除多个属性。

**示例：**

```elisp
(tp-remove-list 1 10 '(face help-echo mouse-face))
```

---

#### `tp-clear` - 清除所有属性

```elisp
(tp-clear &optional START END OBJECT)
```

清除区域中的所有文本属性。

**示例：**

```elisp
(tp-clear 1 10)     ; 清除区域
(tp-clear)          ; 清除整个缓冲区
```

---

### 属性化函数

#### `tp-propertize` - 创建带属性的字符串

```elisp
;; 创建带属性的字符串
(tp-propertize STRING PROPERTY VALUE ...)
(tp-propertize STRING '(PROPERTY VALUE ...))

;; 应用到对象的区域
(tp-propertize OBJECT START END PROPERTY VALUE ...)
```

**示例：**

```elisp
;; 简单用法 - 返回带属性的字符串
(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-layer-propertize` - 将图层应用到对象

```elisp
(tp-layer-propertize OBJECT LAYER &optional START END)
```

将预定义图层的属性应用到对象。

**示例：**

```elisp
;; 首先定义一个图层
(tp-layer-define highlight '(face (:background "yellow")))

;; 应用到字符串
(tp-layer-propertize "Important" 'highlight)

;; 应用到子字符串
(tp-layer-propertize "Hello World" 'highlight 0 5)

;; 应用到缓冲区区域
(tp-layer-propertize (current-buffer) 'highlight 1 10)
```

---

#### `tp-group-propertize` - 应用图层组

```elisp
(tp-group-propertize OBJECT LAYER-GROUP &optional START END)
```

将图层组中的所有图层应用到对象。

---

### 模式匹配函数

#### `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`

```elisp
(tp-forward PROPERTY &optional VALUE PREDICATE NOT-CURRENT)
(tp-backward PROPERTY &optional VALUE PREDICATE NOT-CURRENT)
```

向前/向后搜索具有 PROPERTY 的文本。

**示例：**

```elisp
;; 查找下一个具有 'marker 属性的文本
(tp-forward 'marker)

;; 查找下一个 'type 等于 'heading 的文本
(tp-forward 'type 'heading)
```

---

#### `tp-next` / `tp-prev`

```elisp
(tp-next &optional POINT PROPERTY VALUE)
(tp-prev &optional POINT PROPERTY VALUE)
```

获取下一个/上一个具有文本属性的位置。

---

#### `tp-goto-next` / `tp-goto-prev`

```elisp
(tp-goto-next &optional PROPERTY VALUE)
(tp-goto-prev &optional PROPERTY VALUE)
```

将光标移动到下一个/上一个具有 PROPERTY 的文本。

---

#### `tp-regions-map` / `tp-strings-map`

```elisp
(tp-regions-map FUNCTION PROPERTY &optional VALUE PREDICATE COLLECT)
(tp-strings-map FUNCTION PROPERTY &optional VALUE PREDICATE COLLECT)
```

对所有具有 PROPERTY 的区域/字符串应用函数。

**示例：**

```elisp
;; 处理所有标记的文本
(tp-strings-map
 (lambda (str idx)
   (message "找到: %s，索引 %d" str idx))
 'marker)
```

---

### 查询函数

#### `tp-in` - 查找具有属性的区域

```elisp
(tp-in PROPERTY &optional VALUE START END)
```

获取当前缓冲区中所有具有 PROPERTY 的区域。

**示例：**

```elisp
;; 获取所有具有 'marker 属性的区域
(tp-in 'marker)
;; => ((1 5 (marker t ...)) (10 15 (marker t ...)))

;; 按值过滤
(tp-in 'type 'heading)
```

---

#### `tp-all` - 获取所有带属性的区域

```elisp
(tp-all &optional START END)
```

获取所有具有任何文本属性的区域。

---

#### `tp-intervals` - 获取属性区间

```elisp
(tp-intervals START END &optional OBJECT)
```

获取区域中所有文本属性区间。

---

#### `tp-empty-p` - 检查属性

```elisp
(tp-empty-p OBJECT)
```

如果 OBJECT 没有文本属性则返回 t。

---

#### `tp-plist` - 获取合并的属性

```elisp
(tp-plist START END &optional OBJECT)
```

获取区域中所有属性的合并属性列表。

---

## 图层系统

**图层系统**是 tp.el 的创新功能，允许在同一文本区域上堆叠多组属性。只有**顶层**可见，但下层会被保留，可以通过轮换或置顶来显示。

### 图层概念

```
┌─────────────────────────────┐
│   顶层（可见）              │  ← 你看到的
├─────────────────────────────┤
│   中间层（隐藏）            │  ← 被保留
├─────────────────────────────┤
│   底层（隐藏）              │  ← 被保留
└─────────────────────────────┘
```

### 图层定义函数

#### `tp-layer-define` - 定义图层

```elisp
(tp-layer-define NAME PROPERTIES)
```

定义一个带属性的命名图层。

**示例：**

```elisp
(tp-layer-define highlight
  '(face (:background "yellow" :foreground "black")))

(tp-layer-define error
  '(face (:background "red" :foreground "white")
    help-echo "错误!"))

(tp-layer-define info
  '(face (:background "blue" :foreground "white")))
```

---

#### `tp-group-define` - 定义图层组

```elisp
(tp-group-define NAME
  LAYER1 PROPERTIES1
  LAYER2 PROPERTIES2
  ...)
```

定义一组相关的图层。

**示例：**

```elisp
(tp-group-define status-colors
  status-ok      '(face (:foreground "green"))
  status-warning '(face (:foreground "orange"))
  status-error   '(face (:foreground "red")))
```

---

#### `tp-layer-props` / `tp-group-props`

```elisp
(tp-layer-props LAYER-NAME)
(tp-group-props GROUP-NAME)
```

获取图层或图层组中所有图层的属性。

---

#### `tp-layer-undefine` / `tp-group-undefine`

```elisp
(tp-layer-undefine NAME)
(tp-group-undefine NAME)
```

移除图层或图层组定义。

---

#### `tp-layer-reset`

```elisp
(tp-layer-reset)
```

清除所有图层和图层组定义。

---

### 图层操作函数

#### `tp-layer-push` - 添加图层

```elisp
(tp-layer-push START END NAME &optional OBJECT)
```

将图层推到堆栈顶部。

**示例：**

```elisp
(tp-layer-define base '(face default))
(tp-layer-define highlight '(face (:background "yellow")))

;; 首先推入 base 图层
(tp-layer-push 1 10 'base)

;; 将 highlight 推到顶部（现在可见）
(tp-layer-push 1 10 'highlight)
```

---

#### `tp-layer-delete` - 删除图层

```elisp
(tp-layer-delete START END NAME &optional OBJECT)
```

从堆栈任何位置删除图层。

**示例：**

```elisp
;; 删除 highlight 图层
(tp-layer-delete 1 10 'highlight)
;; base 图层现在可见
```

---

#### `tp-layer-rotate` - 轮换图层

```elisp
(tp-layer-rotate START END &optional OBJECT)
```

轮换图层 - 顶层移到底部，下一层变为可见。

**示例：**

```elisp
;; 堆栈: highlight (顶) -> base (底)
(tp-layer-rotate 1 10)
;; 堆栈: base (顶) -> highlight (底)
```

---

#### `tp-layer-pin` - 将图层置顶

```elisp
(tp-layer-pin START END NAME &optional OBJECT)
```

将特定图层移到顶部。

**示例：**

```elisp
;; 将 'base 设为顶层
(tp-layer-pin 1 10 'base)
```

---

#### `tp-layer-hide` / `tp-layer-show`

```elisp
(tp-layer-hide START END NAME &optional OBJECT)
(tp-layer-show START END NAME &optional OBJECT)
```

隐藏图层（移到底部）或显示图层（移到顶部）。

---

#### `tp-layer-merge`

```elisp
(tp-layer-merge START END LAYER1 LAYER2 NEW-NAME &optional OBJECT)
```

将两个图层合并为一个新图层。

---

### 图层查询函数

#### `tp-layer-list` - 列出所有图层

```elisp
(tp-layer-list START END &optional OBJECT)
```

获取区域中所有图层名称的列表。

**示例：**

```elisp
(tp-layer-list 1 10)  ; => (highlight base)
```

---

#### `tp-layer-count`

```elisp
(tp-layer-count START END &optional OBJECT)
```

计算区域中的图层数量。

---

#### `tp-layer-exists-p`

```elisp
(tp-layer-exists-p START END NAME &optional OBJECT)
```

检查区域中是否存在某图层。

---

#### `tp-layer-top`

```elisp
(tp-layer-top START END &optional OBJECT)
```

获取顶层（可见）图层的名称。

---

## 实用示例

### 多图层语法高亮

```elisp
;; 为不同高亮目的定义图层
(tp-layer-define code-base
  '(face font-lock-keyword-face))

(tp-layer-define code-error
  '(face (:underline (:color "red" :style wave))
    help-echo "语法错误"))

(tp-layer-define code-debug
  '(face (:background "dark blue")))

;; 应用基础高亮
(tp-layer-push 1 100 'code-base)

;; 在有问题的代码上添加错误高亮
(tp-layer-push 50 60 'code-error)

;; 在错误和正常视图之间切换
(defun toggle-error-view ()
  (interactive)
  (tp-layer-rotate 50 60))
```

### 状态指示器

```elisp
(tp-group-define task-status
  status-todo     '(face (:foreground "gray"))
  status-progress '(face (:foreground "yellow"))
  status-done     '(face (:foreground "green")))

;; 循环切换状态
(defun cycle-task-status ()
  (interactive)
  (tp-layer-rotate (line-beginning-position) (line-end-position)))
```

### 临时高亮

```elisp
(tp-layer-define temp-highlight
  '(face (:background "yellow")))

(defun flash-region (start end)
  "临时闪烁一个区域。"
  (tp-layer-push start end 'temp-highlight)
  (run-with-timer 0.5 nil
                  (lambda ()
                    (tp-layer-delete start end 'temp-highlight))))
```

---

## 别名

为方便使用，tp.el 提供以下别名：

| 别名 | 原函数 |
|------|--------|
| `tp-set` | `tp-put` |
| `tp-layer-properties` | `tp-layer-props` |
| `tp-layer-group-define` | `tp-group-define` |
| `tp-layer-group-properties` | `tp-group-props` |
| `tp-layer-group-propertize` | `tp-group-propertize` |
| `tp-layer-group-undefine` | `tp-group-undefine` |

---

## 许可证

GNU 通用公共许可证 v2 或更高版本。

---

## 贡献

欢迎贡献！请随时提交 issues 或 pull requests。

---

<p align="center">
  <em>tp.el - 让文本属性变得强大且易用</em>
</p>