tp.el - Text Properties Library for Emacs

A convenient wrapper around Emacs text properties with an innovative layer system that allows setting multiple layers of text properties on the same text region.

Inspired by ov.el for overlays.

Features

• Simple API for text property manipulation (similar to ov.el for overlays)
• Innovative tp-layer system for multi-layer text properties
• Layer groups for defining reusable property sets
• Search and navigation functions for text properties
• Match and regexp functions for applying properties to text patterns

Installation

(require 'tp)

Requirements:

• Emacs 28.1+ (uses object-intervals function)
• dash (for list manipulation utilities)

Quick Start

Basic Text Properties

;; Set properties on a region
(tp-put 10 20 'face 'warning 'help-echo "Hello!")

;; Get property at point
(tp-get 15 'face)  ; => warning

;; Remove a property
(tp-remove 10 20 'face)

;; Clear all properties in region
(tp-clear 10 20)

;; Get all properties at point
(tp-at 15)  ; => (face warning help-echo "Hello!")

Match and Regexp

;; Apply properties to all matches of a string
(tp-match "TODO" 'face 'warning)

;; Apply properties to all matches of a regexp
(tp-regexp "\\bfunction\\b" 'face 'font-lock-function-name-face)

The Layer System

The layer system allows you to stack multiple sets of properties on the same text. Only the top layer is visible, but you can rotate, pin, or delete layers to reveal hidden ones.

;; Define reusable layers
(tp-layer-define highlight
  '(face (:background "yellow" :foreground "black")))

(tp-layer-define urgent
  '(face (:background "red" :foreground "white")))

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

;; Push layers onto text (first pushed is bottom, last is top)
(tp-layer-push 1 10 'highlight)
(tp-layer-push 1 10 'urgent)  ; urgent is now visible

;; Rotate layers (urgent moves to bottom, highlight becomes visible)
(tp-layer-rotate 1 10)

;; Pin a specific layer to top
(tp-layer-pin 1 10 'urgent)

;; Delete a layer
(tp-layer-delete 1 10 'highlight)

Layer Groups

Define groups of layers that work together:

(tp-group-define my-status-group
  status-normal '(face (:background "green" :foreground "black"))
  status-warning '(face (:background "yellow" :foreground "black"))
  status-error '(face (:background "red" :foreground "white")))

;; Apply all layers from a group to a string
(tp-group-propertize "Status" 'my-status-group)

API Reference

Basic Text Property Functions

Function	Description
tp-put (start end &rest properties)	Set text properties on region
tp-get (position property &optional object)	Get property value at position
tp-remove (start end property &optional object)	Remove a property from region
tp-remove-list (start end properties &optional object)	Remove multiple properties
tp-clear (&optional start end object)	Clear all properties in region
tp-at (&optional point object)	Get all properties at point
tp-plist (start end &optional object)	Get merged plist for region

Match and Regexp Functions

Function	Description
tp-match (string &rest properties)	Set properties on string matches
tp-regexp (regexp &rest properties)	Set properties on regexp matches

Layer Definition Functions

Function	Description
tp-layer-define (name properties)	Define a named layer
tp-group-define (name &rest layers)	Define a layer group
tp-layer-props (layer-name)	Get properties for a layer
tp-group-props (group-name)	Get properties for all layers in group
tp-layer-undefine (name)	Remove a layer definition
tp-group-undefine (name)	Remove a layer group definition
tp-layer-reset ()	Clear all layer definitions

Layer Manipulation Functions

Function	Description
tp-layer-push (start end name &optional object)	Push layer to top of stack
tp-layer-delete (start end name &optional object)	Delete layer from stack
tp-layer-rotate (start end &optional object)	Rotate layers (top to bottom)
tp-layer-pin (start end name &optional object)	Pin layer to top
tp-layer-set (start end name &optional object)	Name the current top layer
tp-layer-hide (start end name &optional object)	Move layer to bottom
tp-layer-show (start end name &optional object)	Move layer to top (alias for pin)
tp-layer-merge (start end layer1 layer2 new-name &optional object)	Merge two layers

Layer Query Functions

Function	Description
tp-layer-list (start end &optional object)	List all layer names in region
tp-layer-count (start end &optional object)	Count layers in region
tp-layer-exists-p (start end name &optional object)	Check if layer exists
tp-layer-top (start end &optional object)	Get name of top layer
tp-region-layer-props (start end layer-name &optional object)	Get layer properties in region

Propertize String Functions

Function	Description
tp-propertize (string &rest properties)	Propertize string
tp-layer-propertize (string layer)	Apply layer to string
tp-group-propertize (string layer-group)	Apply layer group to string

Search Functions

Function	Description
tp-forward (property &optional value predicate not-current)	Search forward for property
tp-backward (property &optional value predicate not-current)	Search backward for property
tp-forward-do (function property &optional ...)	Search forward and apply function
tp-backward-do (function property &optional ...)	Search backward and apply function
tp-regions-map (function property &optional ...)	Apply function to all matching regions
tp-strings-map (function property &optional ...)	Apply function to all matching strings

Navigation Functions

Function	Description
tp-next (&optional point property value)	Get next position with property
tp-prev (&optional point property value)	Get previous position with property
tp-goto-next (&optional property value)	Move to next property
tp-goto-prev (&optional property value)	Move to previous property

Query Functions

Function	Description
tp-in (property &optional value start end)	Get regions with property
tp-all (&optional start end)	Get all regions with properties
tp-intervals (start end &optional object)	Get all property intervals
tp-empty-p (object)	Check if object has no properties

The Layer Concept

The layer system stores multiple sets of properties in a stack structure:

┌─────────────────────────┐
│   TOP LAYER (visible)   │  <- Properties you see
├─────────────────────────┤
│      Middle Layer       │  <- Hidden, but preserved
├─────────────────────────┤
│      Bottom Layer       │  <- Hidden, but preserved
└─────────────────────────┘

Each layer is identified by a name (symbol) and contains:

• Standard text properties (face, display, help-echo, etc.)
• A special tp-name property for identification
• A tp-layers property containing the list of layers below

Layer Operations

• Push: Add a new layer on top
• Delete: Remove a layer from anywhere in the stack
• Rotate: Move top layer to bottom (cycles visibility)
• Pin: Move any layer to the top
• Hide: Move a layer to the bottom
• Merge: Combine two layers into one

Examples

Syntax Highlighting with Layers

;; Define layers for different highlighting purposes
(tp-layer-define code-syntax
  '(face font-lock-keyword-face))

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

(tp-layer-define code-selection
  '(face (:background "light blue")))

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

;; Add error highlighting on top (doesn't remove syntax highlighting)
(tp-layer-push 1 100 'code-error)

;; Toggle between showing error and syntax
(tp-layer-rotate 1 100)

Interactive Layer Switching

(defun my-toggle-layers ()
  "Toggle between different property layers on current line."
  (interactive)
  (tp-layer-rotate (line-beginning-position)
                   (line-end-position)))

(global-set-key (kbd "C-c t") 'my-toggle-layers)

License

GNU General Public License v2 or later.