121 lines
4.4 KiB
Text
121 lines
4.4 KiB
Text
---
|
|
.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).
|