ipc: rename COMMAND to RUN_COMMAND for consistency (#2956)

All other message types are verbs, only our first-ever message COMMAND wasn’t.

While we’re here, also change the message type dictionary into a table with
clickable links to the corresponding reply type.

Authors of downstream IPC libraries are encouraged to keep the old name around
so as to not break existing code, but mark it as deprecated.

AnyEvent-I3/lib/AnyEvent/I3.pm

@@ -88,6 +88,7 @@ use base 'Exporter';
 
 our @EXPORT = qw(i3);
 
+use constant TYPE_RUN_COMMAND => 0;
 use constant TYPE_COMMAND => 0;
 use constant TYPE_GET_WORKSPACES => 1;
 use constant TYPE_SUBSCRIBE => 2;
@@ -100,7 +101,7 @@ use constant TYPE_GET_BINDING_MODES => 8;
 use constant TYPE_GET_CONFIG => 9;
 
 our %EXPORT_TAGS = ( 'all' => [
-    qw(i3 TYPE_COMMAND TYPE_GET_WORKSPACES TYPE_SUBSCRIBE TYPE_GET_OUTPUTS
+    qw(i3 TYPE_RUN_COMMAND TYPE_COMMAND TYPE_GET_WORKSPACES TYPE_SUBSCRIBE TYPE_GET_OUTPUTS
        TYPE_GET_TREE TYPE_GET_MARKS TYPE_GET_BAR_CONFIG TYPE_GET_VERSION
        TYPE_GET_BINDING_MODES TYPE_GET_CONFIG)
 ] );
@@ -322,7 +323,7 @@ Sends a message of the specified C<type> to i3, possibly containing the data
 structure C<content> (or C<content>, encoded as utf8, if C<content> is a
 scalar), if specified.
 
-    my $reply = $i3->message(TYPE_COMMAND, "reload")->recv;
+    my $reply = $i3->message(TYPE_RUN_COMMAND, "reload")->recv;
     if ($reply->{success}) {
         say "Configuration successfully reloaded";
     }
@@ -532,7 +533,7 @@ sub command {
 
     $self->_ensure_connection;
 
-    $self->message(TYPE_COMMAND, $content)
+    $self->message(TYPE_RUN_COMMAND, $content)
 }
 
 =head1 AUTHOR

docs/ipc

@@ -50,38 +50,20 @@ The magic string currently is "i3-ipc" and will only be changed when a change
 in the IPC API is done which breaks compatibility (we hope that we don’t need
 to do that).
 
-Currently implemented message types are the following:
+.Currently implemented message types
-
+[options="header",cols="^10%,^20%,^20%,^50%"]
-COMMAND (0)::
+|======================================================
-	The payload of the message is a command for i3 (like the commands you
+| Type (numeric) | Type (name) | Reply type | Purpose
-	can bind to keys in the configuration file) and will be executed
+| 0 | +RUN_COMMAND+ | <<_command_reply,COMMAND>> | Run the payload as an i3 command (like the commands you can bind to keys).
-	directly after receiving it.
+| 1 | +GET_WORKSPACES+ | <<_workspaces_reply,WORKSPACES>> | Get the list of current workspaces.
-GET_WORKSPACES (1)::
+| 2 | +SUBSCRIBE+ | <<_subscribe_reply,SUBSCRIBE>> | Subscribe this IPC connection to the event types specified in the message payload. See <<events>>.
-	Gets the current workspaces. The reply will be a JSON-encoded list of
+| 3 | +GET_OUTPUTS+ | <<_outputs_reply,OUTPUTS>> | Get the list of current outputs.
-	workspaces (see the reply section).
+| 4 | +GET_TREE+ | <<_tree_reply,TREE>> | Get the i3 layout tree.
-SUBSCRIBE (2)::
+| 5 | +GET_MARKS+ | <<_marks_reply,MARKS>> | Gets the names of all currently set marks.
-	Subscribes your connection to certain events. See <<events>> for a
+| 6 | +GET_BAR_CONFIG+ | <<_bar_config_reply,BAR_CONFIG>> | Gets the specified bar configuration or the names of all bar configurations if payload is empty.
-	description of this message and the concept of events.
+| 7 | +GET_VERSION+ | <<_version_reply,VERSION>> | Gets the i3 version.
-GET_OUTPUTS (3)::
+| 8 | +GET_BINDING_MODES+ | <<_binding_modes_reply,BINDING_MODES>> | Gets the names of all currently configured binding modes.
-	Gets the current outputs. The reply will be a JSON-encoded list of outputs
+|======================================================
-	(see the reply section).
-GET_TREE (4)::
-	Gets the layout tree. i3 uses a tree as data structure which includes
-	every container. The reply will be the JSON-encoded tree (see the reply
-	section).
-GET_MARKS (5)::
-	Gets a list of marks (identifiers for containers to easily jump to them
-	later). The reply will be a JSON-encoded list of window marks (see
-	reply section).
-GET_BAR_CONFIG (6)::
-	Gets the configuration (as JSON map) of the workspace bar with the
-	given ID. If no ID is provided, an array with all configured bar IDs is
-	returned instead.
-GET_VERSION (7)::
-	Gets the version of i3. The reply will be a JSON-encoded dictionary
-	with the major, minor, patch and human-readable version.
-GET_BINDING_MODES (8)::
-        Gets a list of currently configured binding modes.
 
 So, a typical message could look like this:
 --------------------------------------------------
@@ -124,7 +106,7 @@ payload.
 The following reply types are implemented:
 
 COMMAND (0)::
-	Confirmation/Error code for the COMMAND message.
+	Confirmation/Error code for the RUN_COMMAND message.
 WORKSPACES (1)::
 	Reply to the GET_WORKSPACES message.
 SUBSCRIBE (2)::
@@ -142,6 +124,7 @@ VERSION (7)::
 BINDING_MODES (8)::
         Reply to the GET_BINDING_MODES message.
 
+[[_command_reply]]
 === COMMAND reply
 
 The reply consists of a list of serialized maps for each command that was
@@ -153,6 +136,7 @@ human-readable error message in the property +error (string)+.
 [{ "success": true }]
 -------------------
 
+[[_workspaces_reply]]
 === WORKSPACES reply
 
 The reply consists of a serialized list of workspaces. Each workspace has the
@@ -212,6 +196,7 @@ output (string)::
 ]
 -------------------
 
+[[_subscribe_reply]]
 === SUBSCRIBE reply
 
 The reply consists of a single serialized map. The only property is
@@ -223,6 +208,7 @@ default) or whether a JSON parse error occurred.
 { "success": true }
 -------------------
 
+[[_outputs_reply]]
 === OUTPUTS reply
 
 The reply consists of a serialized list of outputs. Each output has the
@@ -269,6 +255,7 @@ rect (map)::
 ]
 -------------------
 
+[[_tree_reply]]
 === TREE reply
 
 The reply consists of a serialized tree. Each node in the tree (representing
@@ -481,6 +468,7 @@ JSON dump:
 }
 ------------------------
 
+[[_marks_reply]]
 === MARKS reply
 
 The reply consists of a single array of strings for each container that has a
@@ -489,6 +477,7 @@ The order of that array is undefined.
 
 If no window has a mark the response will be the empty array [].
 
+[[_bar_config_reply]]
 === BAR_CONFIG reply
 
 This can be used by third-party workspace bars (especially i3bar, but others
@@ -588,6 +577,7 @@ binding_mode_text/binding_mode_bg/binding_mode_border::
 }
 --------------
 
+[[_version_reply]]
 === VERSION reply
 
 The reply consists of a single JSON dictionary with the following keys:
@@ -620,6 +610,7 @@ loaded_config_file_name (string)::
 }
 -------------------
 
+[[_binding_modes_reply]]
 === BINDING_MODES reply
 
 The reply consists of an array of all currently configured binding modes.

i3-msg/main.c

@@ -167,7 +167,7 @@ int main(int argc, char *argv[]) {
     else
         socket_path = NULL;
     int o, option_index = 0;
-    uint32_t message_type = I3_IPC_MESSAGE_TYPE_COMMAND;
+    uint32_t message_type = I3_IPC_MESSAGE_TYPE_RUN_COMMAND;
     char *payload = NULL;
     bool quiet = false;
 
@@ -188,7 +188,9 @@ int main(int argc, char *argv[]) {
             socket_path = sstrdup(optarg);
         } else if (o == 't') {
             if (strcasecmp(optarg, "command") == 0) {
-                message_type = I3_IPC_MESSAGE_TYPE_COMMAND;
+                message_type = I3_IPC_MESSAGE_TYPE_RUN_COMMAND;
+            } else if (strcasecmp(optarg, "run_command") == 0) {
+                message_type = I3_IPC_MESSAGE_TYPE_RUN_COMMAND;
             } else if (strcasecmp(optarg, "get_workspaces") == 0) {
                 message_type = I3_IPC_MESSAGE_TYPE_GET_WORKSPACES;
             } else if (strcasecmp(optarg, "get_outputs") == 0) {
@@ -207,7 +209,7 @@ int main(int argc, char *argv[]) {
                 message_type = I3_IPC_MESSAGE_TYPE_GET_CONFIG;
             } else {
                 printf("Unknown message type\n");
-                printf("Known types: command, get_workspaces, get_outputs, get_tree, get_marks, get_bar_config, get_binding_modes, get_version, get_config\n");
+                printf("Known types: run_command, get_workspaces, get_outputs, get_tree, get_marks, get_bar_config, get_binding_modes, get_version, get_config\n");
                 exit(EXIT_FAILURE);
             }
         } else if (o == 'q') {

i3bar/src/xcb.c

@@ -522,7 +522,7 @@ void handle_button(xcb_button_press_event_t *event) {
         if (binding->input_code != event->detail)
             continue;
 
-        i3_send_msg(I3_IPC_MESSAGE_TYPE_COMMAND, binding->command);
+        i3_send_msg(I3_IPC_MESSAGE_TYPE_RUN_COMMAND, binding->command);
         return;
     }
 
@@ -603,7 +603,7 @@ void handle_button(xcb_button_press_event_t *event) {
         buffer[outpos] = utf8_name[inpos];
     }
     buffer[outpos] = '"';
-    i3_send_msg(I3_IPC_MESSAGE_TYPE_COMMAND, buffer);
+    i3_send_msg(I3_IPC_MESSAGE_TYPE_RUN_COMMAND, buffer);
     free(buffer);
 }
 

include/i3/ipc.h

@@ -27,9 +27,12 @@ typedef struct i3_ipc_header {
 /** Never change this, only on major IPC breakage (don’t do that) */
 #define I3_IPC_MAGIC "i3-ipc"
 
-/** The payload of the message will be interpreted as a command */
+/** Deprecated: use I3_IPC_MESSAGE_TYPE_RUN_COMMAND */
 #define I3_IPC_MESSAGE_TYPE_COMMAND 0
 
+/** The payload of the message will be interpreted as a command */
+#define I3_IPC_MESSAGE_TYPE_RUN_COMMAND 0
+
 /** Requests the current workspaces from i3 */
 #define I3_IPC_MESSAGE_TYPE_GET_WORKSPACES 1
 

src/ipc.c

@@ -113,7 +113,7 @@ void ipc_shutdown(shutdown_reason_t reason) {
  * or not (at the moment, always returns true).
  *
  */
-IPC_HANDLER(command) {
+IPC_HANDLER(run_command) {
     /* To get a properly terminated buffer, we copy
      * message_size bytes out of the buffer */
     char *command = scalloc(message_size + 1, 1);
@@ -1121,7 +1121,7 @@ IPC_HANDLER(get_config) {
 /* The index of each callback function corresponds to the numeric
  * value of the message type (see include/i3/ipc.h) */
 handler_t handlers[10] = {
-    handle_command,
+    handle_run_command,
     handle_get_workspaces,
     handle_subscribe,
     handle_get_outputs,

src/main.c

@@ -418,7 +418,7 @@ int main(int argc, char *argv[]) {
         if (connect(sockfd, (const struct sockaddr *)&addr, sizeof(struct sockaddr_un)) < 0)
             err(EXIT_FAILURE, "Could not connect to i3");
 
-        if (ipc_send_message(sockfd, strlen(payload), I3_IPC_MESSAGE_TYPE_COMMAND,
+        if (ipc_send_message(sockfd, strlen(payload), I3_IPC_MESSAGE_TYPE_RUN_COMMAND,
                              (uint8_t *)payload) == -1)
             err(EXIT_FAILURE, "IPC: write()");
         FREE(payload);
@@ -432,8 +432,8 @@ int main(int argc, char *argv[]) {
                 err(EXIT_FAILURE, "IPC: read()");
             return 1;
         }
-        if (reply_type != I3_IPC_MESSAGE_TYPE_COMMAND)
+        if (reply_type != I3_IPC_REPLY_TYPE_COMMAND)
-            errx(EXIT_FAILURE, "IPC: received reply of type %d but expected %d (COMMAND)", reply_type, I3_IPC_MESSAGE_TYPE_COMMAND);
+            errx(EXIT_FAILURE, "IPC: received reply of type %d but expected %d (COMMAND)", reply_type, I3_IPC_REPLY_TYPE_COMMAND);
         printf("%.*s\n", reply_length, reply);
         FREE(reply);
         return 0;