From ec5fa62ebded07c0db1df0b97ae18db12336a406 Mon Sep 17 00:00:00 2001 From: Kinneyzhang Date: Mon, 15 Dec 2025 20:15:18 +0800 Subject: [PATCH] update readme --- README.md | 95 ++++------------------------------------------------ README_CN.md | 92 +++++--------------------------------------------- 2 files changed, 15 insertions(+), 172 deletions(-) diff --git a/README.md b/README.md index a4703ab..c7079e1 100644 --- a/README.md +++ b/README.md @@ -31,11 +31,11 @@ Inspired by [ov.el](https://github.com/emacsorphanage/ov) for overlays, tp.el in ## Features -### Layer 1: Unified API Parameter Conventions +### Unified API Parameter Conventions Native Emacs APIs have different functions and parameter orders for strings and buffers. tp.el unifies all of this: -- ✅ **Four Calling Conventions**: All core functions (`tp-set`, `tp-get`, `tp-match`, etc.) support four flexible calling patterns: +- ✅ **Three Calling Conventions**: All core functions (`tp-set`, `tp-get`, `tp-remove`, etc.) support three flexible calling patterns: ```elisp ;; 1. Current buffer (tp-set START END '(face bold)) @@ -43,12 +43,10 @@ Native Emacs APIs have different functions and parameter orders for strings and (tp-set START END '(face bold) OBJECT) ;; 3. Entire string (flat properties) (tp-set STRING 'face 'bold 'help-echo "tip") - ;; 4. Support (PATTERN STRING) format - (tp-match '("world" "Hello world") '(face bold)) ``` - ✅ **Unified Object Support**: The same function works with both strings and buffers, no need to remember different APIs -### Layer 2: Three Property Operation Semantics +### Three Property Operation Semantics Native APIs only have simple set and get. tp.el provides three clear operation semantics: @@ -64,7 +62,7 @@ Native APIs only have simple set and get. tp.el provides three clear operation s ;; Native API would completely overwrite, but tp-add merges intelligently ``` -### Layer 3: Fine-grained Sub-property Operations +### Fine-grained Sub-property Operations **This is functionality that native APIs completely lack**. tp.el supports fine-grained reading, modification, and deletion of nested properties: @@ -86,7 +84,7 @@ Native APIs only have simple set and get. tp.el provides three clear operation s - ✅ **Deep Merge**: `tp-add` recursively merges nested plist structures - ✅ **Smart Face Merging**: Symbol faces are automatically prepended to face lists, plist faces are deep merged -### Layer 4: Innovative Property Layer System +### Innovative Property Layer System **This is tp.el's most innovative feature**, completely unsupported by native Emacs. The property layer system allows stacking multiple sets of properties on the same text region: @@ -112,7 +110,7 @@ Native APIs only have simple set and get. tp.el provides three clear operation s (tp-rotate-layer 1 10) ; highlight is now visible ``` -### Layer 5: Pattern Matching & Batch Operations +### Pattern Matching & Batch Operations Native APIs require manual searching and looping. tp.el provides convenient pattern matching functionality: @@ -131,7 +129,7 @@ Native APIs require manual searching and looping. tp.el provides convenient patt (tp-match-add "TODO" '(face (:underline t))) ``` -### Layer 6: Enhanced Search & Navigation +### Enhanced Search & Navigation - ✅ **Range Search**: `tp-search` returns a list of all matching intervals - ✅ **N-times Search**: `tp-forward`/`tp-backward` support searching forward/backward N times @@ -146,12 +144,6 @@ Native APIs require manual searching and looping. tp.el provides convenient patt (tp-search-map #'upcase my-string 'marker) ``` -### Layer 7: Query & Diagnostics - -- ✅ **Interval Query**: `tp-intervals` gets all property intervals -- ✅ **Empty Check**: `tp-empty-p` checks if there are any properties -- ✅ **Property Merge**: `tp-plist` gets merged property list of the region - ## Requirements - **Emacs 28.1+** (uses `object-intervals` function) @@ -215,13 +207,6 @@ A complete overview of all tp.el functions organized by category: | [`tp-search`](#tp-search---search-all-matches) | Search all matching properties in range or string | | [`tp-search-map`](#tp-search-map---apply-function-to-matched-text) | Apply function to matched text for all matches | -#### Query Functions -| Function | Description | -|----------|-------------| -| [`tp-intervals`](#tp-intervals---get-property-intervals) | Get property intervals in a region | -| [`tp-empty-p`](#tp-empty-p---check-for-properties) | Check if object has no properties | -| [`tp-plist`](#tp-plist---get-merged-properties) | Get merged plist of all properties | - #### Property Layer Definition Functions | Function | Description | |----------|-------------| @@ -855,72 +840,6 @@ Apply FUNCTION to matched text for all matches of PROPERTY. --- -### Query Functions - -#### `tp-intervals` - Get Property Intervals - -```elisp -(tp-intervals START END &optional OBJECT) -``` - -Get all text property intervals in a region. - ---- - -#### `tp-empty-p` - Check for 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. - -**Examples:** - -```elisp -;; Check current buffer -(tp-empty-p) -(tp-empty-p nil) - -;; Check specific string -(tp-empty-p "plain string") ; => t -(tp-empty-p (propertize "styled" 'face 'bold)) ; => nil - -;; Check specific buffer -(tp-empty-p my-buffer) -``` - ---- - -#### `tp-plist` - Get Merged Properties - -```elisp -;; Buffer/string region -(tp-plist START END &optional OBJECT) - -;; Entire string -(tp-plist STRING) -``` - -Get a merged plist of all properties in a region or entire string. - -**Examples:** - -```elisp -;; Get properties from buffer region -(tp-plist 1 10) - -;; Get properties from string region -(tp-plist 0 5 my-string) - -;; Get properties from entire string -(tp-plist my-string) -``` - ---- - ## The Property Layer System The **property layer system** is tp.el's innovative feature that allows stacking multiple sets of properties on the same text region. Only the **top layer** is visible, but lower layers are preserved and can be revealed through rotation or pinning. diff --git a/README_CN.md b/README_CN.md index 17c6031..e88c858 100644 --- a/README_CN.md +++ b/README_CN.md @@ -30,11 +30,11 @@ ## 功能特性 -### 第一层：统一的 API 参数规范 +### 统一的 API 参数规范 原生 Emacs API 针对字符串和缓冲区有不同的函数和参数顺序，tp.el 统一了这一切： -- ✅ **四种调用约定**：所有核心函数（`tp-set`、`tp-get`、`tp-match` 等）支持四种灵活的调用方式： +- ✅ **三种调用约定**：所有核心函数（`tp-set`、`tp-get`、`tp-remove` 等）支持三种灵活的调用方式： ```elisp ;; 1. 当前缓冲区 (tp-set START END '(face bold)) @@ -42,12 +42,10 @@ (tp-set START END '(face bold) OBJECT) ;; 3. 整个字符串（平铺属性） (tp-set STRING 'face 'bold 'help-echo "tip") - ;; 4. 支持 (PATTERN STRING) 格式 - (tp-match '("world" "Hello world") '(face bold)) ``` - ✅ **统一对象支持**：同一个函数同时支持字符串和缓冲区，无需记忆不同的 API -### 第二层：三种属性操作语义 +### 三种属性操作语义 原生 API 只有简单的设置和获取，tp.el 提供了三种清晰的操作语义： @@ -63,7 +61,7 @@ ;; 原生 API 会完全覆盖，而 tp-add 会智能合并 ``` -### 第三层：子属性的精细操作 +### 子属性的精细操作 **这是原生 API 完全不具备的功能**。tp.el 支持对嵌套属性进行精细的读取、修改和删除： @@ -85,7 +83,7 @@ - ✅ **深度合并**：`tp-add` 递归合并嵌套的 plist 结构 - ✅ **Face 智能合并**：符号 face 自动前置到 face 列表，plist face 深度合并 -### 第四层：创新的属性层系统 +### 创新的属性层系统 **这是 tp.el 最具创新性的功能**，原生 Emacs 完全不支持。属性层系统允许在同一文本区域上堆叠多组属性： @@ -111,7 +109,7 @@ (tp-rotate-layer 1 10) ; highlight 现在可见 ``` -### 第五层：模式匹配与批量操作 +### 模式匹配与批量操作 原生 API 需要手动搜索和循环，tp.el 提供了便捷的模式匹配功能： @@ -130,7 +128,7 @@ (tp-match-add "TODO" '(face (:underline t))) ``` -### 第六层：增强的搜索与导航 +### 增强的搜索与导航 - ✅ **范围搜索**：`tp-search` 返回所有匹配区间的列表 - ✅ **N次搜索**：`tp-forward`/`tp-backward` 支持向前/向后搜索N次 @@ -145,12 +143,6 @@ (tp-search-map #'upcase my-string 'marker) ``` -### 第七层：查询与诊断 - -- ✅ **区间查询**：`tp-intervals` 获取所有属性区间 -- ✅ **空检查**：`tp-empty-p` 检查是否有属性 -- ✅ **属性合并**：`tp-plist` 获取区域内所有属性的合并列表 - ## 系统要求 - **Emacs 28.1+**（使用 `object-intervals` 函数） @@ -851,79 +843,12 @@ Emacs 的 `text-property-search-forward` 和 `text-property-search-backward` 的 --- -### 查询函数 - -#### `tp-intervals` - 获取属性区间 - -```elisp -(tp-intervals START END &optional OBJECT) -``` - -获取区域中所有文本属性区间。 - ---- - -#### `tp-empty-p` - 检查属性 - -```elisp -(tp-empty-p &optional OBJECT) -``` - -如果 OBJECT 没有文本属性则返回 t。 - -- **OBJECT** 可以是字符串或缓冲区；nil 默认为当前缓冲区。 - -**示例：** - -```elisp -;; 检查当前缓冲区 -(tp-empty-p) -(tp-empty-p nil) - -;; 检查特定字符串 -(tp-empty-p "plain string") ; => t -(tp-empty-p (propertize "styled" 'face 'bold)) ; => nil - -;; 检查特定缓冲区 -(tp-empty-p my-buffer) -``` - ---- - -#### `tp-plist` - 获取合并的属性 - -```elisp -;; 缓冲区/字符串区域 -(tp-plist START END &optional OBJECT) - -;; 整个字符串 -(tp-plist STRING) -``` - -获取区域或整个字符串中所有属性的合并属性列表。 - -**示例：** - -```elisp -;; 从缓冲区区域获取属性 -(tp-plist 1 10) - -;; 从字符串区域获取属性 -(tp-plist 0 5 my-string) - -;; 从整个字符串获取属性 -(tp-plist my-string) -``` - ---- - ## 属性层系统 -**属性层系统**是 tp.el 的创新功能，允许在同一文本区域上堆叠多组属性。只有**顶层**可见，但下层会被保留，可以通过轮换或置顶来显示。 +属性层系统是 tp.el 的创新功能，允许在同一文本区域堆叠多组属性。只有顶层属性可见，但下层属性会被保留，并可通过轮转或固定操作使其显现。 ### 属性层概念 -``` ┌─────────────────────────────┐ │ 顶层（可见） │ ← idx=0，你看到的 ├─────────────────────────────┤ @@ -931,7 +856,6 @@ Emacs 的 `text-property-search-forward` 和 `text-property-search-backward` 的 ├─────────────────────────────┤ │ 底层（隐藏） │ ← idx=-1，被保留 └─────────────────────────────┘ -``` ### 属性层定义