From b01dfdb992103a6321269bfdadf132a948772f82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20T=C3=A1mara?= Date: Fri, 31 Oct 2025 08:53:12 -0500 Subject: [PATCH] Add more internal links and precisions on command arguments --- content/docs/architecture.smd | 13 +++++---- content/docs/architecture/command.smd | 26 +++++++++++------ content/docs/architecture/keybind.smd | 40 +++++++++++++++++---------- content/docs/index.smd | 4 +-- 4 files changed, 53 insertions(+), 30 deletions(-) diff --git a/content/docs/architecture.smd b/content/docs/architecture.smd index 0b5ce3f..5e8dbd4 100644 --- a/content/docs/architecture.smd +++ b/content/docs/architecture.smd @@ -140,14 +140,17 @@ logger.print("{} unsaved buffer(s) remaining", .{remaining}); ### View key presses There are situations when you press some keys without the expected -behavior happening, to review if flow is getting the keys, or your -desktop environment or something else are capturing them, you will want -to invoke flow with the option `--show-input`. +behavior happening, to review if flow is getting the keys, the +[keybindings are associated](/docs/architecture/keybind), and are +executing the [desired command](/docs/architecture/command), or maybe +your desktop environment or something else is capturing them, you will +want to invoke flow with the option `--show-input`. []($section.id("next")) ## Next steps -* [Guidelines for contributions](/docs/contributing) -* [Take a peek on testing](/docs/testing) * [Configure some keybinds](/docs/architecture/keybind) +* [Guidelines for contributions](/docs/contributing) +* [Create your own commands](/docs/architecture/command) +* [Take a peek on testing](/docs/testing) * [Back to docs](/docs) \ No newline at end of file diff --git a/content/docs/architecture/command.smd b/content/docs/architecture/command.smd index 081ba83..8d251cf 100644 --- a/content/docs/architecture/command.smd +++ b/content/docs/architecture/command.smd @@ -69,7 +69,7 @@ in Vim Mode `vim.zig`, `q` corresponds to (quit), the most famous one. ```zig pub fn q(_: *void, _: Ctx) Result { - try cmd("quit", .{}); + try command.cmd("quit", .{}); } pub const q_meta: Meta = .{ .description = "q (quit)" }; ``` @@ -122,14 +122,14 @@ pub fn select_to_char_left_helix(_: *void, ctx: Ctx) Result { `goto_line` (in the case of vim and helix mode, you first type the number and then the action, `gg`) is a command that exemplifies -receiving an integer parameter as stated in its meta: +receiving an integer parameter. As stated in its meta: ```zig pub const goto_line_meta: Meta = .{ .arguments = &.{.integer} }; ``` and to actually receiving the integer parameter, `goto_line` will -extract it like this: +extract from the context like this: ```zig pub fn goto_line(self: *Self, ctx: Context) Result { @@ -140,9 +140,17 @@ pub fn goto_line(self: *Self, ctx: Context) Result { ``` To send a parameter to a command, make sure that the type is exactly -the same when retrieving it. We will refer as encode and decode. Hence -for our terminology to send an integer parameter to a command, we -will encode it using `command.fmt` like in +the same when retrieving it. We will refer as encode and decode when +packing parameters in the context. To pack the `command.fmt` we will +encode it like this, when invoking `goto_line`. + +```zig +var the_line: usize = 43; +try command.cmd("goto_line", command.fmt(.{the_line - 1})); +``` + +Or calling the command directly, if we have a reference to the object +that holds the command. ```zig var the_line: usize = 43; @@ -150,10 +158,12 @@ try ed.goto_line(command.fmt(.{the_line - 1})); ``` It's possible to pass multiple parameters to commands, including arrays -and json, they all will be packed in Command.Context. +and json, packing all of them in Command.Context. A deeper explanation of the rules about parameter passing is exposed in -[inner data exchange](/docs/architecture/inner_data_exchange). +[inner data exchange](/docs/architecture/inner_data_exchange), given +that parameters can be sent not only to commands, but other broather +use cases. []($section.id('next')) ## Next steps diff --git a/content/docs/architecture/keybind.smd b/content/docs/architecture/keybind.smd index b39c856..2ef1b31 100644 --- a/content/docs/architecture/keybind.smd +++ b/content/docs/architecture/keybind.smd @@ -12,29 +12,38 @@ If you are here, maybe is because you want to make flow behave according to your key presses preferences or possibly you already have edited your -own keybinds to suit your needs and are looking for some advanced -topics to cope your use cases and make everything easier, faster and -fluid when in Flow. +own keybinds to suit your use cases and make everything easier, faster +and more fluid when in flow. + +First make sure you are aware of the +[existence of ctrl+f2 palette](/docs#key_controls) which +exposes a list of commands available for you to use, and when you select +a command, it's pasted in your current cursor position. Using the command palette `Ctrl+Shift+p` and typing **Edit key -bindings**, takes you to a json file to extend Flow, configuring -keybindings to suit your needs. According to the mode you are in, the -corresponding file will be opened. The palette can also be reached left -clicking on the current mode in the status bar. +bindings**, takes you to a json file to extend flow, configuring +keybindings to suit your needs. According to the mode you are in, your +personal mode's file configuration will be opened. Explore the +the file to discover how commands are bound to some combos, key presses +and the different [imodes](#hierarchy) present. + +Command palette can also be reached left clicking on the current +mode in the status bar. []($section.id('tldr')) ## ;TLDR; -Once you open the corresponding json file, locate inside the imode -(internal mode) that will accept the key or key/combos and add an array, -where the first element is the combination to map to the commands that -will be invoked, the array accepts strings like in +Once you open the corresponding json file, locate inside the +[imode](#hierarchy)(internal mode) that will accept the key or +key/combos and add an array, where the first element is the combination +to map to the commands that will be invoked, the array accepts strings +like in ```js ["ctrl+alt+shift+p", "open_command_palette"] ``` -To avoid screwing up the combinations, and putting Flow in an unusable +To avoid screwing up the combinations, and putting flow in an unusable state derived from a wrong mapping of key combinations, read on. []($section.id('defaults')) @@ -154,11 +163,12 @@ consider using more keybindings or running tasks for your projects. If you realized that there is a handy combination that others can benefit from or that a mode lacks the combination and it might be -included in flow, look at the [contribution guidelines](/docs/contributing) -to submit your findings and solution. +included in flow, look at the +[contribution guidelines](/docs/contributing) to submit your findings +and solutions. Probably binding commands is good, but maybe there is a feature in other -text editors that you miss and would love to have it at your fingertips. +text editors that you miss and would love to have at your fingertips. Then it's Zig time: [Adding commands](/docs/architecture/command) to flow. diff --git a/content/docs/index.smd b/content/docs/index.smd index 5ed7ab1..641f3f7 100644 --- a/content/docs/index.smd +++ b/content/docs/index.smd @@ -15,7 +15,7 @@ command. The manual is included here for convenience. * [Flow Control online help](/docs/help) - +[]($section.id("basic_usage")) ## Basic Usage ```bash flow file.zig:42 # Open at line 42 @@ -24,7 +24,7 @@ flow --list-languages # Show all supported languages flow --help # List of command line options ``` - +[]($section.id("key_controls")) ## Key Controls | Command | Action | |---------------------------|----------------------|