i3/go-i3

Package i3 provides a convenient interface to the i3 window manager

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

go-i3's Issues

Don't log variant detection

It would be nice if the api did not log the detection of the version Variant. Is there a need to communicate that this is unsupported?

I'm writing a small tool with I'd like to be usable both with i3 and sway. https://github.com/quite/i3gopher

Though the tool is supposed to be run in the background, this frequently logged string (on every messaged roundtripped!) will drown any other relevant logging (error or otherwise) that it does.

I see that we can't really return non-nil since that'd stop the variant from being accepted. What to do...

@dlasky what do you think?

[feature request] add field scratchpad_state to i3.Node

Currently the command i3-msg -t get_tree provides the field scratchpad_state that is useful in identifying windows that are currently shown but still considered to be in the scratchpad. This field is not present/unmarshalled into i3.Node.

I believe adding this line to the Node struct definition would suffice.

ScratchpadState    string           `json:"scratchpad_state"`

Add node app_id for using this pkg with sway

I'm using this pkg for supporting both i3 and sway in my https://github.com/quite/i3gopher

I just found out that I'd need to get hold of the app_id of a node, which is only available under sway (approx like the window instance in X11). I'm using this pkg because it is so good, and I did from the beginning only support i3. And thanks to #4 it just works out of the box with sway. Only now did I run into the missing app_id for i3gopher's exclude functionality.

Having read the #4 issue I'm thinking that you might be wary of making such a sway-specific addition to this pkg @stapelberg . What do you think? I have not come across the fork of this pkg that @dlasky mentioned, which blanked-renames it to go-sway. But I also think that is not such a great idea.

TestRestart is flaky

See e.g.:
https://travis-ci.org/i3/go-i3/builds/530377615?utm_medium=notification&utm_source=email
https://travis-ci.org/i3/go-i3/builds/528495890?utm_medium=notification&utm_source=email
https://travis-ci.org/i3/go-i3/builds/526529017?utm_medium=notification&utm_source=email

Interest check -- sway support?

It looks like only https://github.com/i3/go-i3/blob/master/socket.go#L32 would need to be abstracted to an environment var with a sane default to i3 if you wanted to support swaywm.

More than happy to PR this if there is any interest.