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.

See DESIGN.md for a more detailed account.

CHANGELOG.md

@@ -1,3 +1,18 @@
+# v2.3.0-rc
+
+This is a **major release** which breaks **backward compatibility** with
+non trivial configs. It is best to reread the man page. Minimal
+breaking changes are expected moving forward.
+
+ - Introduce composite layers
+ - Add timeout()
+ - Simplify layer model
+ - Layer entries are now affected by active modifiers (current layer modifiers excepted)
+ - Eliminate layer types
+ - Eliminate -d
+
+See [DESIGN.md](DESIGN.md) for a more thorough description of changes.
+
 # v2.2.7-beta
 
  - Fix support for symlinked config files (#148)

DESIGN.md

@@ -0,0 +1,116 @@
+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
+
+  - 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).

Makefile

@@ -2,32 +2,31 @@
 DESTDIR=
 PREFIX=/usr
 
-LOCK_FILE="/var/run/keyd.lock"
-SOCKET="/var/run/keyd.socket"
-LOG_FILE="/var/log/keyd.log"
-CONFIG_DIR="/etc/keyd"
+VERSION=2.3.0-rc
+COMMIT=$(shell git describe --no-match --always --abbrev=7 --dirty)
 
-VERSION=2.2.7-beta
-GIT_HASH=$(shell git describe --no-match --always --abbrev=40 --dirty)
-
-CFLAGS+=-DVERSION=\"$(VERSION)\" \
-	-DGIT_COMMIT_HASH=\"$(GIT_HASH)\" \
-	-DCONFIG_DIR=\"$(CONFIG_DIR)\" \
-	-DLOG_FILE=\"$(LOG_FILE)\" \
-	-DSOCKET=\"$(SOCKET)\" \
-	-DLOCK_FILE=\"$(LOCK_FILE)\" \
+CFLAGS+=-DVERSION=\"v$(VERSION)\ \($(COMMIT)\)\" \
 	-I/usr/local/include \
 	-L/usr/local/lib
-LDFLAGS+=$(shell if [ `uname -s` != Linux ]; then echo -linotify; fi)
+
+platform+=$(shell uname -s)
+
+ifeq ($(platform), Linux)
+	COMPAT_FILES=
+else
+	LDFLAGS+=-linotify
+	COMPAT_FILES=
+endif
 
 all: vkbd-uinput
 vkbd-%:
 	mkdir -p bin
-	$(CC) $(CFLAGS) -O3 src/*.c src/vkbd/$(@:vkbd-%=%).c -o bin/keyd -lpthread $(LDFLAGS)
+	$(CC) $(CFLAGS) -O3 $(COMPAT_FILES) src/*.c src/vkbd/$(@:vkbd-%=%).c -o bin/keyd -lpthread $(LDFLAGS)
 debug:
-	CFLAGS+="-pedantic -Wall -Wextra -g" $(MAKE)
+	CFLAGS="-pedantic -Wall -Wextra -g" $(MAKE)
 man:
-	pandoc -s -t man man.md | gzip > keyd.1.gz
+	scdoc < keyd.md | gzip > keyd.1.gz
+	scdoc < keyd-application-mapper.md | gzip > keyd-application-mapper.1.gz
 clean:
 	-rm -rf bin
 install:
@@ -55,6 +54,7 @@ install:
 	install -m755 bin/keyd $(DESTDIR)$(PREFIX)/bin
 	install -m755 scripts/keyd-application-mapper $(DESTDIR)$(PREFIX)/bin
 	install -m644 keyd.1.gz $(DESTDIR)$(PREFIX)/share/man/man1
+	install -m644 keyd-application-mapper.1.gz $(DESTDIR)$(PREFIX)/share/man/man1
 	install -m644 man.md CHANGELOG.md README.md $(DESTDIR)$(PREFIX)/share/doc/keyd
 	install -m644 examples/* $(DESTDIR)$(PREFIX)/share/doc/keyd/examples
 
@@ -63,7 +63,8 @@ uninstall:
 		$(DESTDIR)$(PREFIX)/lib/systemd/system/keyd.service\
 		bin/keyd $(DESTDIR)$(PREFIX)/bin/keyd\
 		$(DESTDIR)$(PREFIX)/bin/keyd-application-mapper\
-		$(DESTDIR)$(PREFIX)/share/man/man1/keyd.1.gz
+		$(DESTDIR)$(PREFIX)/share/man/man1/keyd.1.gz\
+		$(DESTDIR)$(PREFIX)/share/man/man1/keyd-application-mapper.1.gz
 
 install-usb-gadget: install
 	install -m644 src/vkbd/usb-gadget.service $(DESTDIR)$(PREFIX)/lib/systemd/system/keyd-usb-gadget.service

README.md

@@ -6,11 +6,12 @@ result often being tethered to a specified environment (X11). keyd attempts to
 solve this problem by providing a flexible system wide daemon which remaps keys
 using kernel level input primitives (evdev, uinput).
 
-# UPDATE (v2-beta)
+# UPDATE (v2.3.0-rc)
 
-master is currently tracking `v2-beta`. Things should be reasonably backwards
-compatible but may occasionally break before v2 leaves beta. If you are looking
-for something a bit more stable you may be interested the [v1](https://github.com/rvaiya/keyd/tree/v1) branch.
+master is currently tracking `v2.3.0-rc`. Things should be reasonably backwards
+compatible, but minor changes may be introduced before the final release. If
+you are looking for something a bit more stable you may be interested the
+[v1](https://github.com/rvaiya/keyd/tree/v1) branch.
 
 *NOTE: For those migrating their configs from v1, please see the
 [changelog](CHANGELOG.md) for a list of changes.*
@@ -154,7 +155,7 @@ members, no personal responsibility is taken for them.
 
 	[main]
 
-	leftshift = oneshot(S)
+	leftshift = oneshot(shift)
 	capslock = overload(symbols, esc)
 
 	[symbols]
@@ -182,7 +183,7 @@ following config:
 	leftalt = oneshot(alt)
 	rightalt = oneshot(altgr)
 
-	capslock = overload(C, esc)
+	capslock = overload(control, esc)
 	insert = S-insert
 
 This overloads the capslock key to function as both escape (when tapped) and

TODO

@@ -1,5 +1,10 @@
- - Organize tests.
- - Improve FAQ.
- - Add more examples.
- - Multi user support?
- - Unicode support?
+fix hotswap
+cleanup manpage
+add [globals] with configurable macro timeouts.
+[idea] tmux like layer timeouts
+nested timeouts? (perhaps not...)
+toggleable composite layers?
+improved mouse support (integrate moused?)
+organize tests
+unicode support
+multi-user support (remove keyd group)

examples/capslock-esc-basic.conf

@@ -6,4 +6,4 @@
 #
 # - when 'capslock' is held, and used in combination with another key, it
 #   behaves like a 'ctrl' key modifier (just like xcape)
-capslock = overload(C, esc)
+capslock = overload(control, esc)

keyd-application-mapper.md

@@ -0,0 +1,90 @@
+keyd-application-mapper(1)
+
+# USAGE
+
+keyd-application-mapper [-d]
+
+# OVERVIEW
+
+A script which reads _~/.config/keyd/app.conf_ and applies the supplied
+bindings whenever a window with a matching class comes into focus.
+
+You can think of each section as a set of application specific masks applied
+over the global rules defined in _/etc/keyd/\*.conf_. 
+
+The config file has the following form:
+
+```
+	[<filter>]
+
+	<expression 1>
+	<expression 2>
+	...
+```
+
+Where _<filter>_ has one of the following forms:
+
+	\[<class exp>\]              # Match by window class
+	\[<class exp>|<title exp>\]  # Match by class and title
+
+and each _<expression>_ is a valid argument to _-e_ (see *Expressions*).
+
+_<class exp>_ and _<title exp>_ are strings which describe window class and title names
+to be matched, and may optionally contain unix style wildcards (\*). For example, 
+_[gnome|\*find\*]_ will match any window with a class of _gnome_ and a title
+containing the substring _find_.
+
+E.G:
+
+```
+	[kitty]
+
+	alt.] = C-tab
+	alt.[ = C-S-tab
+	alt.t = C-S-t
+
+	[st-*]
+
+	alt.1  = macro(Inside space st)
+
+	[chromium]
+
+	control.1 = macro(Inside space chrome!)
+	alt.] = C-tab
+	alt.[ = C-S-tab
+	alt.t = C-t
+```
+
+Will remap _A-1_ to the the string 'Inside st' when a window with a class
+that begins with 'st-' (e.g st-256color) is active. 
+
+Window class and title names can be obtained by inspecting the log output while the
+daemon is running (e.g _tail\ -f\ ~/.config/keyd/app.log_).
+
+At the moment X, Sway and Gnome are supported.
+
+# INSTALLATION
+
+Installation is a simple matter of running the command _keyd-application-mapper -d_
+somewhere in your display server initialization logic (e.g _~/.xinitrc_ or
+_~/.xsession_). If you are running Gnome, 
+running _keyd-application-mapper_ for the first time will install an extension
+which manages the script lifecycle.
+
+In order for this to work, keyd must be running and the user must have access
+to */var/run/keyd.socket* (i.e be a member of the *keyd* group). 
+
+# A note on security
+
+Any user which can interact with a program that directly controls input devices
+should be assumed to have full access to the system.
+
+While keyd offers slightly better isolation compared to other remappers by dint
+of mediating access through an IPC mechanism (rather than granting users
+blanket access to /dev/input/\* and /dev/uinput), it still provides an
+opportunity for abuse and should be treated with due deference.
+
+Specifically, access to */var/run/keyd.socket* should only be granted to
+trusted users and the group _keyd_ should be regarded with the same reverence
+as _wheel_.
+