Hoboneer / sxhkd-parser

Parser library for sxhkd configs
GNU General Public License v3.0
7 stars 0 forks source link

sxhkd-parser

sxhkd-parser is a mostly complete library written in Python 3.7 for parsing sxhkd configs.

It has no dependencies and will not have any in the future.

Bundled tools

For more, see the modules prefixed with hk in sxhkd_parser/cli/.

Goals

Interface Stability

The library API has no guarantees about stability (yet), but the interface of the CLI tools should be relatively more stable.

This project follows semantic versioning. On v1.0.0, the library API will be stable and the CLI tools will be split into a separate Python package after which they can start to have dependencies.

Quickstart

Install

We will use pipx because it is convenient. pipx is available on distro repositories.

Run pipx install sxhkd-parser.

Manuals

If your system uses man-db, include export MANPATH="$HOME/.local/pipx/venvs/sxhkd-parser/share/man:" in .profile, .bashrc, or any startup config file of your choice.

Run man <TOOL> for the details of each tool. man 7 sxhkd-parser also has the background information needed to use them.

Print all your keybinds

from sxhkd_parser import *

for bind_or_err in read_sxhkdrc('sxhkdrc'):
    if isinstance(bind_or_err, SXHKDParserError):
        print(bind_or_err)
        continue
    keybind = bind_or_err
    print(keybind)
    keybind.hotkey.get_tree().print_tree()
    keybind.command.get_tree().print_tree()

Include sections and descriptions

from sxhkd_parser import *

handler = SimpleSectionHandler(r'^#\s*(?P<name>[A-Z. /-]+):$')
parser = SimpleDescriptionParser(r'^#\s*(?P<description>[A-Z][^.]+\.)$')
for bind_or_err in read_sxhkdrc('sxhkdrc', section_handler=handler, metadata_parser=parser):
    if isinstance(bind_or_err, SXHKDParserError):
        print(bind_or_err)
        continue
    keybind = bind_or_err
    print(keybind)
    keybind.hotkey.get_tree().print_tree()
    keybind.command.get_tree().print_tree()
handler.get_tree().print_tree()

In this example, the description for a keybind is the comment immediately preceding the start of the keybind that matches the given regex.

Terminology

  1. Hotkey: The sequence of chords needed to activate a command.
  2. Command: The command passed to the shell after the hotkey is completed.
  3. Keybind: The entity that encompasses the above.

I'm aware that "hotkey" and "keybind" are interchangeable and have the meaning of (3) above, so any suggestions for renaming (1) are welcome.

Limitations

To maintain simplicity in the implementation, some uncommon features of sxhkd are unsupported. The list follows:

Also, using @ or ~ at the start of the hotkey instead of just before the keysym (as documented in the manpage of sxhkd) is unsupported. Use the documented syntax.