pygments-richstyle 1.0.0
Customized Pygments fork with .richstyle CSS-like theming for RichX
License: Apache License 2.0

**pygments_richstyle** is a customized fork of the original [Pygments](https://pygments.org/) syntax highlighter — rebuilt to integrate seamlessly with **RichX** and its new `.richstyle` CSS-like theming system.

This package provides an extensible framework for syntax highlighting and console styling, allowing developers to use human-friendly `.richstyle` files to define colors, fonts, and attributes that work across both Pygments and Rich.

---

## Features

- **CSS-like `.richstyle` themes** for Pygments and RichX
- **Dynamic style loading** via `RichstyleTheme`
- **Two-way compatibility**: use `.richstyle` files with both Rich and Pygments
- Fully compatible with existing lexers, formatters, and tokens
- Convert `.richstyle` themes into `rich.Theme` for direct console use

---

## Installation

```bash
pip install pygments_richstyle
````

If you are using it inside RichX:

```bash
pip install richx pygments_richstyle
```

---

## Usage

### Load a `.richstyle` file

```python
from pygments_richstyle.richstyle_loader import RichstyleTheme
from rich.console import Console

theme = RichstyleTheme.from_file("themes/forest.richstyle")
console = Console(theme=theme.to_rich_theme())

console.print("Hello from pygments_richstyle!", style="header")
```

### Use with syntax highlighting

```python
from pygments_richstyle import highlight, lexers
from pygments_richstyle.formatters import TerminalFormatter
from pygments_richstyle.richstyle_loader import RichstyleTheme

code = 'def greet():\n    print("Hello, world!")'
lexer = lexers.get_lexer_by_name("python")
theme = RichstyleTheme.from_file("themes/oceanic_deep.richstyle")
formatter = TerminalFormatter(style=theme)

print(highlight(code, lexer, formatter))
```

---

## `.richstyle` Example

Example: `themes/forest.richstyle`

```css
/* Variables */
--forest: #2e8b57;
--clay: #a0522d;
--sand: #deb887;

/* Selectors */
header {
    color: var(--forest);
    bold: true;
}

subheader {
    color: var(--clay);
}

note {
    color: var(--sand);
    italic: true;
}
```

---

## Architecture

| Module                                  | Description                                                      |
| --------------------------------------- | ---------------------------------------------------------------- |
| `richstyle_loader.py`                   | Loads and compiles `.richstyle` into a Pygments-compatible Style |
| `rich_css_style.py`                     | Parses `.richstyle` syntax (variables, selectors, color props)   |
| `lexers/richstyle_lexer.py`             | Syntax tokenizers compatible with Pygments ecosystem             |

---

## Integration with RichX

RichX can automatically detect `.richstyle` files from your pygments_richstyle installation:

```python
import pygments_richstyle
from rich.console import Console

console = Console(theme=mypyments.RichstyleTheme.from_file("themes/modern.richstyle").to_rich_theme())
console.print("Integrated theming works beautifully!", style="note")
```
---

## License

MIT License © 2025

---

# Changelog

All notable changes to **pygments_richstyle** will be documented in this file.
## Added
- Initial release of pygments_richstyle as a customized fork of Pygments.
- `.richstyle` support for CSS-like theming in RichX.
- `rich_css_style.py`: Parses `.richstyle` files, supports variables, selectors, and common CSS-like properties.
- `richstyle_loader.py`: Converts parsed `.richstyle` files into a Pygments-compatible Style object and Rich `Theme`.
- `lexers/richstyle_lexer.py`: Lexer for `.richstyle` files with syntax highlighting for:
  - Comments (`/* ... */`)
  - CSS-like variables (`--primary: ...`)
  - Selectors (`header { ... }`)
  - Property values (colors, strings)
- CLI support for `.richstyle` preview, compilation, and JSON output.
- Full integration with RichX: use `.richstyle` themes for both terminal highlighting and Rich console styling.