feat(plugins): allow message introspection (#6353)

This allows users to introspect messages (i.e. look at the elements they're made up of).

Reviewed-by: Mm2PL <mm2pl+gh@kotmisia.pl>

docs/wip-plugins.md

@@ -620,7 +620,26 @@ Closes the WebSocket connection.
 
 #### `Message`
 
-Allows creation of rich chat messages. This is currently limited but is expected to be expanded soon.
+Allows creation and modification of rich chat messages. A `Message` is
+Chatterino's representation of a chat message or any system message.
+The interface to Lua is currently limited but is expected to be expanded soon.
+
+Messages can be added to a [`Channel`](#channel). Once a message is added to a
+channel, it can't be modified anymore (except for its `flags`). These messages
+are termed "frozen" (immutable). You can check for this using the `frozen`
+property:
+
+```lua
+local my_msg = c2.Message.new({ id = "foobar" })
+assert(not my_msg.frozen)
+my_channel:add_message(my_msg)
+assert(my_msg.frozen)
+```
+
+A message has the same properties that it takes in its constructor (e.g.
+`msg.id` or `msg.flags`). If the message is not frozen (mutable), these
+properties can be modified. New elements can be added with
+[`append_element`](#messageappend_elementdata).
 
 ##### `Message.new(data)`
 
@@ -654,6 +673,58 @@ end)
 
 The full range of options can be found in the typing files ([LuaLS](./lua-meta/globals.lua), [TypeScript](./chatterino.d.ts)).
 
+##### `Message:elements()`
+
+Gets a reference to the message's elements. This can be indexed or iterated
+though. Through the return value, you can also remove elements. Note that
+currently, new elements can't be added here (use `Message:append_element`).
+
+The return value can be thought of as a table of `MessageElement`s.
+
+```lua
+local my_msg = c2.Message.new({
+  id = "foo",
+  elements = {
+    { type = "text", text = "foo" },
+    { type = "text", text = "bar" },
+    { type = "text", text = "baz" },
+  }
+})
+local elements = my_msg:elements()
+assert(#elements == 3)
+assert(elements[1].words[1] == "foo")
+assert(elements[2].words[1] == "bar")
+
+elements:erase(2) -- erase "bar"
+assert(#elements == 2)
+assert(elements[1].words[1] == "foo")
+assert(elements[2].words[1] == "baz")
+```
+
+##### `Message:append_element(data)`
+
+Creates a message element from a table (`data`) and appends it to the message.
+The structure of the table matches the one taken in `Message.new`'s `elements`.
+
+```lua
+local my_msg = c2.Message.new({ id = "foo" })
+my_msg:append_element({
+  type = "text",
+  text = "My text element",
+})
+```
+
+#### `MessageElement`
+
+A reference to an element inside a `Message` (essentially an in index into the
+elements). Note that modifications to the elements of the parent `Message` might
+change the actual element this is referring to.
+
+To distinguish different types of elements, check the `type` property. This
+takes the same values as `element.type` in the `Message` constructor.
+
+The full range of properties can be found in the typing files ([LuaLS](./lua-meta/globals.lua), [TypeScript](./chatterino.d.ts)).
+
 #### `LinkType` enum
 
 This table describes links available to plugins.