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.
hkcheck
: Lint your keybinds.hkexport
: Export your keybinds to various formats including HTML and
plaintext.hkwatch
: Tail the sxhkd status fifo and output the current mode.hkfind
: Get hotkeys that match given search criteria.hkxargs
: Execute commands on a keybind's command for editing them,
retrieving some information from them, or running linters on them.hkdebug
: Retrieve information useful for debugging the config.For more, see the modules prefixed with hk
in sxhkd_parser/cli/
.
sxhkd
configssxhkdrc
syntaxThe 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.
We will use pipx because it is convenient.
pipx
is available on distro repositories.
Run pipx install sxhkd-parser
.
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.
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()
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.
I'm aware that "hotkey" and "keybind" are interchangeable and have the meaning of (3) above, so any suggestions for renaming (1) are welcome.
To maintain simplicity in the implementation, some uncommon features of sxhkd are unsupported. The list follows:
:
to indicate noabort across the permutations of a
hotkey:
Hotkey
object has a single noabort_index
attribute. This will
not change.:
outside of any sequences.{s1,s2,s3,...,sn}
:
A-Z
, a-z
, A-F
, a-f
, A-z
(within ASCII)0-9
, 5-8
0-A
, A-0
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.