# Bach

A tool to help you find defined [compose
sequences](https://wiki.debian.org/XCompose).

## 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`