Update docs directory to use define-tp and define-tps format
Co-authored-by: Kinneyzhang <38454496+Kinneyzhang@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
parent
7e0a8573da
commit
f9c0867d63
@ -27,7 +27,7 @@ tp.el 采用分层架构设计，每一层建立在下层功能之上：
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 第四层：响应式系统 │
|
||||
│ tp-define-layer, tp--reactive-variable-watcher, │
|
||||
│ define-tp, define-tps, tp--reactive-variable-watcher, │
|
||||
│ tp--update-layer-regions, tp--register-reactive-deps │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
@ -62,7 +62,7 @@ tp.el 采用分层架构设计，每一层建立在下层功能之上：
|
||||
|------|------|--------|
|
||||
| `tp--parse-args` | 解析灵活的函数参数格式 | tp-set, tp-reset, tp-add |
|
||||
| `tp--parse-layer-args` | 解析属性层操作的参数 | tp-put-layer 及其他层操作函数 |
|
||||
| `tp--parse-define-layer-args` | 解析 tp-define-layer 的参数 | tp-define-layer |
|
||||
| `tp--parse-define-layer-args` | 解析 define-tp 的参数 | define-tp |
|
||||
|
||||
#### 数据结构操作
|
||||
| 函数 | 描述 | 调用者 |
|
||||
@ -192,11 +192,11 @@ tp.el 采用分层架构设计，每一层建立在下层功能之上：
|
||||
| `tp--replace-reactive-text-in-buffer` | 在缓冲区中替换响应式文本 | - |
|
||||
|
||||
#### 层定义
|
||||
| 函数 | 描述 | 依赖 |
|
||||
|------|------|------|
|
||||
| `tp-define-layer` | 定义单个属性层 | tp--parse-define-layer-args, tp--collect-reactive-symbols, tp--ensure-reactive-variables, tp--register-* |
|
||||
| `tp-define-layer-group` | 定义属性层组 | tp--parse-layer-group-element, tp--define-layer-from-parsed |
|
||||
| `tp--define-layer-from-parsed` | 从解析结果定义层 | (与 tp-define-layer 类似的依赖) |
|
||||
| 函数/宏 | 描述 | 依赖 |
|
||||
|---------|------|------|
|
||||
| `define-tp` | 定义单个自定义文本属性（层）| tp--parse-define-layer-args, tp--collect-reactive-symbols, tp--ensure-reactive-variables, tp--register-* |
|
||||
| `define-tps` | 定义自定义文本属性组（层组）| tp--parse-layer-group-element, tp--define-layer-from-parsed |
|
||||
| `tp--define-layer-from-parsed` | 从解析结果定义层 | (与 define-tp 类似的依赖) |
|
||||
| `tp--set-layer-props` | 设置层属性 | - |
|
||||
| `tp--set-group-layers` | 设置组的层列表 | - |
|
||||
| `tp-layer-props` | 获取层属性 | - |
|
||||
@ -218,7 +218,7 @@ tp.el 采用分层架构设计，每一层建立在下层功能之上：
|
||||
| 变量/函数 | 描述 | 依赖 |
|
||||
|-----------|------|------|
|
||||
| `tp-layer-transforms` | 存储层转换函数的 alist | - |
|
||||
| `:transform` 选项 | 在 tp-define-layer 中指定转换函数 | tp-layer-transforms |
|
||||
| `:transform` 选项 | 在 define-tp 中指定转换函数 | tp-layer-transforms |
|
||||
|
||||
#### 调试工具
|
||||
| 变量/函数 | 描述 | 依赖 |
|
||||
@ -290,9 +290,9 @@ tp-add
|
||||
└── put-text-property (Emacs 原生)
|
||||
```
|
||||
|
||||
### tp-define-layer 调用链
|
||||
### define-tp 调用链
|
||||
```
|
||||
tp-define-layer
|
||||
define-tp
|
||||
├── tp--parse-define-layer-args
|
||||
├── tp--collect-reactive-symbols
|
||||
├── tp--unregister-reactive-deps
|
||||
|
||||
@ -66,7 +66,7 @@ When using `setq-local`, updates only affect the specific buffer.
|
||||
|
||||
```elisp
|
||||
;; Define a layer with transformation
|
||||
(tp-define-layer 'currency-display
|
||||
(define-tp currency-display ()
|
||||
:props '(face bold tp-text $amount)
|
||||
:data '((amount . "100"))
|
||||
:transform (lambda (text)
|
||||
@ -119,7 +119,7 @@ Debug log includes:
|
||||
When modifying multiple reactive variables simultaneously, use batch updates to avoid multiple buffer updates:
|
||||
|
||||
```elisp
|
||||
(tp-define-layer 'themed-text
|
||||
(define-tp themed-text ()
|
||||
:props '(face (:foreground $fg-color :background $bg-color))
|
||||
:data '((fg-color . "white") (bg-color . "black")))
|
||||
|
||||
@ -143,14 +143,14 @@ Transform functions allow processing tp-text values before display:
|
||||
|
||||
```elisp
|
||||
;; Number formatting
|
||||
(tp-define-layer 'price-display
|
||||
(define-tp price-display ()
|
||||
:props '(tp-text $price)
|
||||
:data '((price . "99.9"))
|
||||
:transform (lambda (text)
|
||||
(format "$%.2f" (string-to-number text))))
|
||||
|
||||
;; Date formatting
|
||||
(tp-define-layer 'date-display
|
||||
(define-tp date-display ()
|
||||
:props '(tp-text $timestamp)
|
||||
:data '((timestamp . "1703865600"))
|
||||
:transform (lambda (text)
|
||||
@ -158,7 +158,7 @@ Transform functions allow processing tp-text values before display:
|
||||
(seconds-to-time (string-to-number text)))))
|
||||
|
||||
;; Uppercase conversion
|
||||
(tp-define-layer 'uppercase-text
|
||||
(define-tp uppercase-text ()
|
||||
:props '(tp-text $content)
|
||||
:data '((content . "hello"))
|
||||
:transform #'upcase)
|
||||
@ -174,7 +174,7 @@ Debug mode helps developers understand the reactive update flow:
|
||||
(setq tp-debug-echo t)
|
||||
|
||||
;; Define and use a reactive layer
|
||||
(tp-define-layer 'test-layer
|
||||
(define-tp test-layer ()
|
||||
:props '(face (:foreground $my-color))
|
||||
:data '((my-color . "red")))
|
||||
|
||||
|
||||
@ -66,7 +66,7 @@
|
||||
|
||||
```elisp
|
||||
;; 定义带转换的层
|
||||
(tp-define-layer 'currency-display
|
||||
(define-tp currency-display ()
|
||||
:props '(face bold tp-text $amount)
|
||||
:data '((amount . "100"))
|
||||
:transform (lambda (text)
|
||||
@ -119,7 +119,7 @@
|
||||
当需要同时修改多个响应式变量时，使用批量更新可以避免多次缓冲区更新：
|
||||
|
||||
```elisp
|
||||
(tp-define-layer 'themed-text
|
||||
(define-tp themed-text ()
|
||||
:props '(face (:foreground $fg-color :background $bg-color))
|
||||
:data '((fg-color . "white") (bg-color . "black")))
|
||||
|
||||
@ -143,14 +143,14 @@
|
||||
|
||||
```elisp
|
||||
;; 数字格式化
|
||||
(tp-define-layer 'price-display
|
||||
(define-tp price-display ()
|
||||
:props '(tp-text $price)
|
||||
:data '((price . "99.9"))
|
||||
:transform (lambda (text)
|
||||
(format "$%.2f" (string-to-number text))))
|
||||
|
||||
;; 日期格式化
|
||||
(tp-define-layer 'date-display
|
||||
(define-tp date-display ()
|
||||
:props '(tp-text $timestamp)
|
||||
:data '((timestamp . "1703865600"))
|
||||
:transform (lambda (text)
|
||||
@ -158,7 +158,7 @@
|
||||
(seconds-to-time (string-to-number text)))))
|
||||
|
||||
;; 大写转换
|
||||
(tp-define-layer 'uppercase-text
|
||||
(define-tp uppercase-text ()
|
||||
:props '(tp-text $content)
|
||||
:data '((content . "hello"))
|
||||
:transform #'upcase)
|
||||
@ -174,7 +174,7 @@
|
||||
(setq tp-debug-echo t)
|
||||
|
||||
;; 定义和使用响应式层
|
||||
(tp-define-layer 'test-layer
|
||||
(define-tp test-layer ()
|
||||
:props '(face (:foreground $my-color))
|
||||
:data '((my-color . "red")))
|
||||
|
||||
|
||||
@ -44,7 +44,7 @@ Now let's see how the reactive approach solves these problems:
|
||||
(defvar my-color "red")
|
||||
|
||||
;; Define a reactive layer using $my-color to reference the variable
|
||||
(tp-define-layer 'my-highlight
|
||||
(define-tp my-highlight ()
|
||||
'(face (:foreground $my-color)))
|
||||
|
||||
;; Apply to text
|
||||
@ -85,7 +85,7 @@ Let's start with a simple example:
|
||||
(defvar highlight-bg "yellow")
|
||||
|
||||
;; Define a reactive layer
|
||||
(tp-define-layer 'simple-highlight
|
||||
(define-tp simple-highlight ()
|
||||
'(face (:background $highlight-bg)))
|
||||
|
||||
;; Create a test buffer and apply the layer
|
||||
@ -110,7 +110,7 @@ A layer can reference multiple reactive variables:
|
||||
(defvar underline-color "red")
|
||||
|
||||
;; Define a layer using multiple variables
|
||||
(tp-define-layer 'multi-var-layer
|
||||
(define-tp multi-var-layer ()
|
||||
'(face ( :foreground $fg-color
|
||||
:background $bg-color
|
||||
:underline (:color $underline-color))))
|
||||
@ -146,7 +146,7 @@ Main uses of `:data`:
|
||||
|
||||
```lisp
|
||||
;; Complete computed properties example
|
||||
(tp-define-layer 'computed-greeting
|
||||
(define-tp computed-greeting ()
|
||||
:props '(display $full-greeting face (:foreground $status-color))
|
||||
:data '((user-name . "John")
|
||||
(greeting-prefix . "Hello"))
|
||||
@ -186,7 +186,7 @@ Main uses of `:data`:
|
||||
|
||||
```lisp
|
||||
;; Layer with watchers
|
||||
(tp-define-layer 'watched-layer
|
||||
(define-tp watched-layer ()
|
||||
:props '(face (:foreground $status-color))
|
||||
:data '((status-color . "green"))
|
||||
:watch '((status-color
|
||||
@ -227,7 +227,7 @@ This example shows how to create an indicator that automatically changes color b
|
||||
(defvar status-text "Not Started")
|
||||
|
||||
;; Define status indicator layer
|
||||
(tp-define-layer 'status-indicator
|
||||
(define-tp status-indicator ()
|
||||
'(face (:background $status-color) display $status-text))
|
||||
|
||||
;; Define status update function
|
||||
@ -271,10 +271,10 @@ This example shows how to create a switchable theme system:
|
||||
(defvar string-color nil)
|
||||
|
||||
;; Define theme-related reactive layers
|
||||
(tp-define-layer 'themed-keyword
|
||||
(define-tp themed-keyword ()
|
||||
'(face (:foreground $keyword-color :weight bold)))
|
||||
|
||||
(tp-define-layer 'themed-string
|
||||
(define-tp themed-string ()
|
||||
'(face (:foreground $string-color)))
|
||||
|
||||
;; Define theme switching functions
|
||||
@ -314,7 +314,7 @@ This example shows how to create a switchable theme system:
|
||||
|
||||
## Anonymous Reactive Layers
|
||||
|
||||
Besides using `tp-define-layer` to define named layers, you can also use reactive variables directly in property lists. tp.el will automatically generate unique names for these anonymous layers:
|
||||
Besides using `define-tp` to define named layers, you can also use reactive variables directly in property lists. tp.el will automatically generate unique names for these anonymous layers:
|
||||
|
||||
```lisp
|
||||
(tp-layer-reset)
|
||||
@ -386,7 +386,7 @@ The real power of `tp-text` comes from combining it with reactive variables:
|
||||
(defvar my-dynamic-text "Loading...")
|
||||
|
||||
;; Define a layer containing tp-text
|
||||
(tp-define-layer 'dynamic-content
|
||||
(define-tp dynamic-content ()
|
||||
:props '(face (:foreground "blue") tp-text $my-dynamic-text))
|
||||
|
||||
;; Apply to text
|
||||
@ -409,7 +409,7 @@ The real power of `tp-text` comes from combining it with reactive variables:
|
||||
`tp-text` can be combined with `:compute` to create dynamic text derived from other variables:
|
||||
|
||||
```lisp
|
||||
(tp-define-layer 'greeting-layer
|
||||
(define-tp greeting-layer ()
|
||||
:props '(face (:foreground "green") tp-text $full-greeting)
|
||||
:data '((user-name . "Guest")
|
||||
(greeting-prefix . "Welcome"))
|
||||
@ -461,7 +461,7 @@ The `:transform` keyword allows you to register a transformation function that p
|
||||
|
||||
```lisp
|
||||
;; Number formatting
|
||||
(tp-define-layer 'price-display
|
||||
(define-tp price-display ()
|
||||
:props '(tp-text $price)
|
||||
:data '((price . "99.9"))
|
||||
:transform (lambda (text)
|
||||
@ -469,7 +469,7 @@ The `:transform` keyword allows you to register a transformation function that p
|
||||
;; 99.9 displays as $99.00
|
||||
|
||||
;; Date formatting
|
||||
(tp-define-layer 'date-display
|
||||
(define-tp date-display ()
|
||||
:props '(tp-text $timestamp)
|
||||
:data '((timestamp . "1703865600"))
|
||||
:transform (lambda (text)
|
||||
@ -477,7 +477,7 @@ The `:transform` keyword allows you to register a transformation function that p
|
||||
(seconds-to-time (string-to-number text)))))
|
||||
|
||||
;; Uppercase conversion
|
||||
(tp-define-layer 'uppercase-text
|
||||
(define-tp uppercase-text ()
|
||||
:props '(tp-text $content)
|
||||
:data '((content . "hello"))
|
||||
:transform #'upcase)
|
||||
|
||||
@ -44,7 +44,7 @@
|
||||
(defvar my-color "red")
|
||||
|
||||
;; 定义一个响应式层，使用 $my-color 引用变量
|
||||
(tp-define-layer 'my-highlight
|
||||
(define-tp my-highlight ()
|
||||
'(face (:foreground $my-color)))
|
||||
|
||||
;; 应用到文本
|
||||
@ -85,7 +85,7 @@
|
||||
(defvar highlight-bg "yellow")
|
||||
|
||||
;; 定义响应式层
|
||||
(tp-define-layer 'simple-highlight
|
||||
(define-tp simple-highlight ()
|
||||
'(face (:background $highlight-bg)))
|
||||
|
||||
;; 创建测试缓冲区并应用层
|
||||
@ -110,7 +110,7 @@
|
||||
(defvar underline-color "red")
|
||||
|
||||
;; 定义使用多个变量的层
|
||||
(tp-define-layer 'multi-var-layer
|
||||
(define-tp multi-var-layer ()
|
||||
'(face ( :foreground $fg-color
|
||||
:background $bg-color
|
||||
:underline (:color $underline-color))))
|
||||
@ -146,7 +146,7 @@ tp.el 的响应式系统借鉴了 Vue 的 API，提供了三个强大的关键
|
||||
|
||||
```lisp
|
||||
;; 完整的计算属性示例
|
||||
(tp-define-layer 'computed-greeting
|
||||
(define-tp computed-greeting ()
|
||||
:props '(display $full-greeting face (:foreground $status-color))
|
||||
:data '((user-name . "张三")
|
||||
(greeting-prefix . "你好"))
|
||||
@ -186,7 +186,7 @@ tp.el 的响应式系统借鉴了 Vue 的 API，提供了三个强大的关键
|
||||
|
||||
```lisp
|
||||
;; 带监听器的层
|
||||
(tp-define-layer 'watched-layer
|
||||
(define-tp watched-layer ()
|
||||
:props '(face (:foreground $status-color))
|
||||
:data '((status-color . "green"))
|
||||
:watch '((status-color
|
||||
@ -227,7 +227,7 @@ tp.el 的响应式系统借鉴了 Vue 的 API，提供了三个强大的关键
|
||||
(defvar status-text "未开始")
|
||||
|
||||
;; 定义状态指示器层
|
||||
(tp-define-layer 'status-indicator
|
||||
(define-tp status-indicator ()
|
||||
'(face (:background $status-color) display $status-text))
|
||||
|
||||
;; 定义状态更新函数
|
||||
@ -271,10 +271,10 @@ tp.el 的响应式系统借鉴了 Vue 的 API，提供了三个强大的关键
|
||||
(defvar string-color nil)
|
||||
|
||||
;; 定义主题相关的响应式层
|
||||
(tp-define-layer 'themed-keyword
|
||||
(define-tp themed-keyword ()
|
||||
'(face (:foreground $keyword-color :weight bold)))
|
||||
|
||||
(tp-define-layer 'themed-string
|
||||
(define-tp themed-string ()
|
||||
'(face (:foreground $string-color)))
|
||||
|
||||
;; 定义主题切换函数
|
||||
@ -314,7 +314,7 @@ tp.el 的响应式系统借鉴了 Vue 的 API，提供了三个强大的关键
|
||||
|
||||
## 匿名响应式层
|
||||
|
||||
除了使用 `tp-define-layer` 定义命名层，你还可以直接在属性列表中使用响应式变量。tp.el 会自动为这些匿名层生成唯一的名称：
|
||||
除了使用 `define-tp` 定义命名层，你还可以直接在属性列表中使用响应式变量。tp.el 会自动为这些匿名层生成唯一的名称：
|
||||
|
||||
```lisp
|
||||
(tp-layer-reset)
|
||||
@ -386,7 +386,7 @@ tp.el 的响应式系统借鉴了 Vue 的 API，提供了三个强大的关键
|
||||
(defvar my-dynamic-text "Loading...")
|
||||
|
||||
;; 定义包含 tp-text 的响应式层
|
||||
(tp-define-layer 'dynamic-content
|
||||
(define-tp dynamic-content ()
|
||||
:props '(face (:foreground "blue") tp-text $my-dynamic-text))
|
||||
|
||||
;; 应用到文本
|
||||
@ -409,7 +409,7 @@ tp.el 的响应式系统借鉴了 Vue 的 API，提供了三个强大的关键
|
||||
`tp-text` 可以与 `:compute` 结合，创建由其他变量派生的动态文本：
|
||||
|
||||
```lisp
|
||||
(tp-define-layer 'greeting-layer
|
||||
(define-tp greeting-layer ()
|
||||
:props '(face (:foreground "green") tp-text $full-greeting)
|
||||
:data '((user-name . "访客")
|
||||
(greeting-prefix . "欢迎"))
|
||||
@ -461,7 +461,7 @@ tp.el 的响应式系统借鉴了 Vue 的 API，提供了三个强大的关键
|
||||
|
||||
```lisp
|
||||
;; 数字格式化
|
||||
(tp-define-layer 'price-display
|
||||
(define-tp price-display ()
|
||||
:props '(tp-text $price)
|
||||
:data '((price . "99.9"))
|
||||
:transform (lambda (text)
|
||||
@ -469,7 +469,7 @@ tp.el 的响应式系统借鉴了 Vue 的 API，提供了三个强大的关键
|
||||
;; 99.9 显示为 $99.00
|
||||
|
||||
;; 日期格式化
|
||||
(tp-define-layer 'date-display
|
||||
(define-tp date-display ()
|
||||
:props '(tp-text $timestamp)
|
||||
:data '((timestamp . "1703865600"))
|
||||
:transform (lambda (text)
|
||||
@ -477,7 +477,7 @@ tp.el 的响应式系统借鉴了 Vue 的 API，提供了三个强大的关键
|
||||
(seconds-to-time (string-to-number text)))))
|
||||
|
||||
;; 大写转换
|
||||
(tp-define-layer 'uppercase-text
|
||||
(define-tp uppercase-text ()
|
||||
:props '(tp-text $content)
|
||||
:data '((content . "hello"))
|
||||
:transform #'upcase)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user