NAME

       termkey_strpkey - parse a string representing a key event

SYNOPSIS

       #include <termkey.h>

       char *termkey_strpkey(TermKey *tk, const char *str,
                   TermKeyKey *key, TermKeyFormat format);

       Link with -ltermkey.

DESCRIPTION

       termkey_strpkey(3)  parses a string buffer containing a human-readable representation of a
       key event. It fills the key structure from the results of this  parsing,  similar  to  the
       strptime(3) standard library function.

       The  format  argument  specifies  the  format  expected in the string, as a bitmask of the
       following constants:

       TERMKEY_FORMAT_LONGMOD
              Expect full modifier names e.g. "Shift-" instead of abbreviating to "S-".

       TERMKEY_FORMAT_CARETCTRL
              If the only modifier is TERMKEY_MOD_CTRL on a  plain  letter,  accept  it  as  "^X"
              rather than "Ctrl-X".

       TERMKEY_FORMAT_ALTISMETA
              Expect the name "Meta" or the letter "M" instead of "Alt" or "A".

       TERMKEY_FORMAT_SPACEMOD
              Expect spaces instead of hyphens to separate the modifier name(s) from the base key
              name.

       TERMKEY_FORMAT_LOWERMOD
              Expect lowercase for the modifier name.

       TERMKEY_FORMAT_LOWERSPACE
              Expect lowercase with spaces in for the key name instead of camelCase (for  example
              "page down" instead of "PageDown").

       TERMKEY_FORMAT_MOUSE_POS
              Expect a mouse event to be followed by its position rendered as "@ (col,line)".

       Before  returning,  this  function  canonicalises the key structure according to the rules
       given for termkey_canonicalise(3).

       The TERMKEY_FORMAT_WRAPBRACKET option is currently  not  supported  by  termkey_strpkey().
       When  returning  a TERMKEY_TYPE_UNICODE key structure, this function will fill in the utf8
       member.

RETURN VALUE

       After a successful parse, termkey_strpkey() returns a pointer to the  first  character  of
       the  input it did not consume. If the input string contains more characters then this will
       point at the first character beyond. If the entire input string was  consumed,  then  this
       will  point  at a null byte. If termkey_strpkey() fails to parse, it returns NULL. After a
       failed parse, the key structure may contain partial or invalid results. The structure will
       only be valid if the function returns a non-NULL result.

SEE ALSO

       termkey_new(3), termkey_strfkey(3), termkey_keycmp(3), termkey(7)

                                                                               TERMKEY_STRPKEY(3)