lib/xkb/src/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 //! The package turns key presses into the symbols and text a program acts on:
 2 //! it compiles a keyboard layout, tracks which modifier keys are in force, and
 3 //! resolves sequences of key presses that produce one character.
 4 //!
 5 //! The operating system reports only a number for the key that moved, and a
 6 //! program needs the letter or symbol that key means at that moment, and the
 7 //! Unicode text it produces. What a key means depends on the alphabet in force
 8 //! and on which modifier keys, such as Shift or Caps Lock, are held, latched
 9 //! for the next key, or locked on. Some characters take a run of key presses,
10 //! as a dead accent key followed by a letter gives an accented letter.
11 //!
12 //! A layout arrives as text read at startup, so something has to compile it
13 //! into a table a key press can be looked up in. The three parts of the
14 //! modifier state change on different schedules, and the alphabet in force is a
15 //! sum of three parts that has to be brought back into range. Files that
16 //! describe multi-key sequences include other such files, so a loader with no
17 //! limits could follow includes forever or read a file of any size. A program
18 //! that wants a fixed memory footprint needs every table and every loader
19 //! workspace to have a size known in advance.
20 //!
21 //! [libxkbcommon](https://github.com/xkbcommon/libxkbcommon), the C library
22 //! Linux desktops use for keyboard handling, answers these for the X Keyboard
23 //! Extension layout format, and the package takes its semantics: layout
24 //! interpretation, modifiers, the names of key symbols and their Unicode
25 //! mappings, and the behavior of multi-key sequences (*Compose*). The package
26 //! generates tables for the 32-bit name of a key symbol (a *keysym*) from files
27 //! of libxkbcommon 1.13.2, each pinned by hash.
28 //!
29 //! The package is written in Zig and carries those semantics itself, and a
30 //! layout compiles into lookup tables (a *keymap*) with no C library involved.
31 //! One test step alone links the pinned library, running both implementations
32 //! over the same input and comparing the results (*differential conformance*),
33 //! so the lineage can be checked from this tree. A small state machine,
34 //! `state.State`, holds the three modifier masks (the *modifier state*) and the
35 //! three alphabet parts for one keyboard and, given a key number, answers with
36 //! its symbols and its Unicode text. Loading multi-key sequences parses into
37 //! workspace storage the caller supplies (a *scratch workspace*), which the
38 //! load takes at its start and gives back at its end. Every bound is fixed in
39 //! advance: a sequence of at most 10 key presses, at most 255 bytes of output
40 //! per sequence, at most 2^23 table nodes, and caps on include depth, file
41 //! bytes and path bytes.
42 //!
43 //! - *keycode*: the number the operating system reports for one physical key.
44 //! - *layout*: the index of the alphabet in force, which lets one keyboard
45 //!   carry more than one.
46 //! - *Compose table*: the trie of runs of key presses that produce one symbol,
47 //!   compiled from a Compose file, with a fixed bound on the length of a run
48 //!   and on the bytes one run produces.
49 
50 pub const keysym = @import("keysym/root.zig");
51 pub const keymap = @import("keymap/root.zig");
52 pub const state = @import("state/root.zig");
53 pub const compose = @import("compose/root.zig");