ksway

This library provides a convenient interface for quickly making scripts for i3 and sway (since they share an IPC interface API). It will mainly be focused on sway if that compatibility changes.

It will also be a container for the many scripts I use on a daily basis which live under examples/.

Those examples are the best resource for learning how to use this for complex situations, but here are some small examples:

Short examples

connect

let mut client = Client::connect()?;
let mut client = Client::connect_to_path("/run/user/1000/sway-ipc.1000.1.sock")?;

run commands

The criteria implementation is complete and up to date as of 2019-07-27.

use ksway::{ipc_command, command};


// These are equivalent
client.ipc(ipc_command::run("exec st"))?;
client.ipc(ipc_command::run(command::raw("exec st"))?;
client.ipc(ipc_command::run(command::exec("st"))?;
client.run(command::exec("st"))?;

// The benefit of using command is the additional methods such as .with_criteria

use ksway::criteria::*;

let cmd = command::raw("focus").with_criteria(vec![floating(), title("mpv")]);
client.run(cmd)?;

// criteria examples
let cmd = command::raw("focus").with_criteria(vec![workspace(focused())]);
let cmd = command::raw("focus").with_criteria(vec![con_id(123)])
let cmd = command::raw("focus").with_criteria(vec![con_id(focused())])

get_*

use ksway::ipc_command;

client.ipc(ipc_command::get_tree())?;

let tree_data = json::parse(str::from_utf8(&client.ipc(ipc_command::get_tree())?)?)?;

client.ipc(ipc_command::get_workspaces())?;
client.ipc(ipc_command::get_version())?;

subscribe*

use ksway::IpcEvent;

let rx = client.subscribe(vec![IpcEvent::Window, IpcEvent::Tick])?;
loop {
	while let Ok((payload_type, payload)) = rx.try_recv() {
		match payload_type {
			IpcEvent::Window => {},
			_ => {},
		}
	}
	client.poll()?;
}

Full examples

• examples/sway-focused-window $PATH: Outputs the json for the currently focused window with no arguments, but you can additionally specify a path to extract, e.g.

  • sway-focused-window -> full json
  • sway-focused-window window_rect width
  • sway-focused-window window_properties title
  • sway-focused-window id

• examples/sway-focus-next $INCREMENT $EXPRESSIONS: Focus the next window which matches the criteria matched by $EXPRESSIONS. By next, I mean, it will try to find the next window after the currently focused one (if the focused one is included in the set of windows specified by $EXPRESSIONS, otherwise it will choose the first window).

  • sway-focus-next 1 visible==true
  • sway-focus-next 1 type==floating
  • sway-focus-next 1 visible==true type==$(sway-focused-window type)
  • sway-focus-next -1 visible==true type==$(sway-focused-window type)

• examples/watch-sway-windows: Run rules based on the current windows. This is highly personal and customized for my needs and not very well documented.

TODO

• Add serde typed interface under a feature gate. I plan to generate this with json_typegen.
• Think about making a future based interface for subscribe.
• Add more commands to ksway::command::*, such as resize and whatnot.
• Document all the examples

Open Design Questions

• Should I add an ipc_json method for deserializing to json or serde_json?