neurocyte/flow-website
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Links between developer docs

Browse source
This commit is contained in:
Igor Támara 2025-10-29 16:43:37 -05:00 • committed by CJ van den Berg
parent 5eedc17542
commit e837a66b97
10 changed files with 318 additions and 243 deletions
Download patch file Download diff file Expand all files Collapse all files

84
content/docs/architecture/command.smd
View file

@ -4,32 +4,36 @@
.author = "Igor Támara",
.layout = "tutorial.shtml",
.draft = false,
.custom = { .githubedit = "https://github.com/neurocyte/flow-website/tree/master/content/docs/architecture/command.md"},
.custom = {
.githubedit = "/docs/architecture/command.smd",
.codepath = "src/tui/editor.zig",
},
---
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.
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.
[]($section.id('notes'))
## 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
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.
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.
[]($section.id('creating'))
## Understanding and creating commands
A command is a function with a type like
@ -45,8 +49,8 @@ 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.
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
@ -54,6 +58,7 @@ repetition parameter, targeting vim, emacs and helix modes. As you dig in,
there might be particularities on the parameters accepted for a given
command.
[]($section.id('calling'))
## Invoking another command
Commands can be bound to mnemonics in modes by convention. For example, in
@ -71,6 +76,7 @@ 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.
[]($section.id('tldr'))
## Chaining commands
Chaining commands is also common, and, by the way, swift. This is a sample
@ -87,10 +93,12 @@ 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
[]($section.id('deepen'))
## 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.
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
@ -102,20 +110,40 @@ pub fn select_to_char_left_helix(_: *void, ctx: Ctx) Result {
}
```
## Sending parameters to commands
[]($section.id('command_arguments'))
### 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.
to commands vary for each command.
The command `goto_line`, which receives as parameter an integer(in the case
of vim and helix mode, you first type the number and then the action, gg)
as stated in its meta:
```zig
pub const goto_line_meta: Meta = .{ .arguments = &.{.integer} };
```
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
and to actually receiving the integer parameter:
```zig
pub fn goto_line(self: *Self, ctx: Context) Result {
var line: usize = 0;
if (!try ctx.args.match(.{tp.extract(&line)}))
return error.InvalidGotoLineArgument;
```
[]($section.id('next'))
## Next steps
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).
* [Add tests](/docs/testing) to harden your code
* [Back to architecture](/docs/architecture)