3 releases (breaking)

0.3.0 Jun 25, 2023
0.2.0 May 11, 2023
0.1.0 Apr 30, 2023

#1444 in Command line utilities

BSD-2-Clause-Patent

495KB
12K SLoC

Bach

A tool to help you find defined compose sequences.

Usage

Provide a query as a positional argument, which will then be matched against

  • the name of the unicode character produced by a sequence, when -n is specified (case insensitive)[^1]
  • the result string of a compose sequence, when -r is specified (case sensitive)
  • the comment following a sequence's definition, when -c is specified (case insensitive)

or all three when neither -n, -r, nor -c are specified.

By default, only sequences that start with the compose key are shown, All sequences (e.g. those starting with dead keys) can be shown with the -a flag.

Interpretation

bach can return matching sequences in two formats: as they would appear in an .XCompose file (by using the -x flag), or its own “pretty” format (the default).

The .XCompose format is described in Compose(5).

The pretty format is, for each sequence,

<result><events> ~ <info>

where

  • result is the string or X11 keysym resulting from that compose sequence. To help differentiate keysyms, they are set in magenta italics.
  • events are the keypresses needed. These are mostly self-explanatory, but the following symbols are used for special keys:
    • the compose key itself is a magenta ♦
    • keypad keys are in blue
    • dead keys are a yellow dotted circle with the combining mark, e.g. ◌̂ for XK_dead_circumflex
      • α is used for XK_dead_greek
      • ι is used for XK_dead_iota
      • ¤ is used for XK_dead_currency
      • a–e are used for XK_dead_a–e
    • other special symbols are in cyan:
      • for XK_Escape
      • for XK_BackSpace
      • for XK_Tab
      • for XK_Return
      • for XK_space
      • for XK_nobreakspace
      • , , , respectively for XK_Up, XK_Down, XK_Left and XK_Right.
  • info is the sequence's inline comment in the compose file, or the name of the character produced if there is no such comment[^1].

Personal compose file

bach will look for your personal compose file at XCOMPOSEFILE, or ~/.XCompose if this is not set.

Global compose files

bach will need to locate X11's global compose sequence files if they are referred to in your personal compose file (e.g. via include "%L"), or if you have no such file. By default, it will use /usr/share/X11/locale, but this can be changed via

  • setting BACH_X11_SYSTEM_DIR_DEFAULT at compile time[^2]
  • setting BACH_X11_SYSTEM_DIR at runtime
  • the --x11-system-dir argument

in order of increasing priority.

Limitations

  • bach will display sequences that are clobbered by identical or longer sequences that are defined later
  • Octal (\124) and hex (\x4F) character escapes are always interpreted as the corresponding character in unicode.
  • You probably shouldn't use it in a non-UTF-8 locale in general
  • Error reporting is fairly preliminary

Sequence compatibility

bach understands the full xcompose file format as described in Compose(5), however I have found mixed compatibility for this full specification across different programs and platforms, in particular:

  • Modifiers are often ignored and can render a sequence invalid
  • Octal and hex character escapes are not always supported
  • Specifying only a keysym as the result of a sequence is not recognised in some cases

License

Bach is distributed under the BSD-2-Clause Plus Patent License.

[^1]: Only applies for sequences that produce one character

[^2]: This will be set to a suitable value when built with nix build

Dependencies

~3–13MB
~107K SLoC