# tp.el - Text Properties Library for Emacs

<p align="center">
  <strong>A powerful text properties manipulation library with an innovative layer system</strong>
</p>

<p align="center">
  <a href="#features">Features</a> •
  <a href="#installation">Installation</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#api-reference">API Reference</a> •
  <a href="#the-layer-system">Layer System</a> •
  <a href="README_CN.md">中文文档</a>
</p>

---

**tp.el** provides a convenient and unified API for manipulating Emacs text properties. Inspired by [ov.el](https://github.com/emacsorphanage/ov) for overlays, tp.el offers:

- **Unified API**: All property-setting functions work on both **strings** and **buffers**
- **Layer System**: Stack multiple property sets on the same text region
- **Pattern Matching**: Apply properties to text matching strings or regexps

## Features

- ✅ **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
- ✅ **Layer Groups**: Define reusable sets of related layers
- ✅ **Search & Navigation**: Find and navigate through propertized text
- ✅ **Pattern Matching**: Apply properties to string/regexp matches with reset/add variants
- ✅ **Clean API**: Consistent naming and calling conventions

## Requirements

- **Emacs 28.1+** (uses `object-intervals` function)
- **dash.el** (list manipulation utilities)

## Installation

```elisp
;; Add to your load-path
(add-to-list 'load-path "/path/to/tp")
(require 'tp)
```

Or with `use-package`:

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

---

## API Reference

### Core Property Functions

#### `tp-set` - Set Text Properties

Set text properties on a string or buffer region. Replaces only the specified properties, preserving others.

```elisp
;; Current buffer (properties as a list)
(tp-set START END '(PROPERTY VALUE ...))

;; Specific buffer or string
(tp-set START END '(PROPERTY VALUE ...) OBJECT)

;; Entire string (flat properties)
(tp-set STRING PROPERTY VALUE ...)
```

**Examples:**

```elisp
;; Set face on buffer region
(tp-set 1 10 '(face bold))  ; => (1 . 10)

;; Set multiple properties
(tp-set 1 10 '(face bold help-echo "Click me"))

;; Set on specific buffer
(tp-set 1 10 '(face italic) my-buffer)

;; Set properties on a string (0-indexed)
(setq my-string (tp-set 0 5 '(face italic) "Hello World"))
;; => #("Hello World" 0 5 (face italic))

;; Set properties on entire string
(tp-set "Hello" '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")

;; Face prepending - symbol faces are prepended to face list
(tp-set "Hello" 'face 'bold)
(tp-add "Hello" 'face 'shadow)
;; Result: face is (shadow bold)
```

---

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

Get property value(s) from position or range, with support for nested sub-properties.

For range and entire string queries, returns a list of `(START END VALUE)` intervals, allowing you to see all property values across the range.

```elisp
;; Single position
(tp-get POSITION PROPERTY)
(tp-get POSITION PROPERTY OBJECT)

;; Nested sub-property access
(tp-get POSITION PROPERTY SUB-KEY ...)

;; Range - specific property (returns list of intervals)
(tp-get START END PROPERTY)
(tp-get START END PROPERTY OBJECT)

;; Range with property path as list
(tp-get START END '(PROPERTY) OBJECT)
(tp-get START END '(PROPERTY SUB-KEY ...) OBJECT)

;; Range with deeply nested property path
(tp-get START END '(PROPERTY SUB-KEY SUB-SUB-KEY ...) OBJECT)

;; Range extracting multiple keys from nested property
(tp-get START END '(PROPERTY SUB-KEY (KEY1 KEY2 ...)) OBJECT)

;; Range - all properties (returns list of intervals)
(tp-get START END)
(tp-get START END OBJECT)

;; Entire string (returns list of intervals)
(tp-get STRING)
(tp-get STRING PROPERTY)
(tp-get STRING PROPERTY SUB-KEY ...)
(tp-get STRING PROPERTY SUB-KEY '(KEY1 KEY2 ...))
(tp-get STRING '(PROPERTY SUB-KEY ...))
```

**Examples:**

```elisp
;; Get from current buffer
(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)
(tp-get 0 'face my-string) ; => italic

;; Get from range - returns list of (START END VALUE) intervals
(tp-get 1 10 'face)        ; => ((1 6 bold))

;; Get with multiple intervals
(tp-set 0 5 '(face bold) str)
(tp-set 12 17 '(face italic) str)
(tp-get 0 17 'face str)    ; => ((0 5 bold) (12 17 italic))

;; Get with property path as list
(tp-get 5 20 '(face :underline :style) my-string)  ; => ((5 20 wave))

;; Get deeply nested property from entire string
(tp-get str 'face :underline :color)  ; => ((0 5 "green") (6 11 "yellow"))

;; Get multiple keys from nested property
(tp-get str 'face :underline '(:color :style))
;; => ((0 5 (:color "green" :style wave)) (6 11 (:color "yellow" :style line)))

;; Get all properties from range
(tp-get 1 10)              ; => ((1 6 (face bold help-echo "test")))

;; Get from entire string - returns list of intervals
(tp-get str)               ; => ((0 5 (face bold)) (12 17 (face italic)))
(tp-get str 'face)         ; => ((0 5 bold) (12 17 italic))
(tp-get str 'face :foreground)    ; => ((0 5 "red") (12 17 "blue"))
(tp-get str '(face :foreground))  ; => ((0 5 "red") (12 17 "blue"))
```

---

#### Fine-grained Property Functions

For manipulating sub-properties within complex properties like `face` or `display`:

```elisp
;; Get sub-property
(tp-get-sub POSITION PROPERTY SUB-PROPERTY &optional OBJECT)

;; Set sub-property
(tp-put-sub START END PROPERTY SUB-PROPERTY VALUE &optional OBJECT)

;; Remove sub-property
(tp-remove-sub START END PROPERTY SUB-PROPERTY &optional OBJECT)
```

**Examples:**

```elisp
;; Get :foreground from face
(tp-get-sub 1 'face :foreground)  ; => "red"

;; Set :weight on face
(tp-put-sub 1 6 'face :weight 'bold)

;; Remove :background from face
(tp-remove-sub 1 6 'face :background)
```

---

#### `tp-at` - Get All Properties

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

Get all text properties at POINT as a plist.

**Examples:**

```elisp
(tp-at 5)  ; => (face bold help-echo "test")
(tp-at 0 my-string)  ; Get from string
```

---

#### `tp-remove` - Remove Property

Remove a property or nested sub-property from a region or entire string.

```elisp
;; Remove entire property (buffer)
(tp-remove START END PROPERTY &optional OBJECT)

;; Remove sub-property (buffer)
(tp-remove START END '(PROPERTY SUB-KEY) &optional OBJECT)

;; Remove nested sub-properties (buffer)
(tp-remove START END '(PROPERTY SUB-KEY (NESTED-KEYS...)) &optional OBJECT)

;; Remove from entire string
(tp-remove STRING PROP1 PROP2 ...)
(tp-remove STRING PROPERTY SUB-KEY)
(tp-remove STRING PROPERTY SUB-KEY '(NESTED-KEYS...))
```

**Examples:**

```elisp
;; 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

;; Remove from entire string
(tp-remove "Hello World" 'face 'help-echo)  ; Remove multiple properties
(tp-remove "Hello World" 'face :underline)  ; Remove sub-property
(tp-remove "Hello World" 'face :underline '(:style :position))  ; Remove nested
```

---

#### `tp-remove-list` - Remove Multiple Properties

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

Remove multiple properties at once.

**Examples:**

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

---

#### `tp-clear` - Clear All Properties

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

Clear all text properties from a region.

**Examples:**

```elisp
(tp-clear 1 10)     ; Clear region
(tp-clear)          ; Clear entire buffer
```

---

### Pattern Matching Functions

#### `tp-match` - Match String

```elisp
;; Buffer
(tp-match PATTERN '(PROPERTY VALUE ...))

;; String or Buffer object
(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:**

```elisp
(tp-match-reset "TODO" '(face warning))
;; Replaces ALL properties on matched text
```

---

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

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

Apply a predefined layer's properties to an object.

**Examples:**

```elisp
;; Define a layer first
(tp-layer-define highlight '(face (:background "yellow")))

;; Apply to string
(tp-layer-propertize "Important" 'highlight)

;; Apply to substring
(tp-layer-propertize "Hello World" 'highlight 0 5)

;; Apply to buffer region
(tp-layer-propertize (current-buffer) 'highlight 1 10)
```

---

#### `tp-group-propertize` - Apply Layer Group

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

Apply all layers from a layer group to an object.

---

### Search & Navigation Functions

#### `tp-forward` / `tp-backward`

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

Search forward/backward for text with PROPERTY.

**Examples:**

```elisp
;; Find next text with 'marker property
(tp-forward 'marker)

;; Find next text where 'type equals 'heading
(tp-forward 'type 'heading)
```

---

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

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

Get the next/previous position with text properties.

---

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

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

Move point to next/previous text with 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)
```

Apply a function to all regions/strings with PROPERTY.

**Examples:**

```elisp
;; Upcase all marked text
(tp-strings-map
 (lambda (str idx)
   (message "Found: %s at index %d" str idx))
 'marker)
```

---

### Query Functions

#### `tp-in` - Find Regions with Property

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

Get all regions with PROPERTY in current buffer.

**Examples:**

```elisp
;; Get all regions with 'marker property
(tp-in 'marker)
;; => ((1 5 (marker t ...)) (10 15 (marker t ...)))

;; Filter by value
(tp-in 'type 'heading)
```

---

#### `tp-all` - Get All Propertized Regions

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

Get all regions with any text properties.

---

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

Return t if OBJECT has no text properties.

---

#### `tp-plist` - Get Merged Properties

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

Get a merged plist of all properties in a region.

---

## The Layer System

The **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.

### Layer Concept

```
┌─────────────────────────────┐
│   TOP LAYER (visible)       │  ← idx=0, What you see
├─────────────────────────────┤
│   Middle Layer (hidden)     │  ← idx=1, Preserved
├─────────────────────────────┤
│   Bottom Layer (hidden)     │  ← idx=-1, Preserved
└─────────────────────────────┘
```

### Layer Definition

#### `tp-define-layer` - Define Layer(s)

Define a single layer or a group of multiple layers.

**Single Layer:**

```elisp
(tp-define-layer layer-name
  (face (:background "cyan") line-prefix ">>"))
```

**Multiple Layers (Layer Group):**

```elisp
(tp-define-layer my-group
  layer-1                                    ; Reference existing layer
  (face (:background "red") line-prefix ">>")    ; Anonymous layer
  (face (:background "green" :weight bold)))     ; Another anonymous layer
```

The first layer in the definition is the top layer (visible by default).

**Examples:**

```elisp
;; Define individual layers
(tp-define-layer highlight
  (face (:background "yellow" :foreground "black")))

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

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

;; Define a layer group
(tp-define-layer status-colors
  highlight
  error
  info)
```

---

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

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

Get properties for a layer or all layers in a group.

---

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

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

Remove layer or group definition.

---

#### `tp-layer-reset`

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

Clear all layer and group definitions.

---

### Layer Placement

#### `tp-put-layer` - Set Layer at Index

```elisp
;; Buffer/string region
(tp-put-layer START END LAYER IDX OBJECT)

;; Entire string
(tp-put-layer STRING LAYER IDX)
```

Set layer(s) at a specific index position in the layer stack.

- `IDX = 0`: Top (visible layer)
- `IDX = -1`: Bottom
- Other values insert at that position

**Examples:**

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

;; Put base layer at top
(tp-put-layer 1 10 'base 0)

;; Put highlight at index 1 (below top)
(tp-put-layer 1 10 'highlight 1)

;; Put layer at bottom
(tp-put-layer 1 10 'info -1)
```

---

#### `tp-push-layer` - Push Layer to Top

```elisp
;; Buffer/string region
(tp-push-layer START END LAYER OBJECT)

;; Entire string
(tp-push-layer STRING LAYER)
```

Push a layer to the top of the stack (equivalent to `tp-put-layer ... 0`).

**Examples:**

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

;; Push base layer first
(tp-push-layer 1 10 'base)

;; Push highlight on top (now visible)
(tp-push-layer 1 10 'highlight)
```

---

### Layer Deletion

#### `tp-delete-layer` - Delete Layer by Name/Index

```elisp
;; Buffer/string region
(tp-delete-layer START END LAYER-NAME/IDX OBJECT)

;; Entire string
(tp-delete-layer STRING LAYER-NAME/IDX)
```

Delete a layer from anywhere in the stack by name or index.

**Examples:**

```elisp
;; Remove by name
(tp-delete-layer 1 10 'highlight)

;; Remove top layer (idx=0)
(tp-delete-layer 1 10 0)

;; Remove bottom layer
(tp-delete-layer 1 10 -1)
```

---

#### `tp-pop-layer` - Pop Top Layer

```elisp
;; Buffer/string region
(tp-pop-layer START END OBJECT)

;; Entire string
(tp-pop-layer STRING)
```

Remove the top layer (equivalent to `tp-delete-layer ... 0`).

---

### Layer Movement

#### `tp-raise-layer` - Move Layer Up/Down

```elisp
;; Buffer/string region
(tp-raise-layer START END IDX/LAYER-NAME N OBJECT)

;; Entire string
(tp-raise-layer STRING IDX/LAYER-NAME N)
```

Raise a layer by N positions. Positive N moves toward top, negative moves toward bottom.

**Examples:**

```elisp
;; Move layer1 up by 2 positions
(tp-raise-layer 1 10 'layer1 2)

;; Move layer at idx 2 down by 1 position
(tp-raise-layer 1 10 2 -1)
```

---

#### `tp-rotate-layer` - Cycle Layers

```elisp
;; Buffer/string region
(tp-rotate-layer START END OBJECT)

;; Entire string
(tp-rotate-layer STRING)
```

Rotate layers - top goes to bottom, next becomes visible.

**Examples:**

```elisp
;; Stack: highlight (top) -> base (bottom)
(tp-rotate-layer 1 10)
;; Stack: base (top) -> highlight (bottom)
```

---

#### `tp-pin-layer` - Pin Layer to Top

```elisp
;; Buffer/string region
(tp-pin-layer START END IDX/LAYER-NAME OBJECT)

;; Entire string
(tp-pin-layer STRING IDX/LAYER-NAME)
```

Move a specific layer to the top (make it visible).

**Examples:**

```elisp
;; Make 'base the top layer
(tp-pin-layer 1 10 'base)
```

---

#### `tp-switch-layer` - Switch Two Layers

```elisp
;; Buffer/string region
(tp-switch-layer START END IDX1/NAME1 IDX2/NAME2 OBJECT)

;; Entire string
(tp-switch-layer STRING IDX1/NAME1 IDX2/NAME2)
```

Swap positions of two layers.

**Examples:**

```elisp
;; Switch layer1 and layer2
(tp-switch-layer 1 10 'layer1 'layer2)
```

---

### Layer Merging

#### `tp-merge-layers` - Merge Multiple Layers

```elisp
;; Buffer/string region
(tp-merge-layers START END NEW-LAYER-NAME '(IDX1 LAYER-NAME1 IDX2 ...) OBJECT)

;; Entire string
(tp-merge-layers STRING NEW-LAYER-NAME '(IDX1 LAYER-NAME1 IDX2 ...))
```

Merge specified layers into a new layer. Earlier layers in the list take precedence.

**Examples:**

```elisp
;; Merge layer1 and layer2 into merged-layer
(tp-merge-layers 1 10 'merged-layer '(layer1 layer2))

;; Merge by index
(tp-merge-layers 1 10 'merged '(0 1 2))
```

---

#### `tp-flatten-layers` - Flatten All Layers

```elisp
;; Buffer/string region
(tp-flatten-layers START END NAME OBJECT)

;; Entire string
(tp-flatten-layers STRING NAME)
```

Flatten all layers into a single layer with the given name.

**Examples:**

```elisp
;; Flatten all layers into 'flat-layer
(tp-flatten-layers 1 10 'flat-layer)

;; Flatten with nil name (unnamed layer)
(tp-flatten-layers 1 10 nil)
```

---

### Layer Query Functions

#### `tp-layer-list` - List All Layers

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

Get list of all layer names in region.

**Examples:**

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

---

#### `tp-layer-count`

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

Count layers in region.

---

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

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

Check if layer exists in region.

---

#### `tp-layer-top`

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

Get name of the top (visible) layer.

---

## Practical Examples

### Syntax Highlighting with Multiple Layers

```elisp
;; Define layers for different highlighting purposes
(tp-define-layer code-base
  (face font-lock-keyword-face))

(tp-define-layer code-error
  (face (:underline (:color "red" :style wave))
   help-echo "Syntax error"))

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

;; Apply base highlighting
(tp-push-layer 1 100 'code-base)

;; Add error highlight on problematic code
(tp-push-layer 50 60 'code-error)

;; Toggle between error and normal view
(defun toggle-error-view ()
  (interactive)
  (tp-rotate-layer 50 60))
```

### Status Indicator

```elisp
;; Define status layers as a group
(tp-define-layer status-todo (face (:foreground "gray")))
(tp-define-layer status-progress (face (:foreground "yellow")))
(tp-define-layer status-done (face (:foreground "green")))
(tp-define-layer task-status status-todo status-progress status-done)

;; Cycle through statuses
(defun cycle-task-status ()
  (interactive)
  (tp-rotate-layer (line-beginning-position) (line-end-position)))
```

### Temporary Highlights

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

(defun flash-region (start end)
  "Flash a region temporarily."
  (tp-push-layer start end 'temp-highlight)
  (run-with-timer 0.5 nil
                  (lambda ()
                    (tp-delete-layer start end 'temp-highlight))))
```

---

## Aliases

For convenience, tp.el provides these aliases:

| Alias | Original Function |
|-------|-------------------|
| `tp-put` | `tp-set` |
| `tp-layer-properties` | `tp-layer-props` |
| `tp-layer-group-properties` | `tp-group-props` |
| `tp-layer-group-undefine` | `tp-group-undefine` |

---

## License

GNU General Public License v2 or later.

---

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

---

<p align="center">
  <em>tp.el - Making text properties powerful and easy to use</em>
</p>