go-i3/README.md

Package i3 provides a convenient interface to the i3 window manager via its IPC interface.

See its documentation for more details.

Start using it

In module mode, use import path go.i3wm.org/i3/v4.

In non-module mode, use import path go.i3wm.org/i3.

Advantages over other i3 IPC packages

Here comes a grab bag of features to which we paid attention. At the time of writing, most other i3 IPC packages lack at least a good number of these features:

• Retries are transparently handled: programs using this package will recover automatically from in-place i3 restarts. Additionally, programs can be started from xsession or user sessions before i3 is even running.

• Version checks are transparently handled: if your program uses features which are not supported by the running i3 version, helpful error messages will be returned at run time.

• Comprehensive: the entire documented IPC interface of the latest stable i3 version is covered by this package. Tagged releases match i3’s major and minor version.

• Consistent and familiar: once familiar with the i3 IPC protocol’s features, you should have no trouble matching the documentation to API and vice-versa.

• Good test coverage (hard to display in a badge, as our multi-process setup breaks go test’s -coverprofile flag).

• Implemented in pure Go, without resorting to the unsafe package.

• Works on little and big endian architectures.

Scope

i3’s entire documented IPC interface is available in this package.

In addition, helper functions which are useful for a broad range of programs (and only those!) are provided, e.g. Node’s FindChild and FindFocused.

Packages which introduce higher-level abstractions should feel free to use this package as a building block.

Assumptions

• The i3(1) binary must be in $PATH so that the IPC socket path can be retrieved.
• For transparent version checks to work, the running i3 version must be ≥ 4.3 (released 2012-09-19).

Testing

Be sure to include the target i3 version (the most recent stable release) in $PATH and use go test as usual:

PATH=~/i3/build/i3:$PATH go test -v go.i3wm.org/i3