Add initial docs for command, editor, keybind, palette

content/docs/architecture/command.smd

@@ -0,0 +1,121 @@
+---
+.title = "Commands",
+.date = @date("2025-10-15T00:00:00"),
+.author = "Igor Támara",
+.layout = "tutorial.shtml",
+.draft = false,
+.custom = { .githubedit = "https://github.com/neurocyte/flow-website/tree/master/content/docs/architecture/command.md"},
+---
+
+Commands are actions triggered to operate on buffers primarily. They
+are present in `editor`, `tui`, `mode` and `minimodes`, it's possible
+to find commands in other places, which will become evident when the
+need arises.
+
+## Previous notes
+
+Note: Flow is programmed with [zig](https://ziglang.org/), if you are familiar
+with C, C++, Rust, there are differences and reasonings that
+might find useful when [learning Zig](https://ziglang.org/learn/). If you
+are coming from higher level programming languages such as Python, Ruby,
+C#, Java, Golang, Typescript it will be an opportunity to learn about trades
+of managing memory and fast responses and some lower level concepts present
+in Zig. If you are brand new to programming, some general concepts will be
+needed and practice in another language before getting into flow development.
+
+If you are new to Zig, it's a good idea to take a look at
+[ziglings](https://ziglings.org/) to practice, as you learn the language.
+
+Maybe there is a [shell command invoked](/docs/architecture/keybind#shell) with a
+keybinding that can help in the task you are aiming at before developing
+flow itself.
+
+## Understanding and creating commands
+
+A command is a function with a type like
+
+```zig
+pub fn copy(self: *Self, _: Context) Result
+```
+
+and a `Meta` definition with the same name and suffix `_meta`.
+
+```zig
+pub const copy_meta: Meta = .{ .description = "Copy selection to clipboard" };
+```
+
+`copy` command is defined in `editor.zig`, which copies the current
+selections into the pimp internal clipboard. Commands are available
+to all the modes if defined as pub.
+
+`meta` holds the description appearing in the command palette and optionally
+has arguments, the most common, an integer, that usually constitutes a
+repetition parameter, targeting vim, emacs and helix modes. As you dig in,
+there might be particularities on the parameters accepted for a given
+command.
+
+## Invoking another command
+
+Commands can be bound to mnemonics in modes by convention. For example, in
+Vim Mode `vim.zig`, `q` corresponds to (quit), the most famous one.
+
+```zig
+pub fn q(_: *void, _: Ctx) Result {
+    try cmd("quit", .{});
+}
+pub const q_meta: Meta = .{ .description = "q (quit)" };
+```
+
+Looking more closely, the first parameter in this case is of `*void` type,
+given that this command is defined in `vim.zig` which is calling the `quit`
+command defined in `editor.zig`. `cmd` takes care of routing and finding
+the command wherever it is defined.
+
+## Chaining commands
+
+Chaining commands is also common, and, by the way, swift. This is a sample
+of applying first `save_file` command and then, the command `quit`.
+
+```zig
+pub fn wq(_: *void, _: Ctx) Result {
+    try cmd("save_file", command.fmt(.{ "then", .{ "quit", .{} } }));
+}
+pub const wq_meta: Meta = .{ .description = "wq (write file and quit)" };
+```
+
+Sometimes [keybinding](/docs/architecture/keybind) is enough to accomplish
+a compound of already present commands, in others, zig programming is the
+path to be taken.
+
+# More in depth commands
+
+Is common to define private functions in a given module that are invoked from
+commands, as usual, functions are meant to be reused and help organize code.
+
+For example, in hx mode `helix.zig` the `select_to_char_left_helix` command
+uses the functions `helix_with_selections_const_arg` which iterates over all
+cursels and applies the `select_cursel_to_char_left_helix` function.
+
+```zig
+pub fn select_to_char_left_helix(_: *void, ctx: Ctx) Result {
+    try helix_with_selections_const_arg(ctx, &select_cursel_to_char_left_helix);
+}
+```
+
+## Sending parameters to commands
+
+`cmd` is in charge of finding a command given its name, and parameters sent
+to commands are vary for each command, for example, when interacting with
+the clipboard, the messages sent are multiple chunks of information, for
+now an example of such usage can be seen in a function that fetches contents
+from the clipboard.
+
+
+
+There are more advanced topics related to commands that are covered in the
+[editor](/docs/architecture/editor), that deeps in specific details of
+the editor and its interaction with cursors, selections and buffers
+modifications, among others.
+
+Learning about interactions with the buffer and editor is present in
+[minimodes](/docs/architecture/minimode).