Document the top-level module of the sway-ipc library

4 files changed, 68 insertions, 4 deletions

diff --git a/bin/spatial/state.ml b/bin/spatial/state.ml
index 7cfb96b..2d1ed2c 100644
--- a/bin/spatial/state.ml
+++ b/bin/spatial/state.ml
@@ -91,7 +91,7 @@ let arrange_workspace ~focus ~socket workspace state =
   Lwt.return ()
 
 let arrange_current_workspace state =
-  Sway_ipc.wtih_socket (fun socket ->
+  Sway_ipc.with_socket (fun socket ->
       arrange_workspace ~focus:true ~socket state.current_workspace state)
 
 let register_window default_full_view default_maximum_visible workspace state
diff --git a/lib/sway_ipc/socket.ml b/lib/sway_ipc/socket.ml
index bd41f3d..ce58ccb 100644
--- a/lib/sway_ipc/socket.ml
+++ b/lib/sway_ipc/socket.ml
@@ -1,6 +1,10 @@
+(* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. *)
+
 open Sway_ipc_types
 
-type socket = Lwt_io.input_channel * Lwt_io.output_channel
+type socket = Lwt_io.input_channel * Lwt_io.output_channel * Lwt_unix.file_descr
 
 let sway_sock_path () =
   match Sys.getenv_opt "SWAYSOCK" with
diff --git a/lib/sway_ipc/sway_ipc.ml b/lib/sway_ipc/sway_ipc.ml
index 5ddf41c..3e37a29 100644
--- a/lib/sway_ipc/sway_ipc.ml
+++ b/lib/sway_ipc/sway_ipc.ml
@@ -1,6 +1,12 @@
+(* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. *)
+
 open Sway_ipc_types
 
-let connect () =
+type socket = Socket.socket
+
+let connect () : socket Lwt.t =
   let open Lwt.Syntax in
   let socket = Lwt_unix.socket PF_UNIX SOCK_STREAM 0 in
   let+ () = Lwt_unix.connect socket (ADDR_UNIX (Socket.sway_sock_path ())) in
@@ -10,7 +16,7 @@ let connect () =
 
 let close socket = Socket.close socket
 
-let wtih_socket f =
+let with_socket f =
   let open Lwt.Syntax in
   let* socket = connect () in
   let* res = f socket in
diff --git a/lib/sway_ipc/sway_ipc.mli b/lib/sway_ipc/sway_ipc.mli
new file mode 100644
index 0000000..f35d05b
--- /dev/null
+++ b/lib/sway_ipc/sway_ipc.mli
@@ -0,0 +1,54 @@
+(* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. *)
+
+type socket
+(** A socket to interact with Sway. *)
+
+val connect : unit -> socket Lwt.t
+(** [connect ()] establishes a connection with Sway. This connection
+    can be ended by using {!close}.
+
+    When possible, it is advised to use {!with_socket}. *)
+
+val close : socket -> unit Lwt.t
+(** [close socket] puts an end to a connection with Sway. *)
+
+val with_socket : (socket -> 'a Lwt.t) -> 'a Lwt.t
+(** [with_socket k] establishes a connection with Sway, hands over the
+    socket to the continuation [k], and takes care of closing the
+    connection with Sway prior to returning the result. *)
+
+val send_command : ?socket:socket -> 'a Sway_ipc_types.Message.t -> 'a Lwt.t
+(** [send_command ?socket msg] sends the command [msg] to Sway (by
+    establishing (either by using [socket], or by establishing a fresh
+    connection if [socket] is omitted), and returns the result sent
+    back by Sway.
+
+    This is a low-level helpers. It is advised to use specialized
+    helpers whenever they are available. *)
+
+val subscribe :
+  ?socket:socket ->
+  Sway_ipc_types.Event.event_type list ->
+  Sway_ipc_types.Event.t Lwt_stream.t Lwt.t
+(** [subscribe ?socket evs] returns a stream of events sent by Sway,
+    matching the event types listed in [evs].
+
+    The socket passed as argument should not be used to send commands
+    afterwards. *)
+
+val get_tree : ?socket:socket -> unit -> Sway_ipc_types.Node.t Lwt.t
+(** [get_tree ?socket ()] returns the current state of the tree
+    manipulated by Sway.
+
+    If [socket] is omitted, a fresh connection is established with
+    Sway. *)
+
+val get_current_workspace :
+  ?socket:socket -> unit -> Sway_ipc_types.Workspace.t Lwt.t
+(** [get_current_workspace ?socket ()] returns the workspace currently
+    focused by Sway.
+
+    If [socket] is omitted, a fresh connection is established with
+    Sway. *)