keyd/DESIGN.md

This document contains a description of major design changes. It is not intended to be exhaustive.

v2.3.0-rc

This is a major release which breaks backward compatibility for non-trivial configs. (we are still in beta after all :P).

In the absence of too much blowback, this will probably become the final v2 design.

Much of this harkens back to the v1, with some additional simplifications and enhancements.

Notable changes:

• Introduced composite layers

• Replaced three arg overload() with a more flexible timeout() mechanism

• Eliminated sequences in favour of macros (C-x is now just syntactic sugar for macro(C-x)).

• Actions which previously accepted sequences as a second argument now accept macros of any kind.

• General stability/speed/memory improvements

• Made the man page less war and peacey

Non backward-compatible changes:

• Modifiers now apply to all bindings with the exception of modifiers associated with the layer in which the key is bound.

  Rationale:

  The end result is more intuitive and allows for modifiers to be paired with layer entries.

  E.G

	capslock = layer(nav)

	[nav:C]

	h = left
	l = right

will cause `control+h` to produce `left` (rather than `C-left`), while
`control+capslock+h` will produce `C-left`, as one might intuit.

• Abolished layer types. Notably, the concept of a 'layout' no longer exists. Bindings are drawn from layers on the basis of activation order with [main] being active by default.

  Rationale:

  This simplifies the lookup logic, elminates the need for dedicated layout actions, and makes it easier to define common bindings for letter layouts since the main layer can be used as a fallback during lookup.

  E.G

    [main]
  
    capslock = layer(capslock)
  
    [dvorak]
  
    a = a
    s = o
    ...
  
    [capslock]
  
    1 = toggle(dvorak)
  

• Special characters within macros like ) and \ must be escaped with a backslash.

• Modifier sequences (e.g C-M) are no longer valid layers by default.

  Rationale:

  This was legacy magic from v1 which added a bunch of cruft to the code and seemed to cause confusion by blurring the boundaries between layers and modifiers. Similar results can be achieved by explicitly defining an empty layer with the desired modifier tags:

    I.E
  
            a = layer(M-C)
            b = layer(M)
  
    becomes
  
            a = layer(meta-control)
            b = layer(meta)
  
            [meta-control:M-C]
  

  Note that in the above sample "meta" does not need to be explicitly defined, since full modifier names are still mapped to their eponymously named layers.

• Eliminated -d

  Rationale:

  Modern init systems are quite adept at daemonization, and the end user can always redirect/fork using a wrapper script if desired.

• Eliminated reload on SIGUSR1

  Rationale:

  Startup time has been reduced making the cost of a full restart negligible (and probably more reliable).