Metadata-Version: 2.4
Name: confhelp
Version: 0.1.1
Summary: Config-driven parser for keybindings with fzf interface
Author: Piotr Zaniewski
License-Expression: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: iterfzf>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# confhelp

[![PyPI version](https://badge.fury.io/py/confhelp.svg)](https://badge.fury.io/py/confhelp)
[![Python](https://img.shields.io/pypi/pyversions/confhelp.svg)](https://pypi.org/project/confhelp/)
[![Tests](https://github.com/Piotr1215/confhelp/actions/workflows/test.yml/badge.svg)](https://github.com/Piotr1215/confhelp/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Config-driven parser for extracting keybindings from dotfiles.

![demo](media/demo.png)

## Why

Most developers accumulate keybindings across tmux, zsh, vim, and other tools. These bindings live scattered across config files, and remembering them all becomes impossible.

The typical solution is maintaining a static YAML or markdown file listing shortcuts. But this falls out of sync - you add a binding and forget to update the docs.

confhelp solves this by parsing your actual config files. Define regex patterns once, and confhelp extracts bindings directly from source. Your help system stays in sync because it reads the same files you edit.

## Install

```bash
pip install confhelp
```

## Usage

```bash
# Output all bindings
confhelp -c config.toml -b ~/dotfiles

# Interactive fzf selection
confhelp -c config.toml -b ~/dotfiles --select

# Select and open in $EDITOR at line
confhelp -c config.toml -b ~/dotfiles --edit

# JSON output
confhelp -c config.toml -b ~/dotfiles -f json
```

Example output:

```
[tmux]   prefix+g   display-popup -w 80%...   .tmux.conf:42
[alias]  gs         git status                .zsh_aliases:15
[bind]   ^[e        edit-command-line         .zshrc:89
```

The `--edit` flag drops you directly into the file at the exact line. Change the binding, save, done.

## Config Format

Define parsers in TOML. Each section describes how to extract bindings from a set of files:

```toml
[tmux]
paths = [".tmux.conf"]
match_line = "^bind"
regex = 'bind(?:-key)?\s+(?:-n\s+)?(\S+)(.*)'
key_group = 1
desc_group = 2
type = "tmux"
truncate = 100

[alias]
paths = [".zsh_aliases", ".zsh_claude"]
regex = "alias\\s+(?:-[gs]\\s+)?([^=]+)=(.*)"
key_group = 1
desc_group = 2
type = "alias"
strip_quotes = true

[abbrev]
paths = [".zsh_abbreviations"]
mode = "abbrev_block"
type = "abbrev"
```

### Config Options

| Option | Description |
|--------|-------------|
| `paths` | List of files to parse (relative to base-dir) |
| `regex` | Pattern with capture groups for key/desc |
| `key_group` | Capture group number for the key |
| `desc_group` | Capture group number for description |
| `match_line` | Only process lines matching this pattern |
| `skip_comment` | Skip lines starting with `#` |
| `truncate` | Max length for description |
| `strip_quotes` | Remove surrounding quotes from desc |
| `desc_literal` | Use fixed string as description |
| `desc_from_comment` | Extract desc from trailing `# comment` |
| `mode` | Special modes: `abbrev_block` for zsh abbreviations |

## Output Formats

- `pipe` (default): `[type]|key|desc|file:line`
- `tsv`: Tab-separated
- `json`: JSON array

The pipe format works well with `column -t -s'|'` for aligned display.

## Integration Examples

confhelp outputs text. How you display it is up to you.

### Alacritty Popup

Spawn a centered popup window showing bindings. Enter jumps to the file:

```bash
selection=$(confhelp -c config.toml -b ~/dotfiles | column -t -s'|' | fzf)
# parse selection, open in editor
```

See `examples/alacritty-popup.sh` for a complete implementation.

### tmux Popup

```bash
tmux display-popup -w 80% -h 80% -E 'confhelp -c config.toml -b ~/dotfiles --select'
```

See `examples/tmux-popup.sh` for a complete implementation.

### Rofi/dmenu

```bash
confhelp -c config.toml -b ~/dotfiles | rofi -dmenu
```

## Acknowledgments

Inspired by [Extracto](https://github.com/sarthakbhatkar1/Extracto).

## License

MIT
