Golang library for using the i3 windows manager IPC interface
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore Add coverage May 12, 2017
.travis.yml Update api to match latest version of i3 IPC (4.13) May 16, 2017
LICENSE Fresh start for the project: May 1, 2017
README.md Add better code badge May 12, 2017
bar.go Update api to match latest version of i3 IPC (4.13) May 16, 2017
bar_test.go Refactor test, fix subscription test May 10, 2017
command.go Return success for empty replies, fixes #3 May 1, 2017
command_test.go Refactor test, fix subscription test May 10, 2017
doc.go Fresh start for the project: May 1, 2017
marks.go Fresh start for the project: May 1, 2017
marks_test.go Refactor test, fix subscription test May 10, 2017
outputs.go Update api to match latest version of i3 IPC (4.13) May 16, 2017
outputs_test.go Refactor test, fix subscription test May 10, 2017
socket.go Refactor test, fix subscription test May 10, 2017
socket_test.go Refactor test, fix subscription test May 10, 2017
subscribe.go Update api to match latest version of i3 IPC (4.13) May 16, 2017
subscribe_test.go Refactor test, fix subscription test May 10, 2017
tree.go Fix rebasing issues Dec 12, 2017
tree_test.go Refactor test, fix subscription test May 10, 2017
tree_utils.go Fix rebasing issues Dec 12, 2017
utils_test.go Update api to match latest version of i3 IPC (4.13) May 16, 2017
version.go Update api to match latest version of i3 IPC (4.13) May 16, 2017
version_test.go Refactor test, fix subscription test May 10, 2017
workspaces.go Update api to match latest version of i3 IPC (4.13) May 16, 2017
workspaces_test.go Refactor test, fix subscription test May 10, 2017

README.md

GoDoc Build Status Go Report Card codecov BCH compliance

i3ipc

Overview

i3ipc is a golang library for convenient access to the IPC API of the i3 window manager. If you want to take a look at the documentation then head to http://godoc.org/github.com/mdirkse/i3ipc-go/.

Compatibility

This library can be used with the i3 IPC as it is as of at least version 4.13. However, according to the i3 maintainers:

The IPC isn't versioned. It can change with every release and usually does in one way or another. We only try to avoid breaking changes to the documented values since we consider those stable, but with good enough reason even those can change.

We'll do our best to make this library track the i3 IPC as closely as possible, but if you find anything missing (or broken) please file an issue or (even better) submit a pull request.

Usage

Thanks to Go's built-in git support, you can start using i3ipc with a simple

import "github.com/mdirkse/i3ipc"

For everything except subscriptions, you will want to create an IPCSocket over which the communication will take place. This object has methods for all message types that i3 will accept, though some might be split into multiple methods (eg. Get_Bar_Config). You can create such a socket quite easily:

ipcsocket, err := i3ipc.GetIPCSocket()

As a simple example of what you could do next, let's get the version of i3 over our new socket:

version, err := ipcsocket.GetVersion()

For further commands, refer to go doc or use the aforementioned website.

Subscriptions

i3ipc handles subscriptions in a convenient way: you don't have to think about managing the socket or watch out for unordered replies. The appropriate method simply returns a channel from which you can read Event objects.

Here's a simple example - we start the event listener, we subscribe to workspace events, then simple print all of them as we receive them:

i3ipc.StartEventListener()
ws_events, err := i3ipc.Subscribe(i3ipc.I3WorkspaceEvent)
for {
    event := <-ws_events
    fmt.Printf("Received an event: %v\n", event)
}

i3ipc currently has no way of subscribing to multiple event types over a single channel. If you want this, you can simply create multiple subscriptions, then demultiplex those channels yourself - select is your friend.

Credits

Many thanks to proxypoke for originally starting this project.