comments and useful utils

client.go

@@ -11,6 +11,17 @@ import (
 	"sync"
 )
 
+// Client is a single connection to a sway socket.
+// All requests are synchronized in order to be thread-safe.
+// That means they are processed in incoming order.
+// If you want to be truly concurrent, use multiple clients
+// connected to the same sway socket path.
+// Subscriptions are the exception: They use their own socket connection
+// so other requests are still possible.
+// Subscription connections get closed as soon as the provided context is done.
+// Use Client.Close after all requests are processed
+// to close the connection to the socket.
+// Client.Close does not handle subscriptions.
 type Client struct {
 	sync.Mutex
 
@@ -18,6 +29,8 @@ type Client struct {
 	conn   net.Conn
 }
 
+// GetDefaultClient returns a sway client for the current seat.
+// It determines the current seat by the SWAYSOCK environment variable
 func GetDefaultClient() (*Client, error) {
 	socket, ok := os.LookupEnv("SWAYSOCK")
 	if !ok {
@@ -27,6 +40,7 @@ func GetDefaultClient() (*Client, error) {
 	return GetClientBySocket(socket)
 }
 
+// GetClientBySocket returns a sway client for the provided socket.
 func GetClientBySocket(socket string) (*Client, error) {
 	conn, err := net.Dial("unix", socket)
 	if err != nil {
@@ -39,6 +53,8 @@ func GetClientBySocket(socket string) (*Client, error) {
 	}, nil
 }
 
+// Close closes the socket connection.
+// All requests will return errors after calling Close
 func (c *Client) Close() error {
 	c.Lock()
 	defer c.Unlock()

get_bar_config.go

@@ -1,9 +1,11 @@
 package sway
 
+// GetBarIDs returns a string array containing the IDs of all sway bars
 func (c *Client) GetBarIDs() ([]string, error) {
 	return sendMessage[[]string](c, 6, "")
 }
 
+// GetBarConfig returns the configuration for the given bar id
 func (c *Client) GetBarConfig(barID string) (*BarConfig, error) {
 	return sendMessage[*BarConfig](c, 6, barID)
 }

get_binding_modes.go

@@ -1,5 +1,6 @@
 package sway
 
+// GetBindingModes returns all binding modes configured in the config file
 func (c *Client) GetBindingModes() ([]string, error) {
 	return sendMessage[[]string](c, 8, "")
 }

get_config.go

@@ -1,5 +1,7 @@
 package sway
 
+// GetConfig returns the content of the content file.
+// Includes are not handled
 func (c *Client) GetConfig() (string, error) {
 	cfg, err := sendMessage[config](c, 9, "")
 	if err != nil {

get_current_binding_mode.go

@@ -1,5 +1,6 @@
 package sway
 
+// GetCurrentBindingMode returns the currently active binding mode
 func (c *Client) GetCurrentBindingMode() (string, error) {
 	mode, err := sendMessage[name](c, 12, "")
 	if err != nil {

get_inputs.go

@@ -1,5 +1,6 @@
 package sway
 
+// GetInputs returns all input devices and their properties
 func (c *Client) GetInputs() ([]InputDevice, error) {
 	return sendMessage[[]InputDevice](c, 100, "")
 }

get_marks.go

@@ -1,5 +1,6 @@
 package sway
 
+// GetMarks returns a string array containing all current marks
 func (c *Client) GetMarks() ([]string, error) {
 	return sendMessage[[]string](c, 5, "")
 }

get_outputs.go

@@ -1,5 +1,6 @@
 package sway
 
+// GetOutputs returns all outputs and their properties
 func (c *Client) GetOutputs() ([]Output, error) {
 	return sendMessage[[]Output](c, 3, "")
 }

get_seats.go

@@ -1,5 +1,6 @@
 package sway
 
+// GetSeats returns all sway seats
 func (c *Client) GetSeats() ([]Seat, error) {
 	return sendMessage[[]Seat](c, 101, "")
 }

get_tree.go

@@ -1,5 +1,8 @@
 package sway
 
+// GetTree returns a Node object containing all
+// outputs, workspaces, containers and windows in a recursive tree.
+// Use Node.Find and Node.FindAll to search the tree recursively
 func (c *Client) GetTree() (*Node, error) {
 	return sendMessage[*Node](c, 4, "")
 }

get_version.go

@@ -1,5 +1,6 @@
 package sway
 
+// GetVersion returns information about the sway version
 func (c *Client) GetVersion() (*Version, error) {
 	return sendMessage[*Version](c, 7, "")
 }

get_workspaces.go

@@ -1,5 +1,6 @@
 package sway
 
+// GetWorkspaces returns all currently opened workspaces
 func (c *Client) GetWorkspaces() ([]Workspace, error) {
 	return sendMessage[[]Workspace](c, 1, "")
 }

run_command.go

@@ -4,6 +4,10 @@ import (
 	"git.milar.in/milarin/slices"
 )
 
+// RunCommand runs all provided commands.
+// It will return an array of errors
+// which represent the result of each command.
+// The last error is for communication problems only.
 func (c *Client) RunCommand(cmd string) ([]error, error) {
 	results, err := sendMessage[[]commandResult](c, 0, cmd)
 	if err != nil {

send_tick.go

@@ -1,5 +1,6 @@
 package sway
 
+// SendTick sends a tick with the given payload
 func (c *Client) SendTick(payload string) error {
 	result, err := sendMessage[commandResult](c, 10, payload)
 	if err != nil {

subscribe.go

@@ -11,6 +11,11 @@ import (
 	"git.milar.in/milarin/slices"
 )
 
+// Subscribe subscribes to the given event types
+// and returns a channel in which all events get written into.
+// A new socket connection will be established
+// so other requests can still be used during a subscription.
+// The subscription connection will be closed as soon as ctx is closed.
 func (c *Client) Subscribe(ctx context.Context, events ...EventType) (<-chan Event, error) {
 	conn, err := net.Dial("unix", c.socket)
 	if err != nil {

types.go

@@ -131,6 +131,53 @@ func (n Node) String() string {
 	return string(data)
 }
 
+// Find recursively searches n and returns the node
+// for which condition returned true.
+// condition is called in depth-first order:
+// 1. for n
+// 2. for n.Nodes (in order)
+// 3. for n.FloatingNodes (in order)
+//
+// If no matching node is found, Find returns nil
+func (n *Node) Find(condition func(n *Node) bool) *Node {
+	if condition(n) {
+		return n
+	}
+
+	for _, child := range n.Nodes {
+		if node := child.Find(condition); node != nil {
+			return node
+		}
+	}
+
+	for _, child := range n.FloatingNodes {
+		if node := child.Find(condition); node != nil {
+			return node
+		}
+	}
+
+	return nil
+}
+
+// FindAll behaves like Find but returns all matching nodes
+func (n *Node) FindAll(condition func(n *Node) bool) []*Node {
+	nodes := []*Node{}
+
+	if condition(n) {
+		nodes = append(nodes, n)
+	}
+
+	for _, child := range n.Nodes {
+		nodes = append(nodes, child.FindAll(condition)...)
+	}
+
+	for _, child := range n.FloatingNodes {
+		nodes = append(nodes, child.FindAll(condition)...)
+	}
+
+	return nodes
+}
+
 type NodeType = string
 
 const (

utils.go

@@ -0,0 +1,5 @@
+package sway
+
+func FindNodeByType(nodeType NodeType) func(n *Node) bool {
+	return func(n *Node) bool { return n.Type == nodeType }
+}