hkfind(1)

NAME

hkfind - find sxhkd(1) hotkeys that match a search expression

SYNOPSIS

hkfind [options...] [expression]

DESCRIPTION

hkfind searches a sxhkdrc file for keybinds that match a given expression, similar in spirit to find(1). It writes the hotkeys for the matching keybinds to standard output. If expression is omitted, all keybinds are matched.

See sxhkd-parser(7) for important background information needed to use this tool.

OPTIONS

Run hkfind --help.

EXPRESSION

After the options, the search expression may be entered. hkfind accepts a similar expression syntax as find(1), but is much simpler. An expression is composed of:

    • Predicates: The filters against which the keybinds are matched.
    • Operators: Join predicates together as a logical expression.

The expression evaluates against each permutation of a keybind. Only when the whole expression evaluates to true for a permutation of a keybind does its hotkey get written to standard output.

  PREDICATES

-cmd command ;
    Execute command; true if 0 status is returned. An empty command is forbidden. Replaces all occurrences of the hotkey replacement string (-H) with the hotkey and all occurrences of the command replacement string (-C) with the filename of a temporary file containing the contents of the command for the keybind permutation.

-has name
    True if the key name is in the metadata of the keybind.
-has name = value
    True if the value of name is exactly value. Whitespace is significant before and after the "=".
-has name != value
    True if the value of name is not value. Whitespace is significant before and after the "!=".
NOTE ON GREEDINESS: -has consumes more than one argument only if the next argument cannot possibly be interpreted as another predicate or as a logical operator. That is, -has consumes three arguments if the argument after name:
    1. does not start with - (predicate); and
    2. is not exactly ! (negation), (, or ) (grouping).

-in path
-child-of path
    True if the keybind is a (direct) child of the section referred to by path. An empty path is forbidden.
-under path
-descendant-of path
    True if the keybind is a descendant (but not a direct child) of the section referred to by path. An empty path is forbidden.
path is an absolute or relative UNIX path and can have the directory separators escaped, i.e., /foo\/bar/baz has section baz underneath the top-level foo/bar, but foo\/bar/baz has section baz underneath a section foo/bar which may or may not be at the top-level.

  OPERATORS

Listed in order of decreasing precedence, with the same meaning as those in find(1):

( expr )

! expr

expr1 -a expr2
expr1 expr2

expr1 -o expr2

EXIT STATUS

Similarly to find(1), hkfind exits with status 0 if no errors occur, greater than 0 if any do.

SEE ALSO

sxhkd(1), find(1), sxhkd-parser(7)