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

refactor: Better anchor linking for toc

Browse source
This commit is contained in:
Igor Támara 2025-11-07 23:24:38 -05:00 • committed by CJ van den Berg
parent a239b2b5f2
commit 3b93f62ccd
8 changed files with 70 additions and 130 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -15,8 +15,7 @@ present in `editor`, `tui`, `mode` and `minimodes`, it's possible to
find commands in other places, which will become evident when the need find commands in other places, which will become evident when the need
arises. arises.
[]($section.id('notes')) ## Prev[ious notes]($section.id('notes'))
## Previous notes
Note: Flow is programmed with [zig](https://ziglang.org/), if you are Note: Flow is programmed with [zig](https://ziglang.org/), if you are
familiar with C, C++, Rust, there are differences and reasonings that familiar with C, C++, Rust, there are differences and reasonings that
@ -36,8 +35,7 @@ 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 with a keybinding that can help in the task you are aiming at before
developing flow itself. developing flow itself.
[]($section.id('creating')) ## [Understanding and creating commands]($section.id('creating'))
## Understanding and creating commands
A command is a function with a type like A command is a function with a type like
@ -61,8 +59,7 @@ constitutes a repetition parameter, targeting vim, emacs and helix
modes. As you dig in, there might be particularities on the parameters modes. As you dig in, there might be particularities on the parameters
accepted for a given command. accepted for a given command.
[]($section.id('calling')) ## [Invoking another command]($section.id('calling'))
## Invoking another command
Commands can be bound to mnemonics in modes by convention. For example, 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. in Vim Mode `vim.zig`, `q` corresponds to (quit), the most famous one.
@ -79,8 +76,7 @@ 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 the `quit` command defined in `editor.zig`. `cmd` takes care of routing
and finding the command wherever it is defined. and finding the command wherever it is defined.
[]($section.id('tldr')) ## [Chaining commands]($section.id('tldr'))
## Chaining commands
Chaining commands is also common, and, by the way, swift. This is a Chaining commands is also common, and, by the way, swift. This is a
sample of applying first `save_file` command and then, the command sample of applying first `save_file` command and then, the command
@ -99,8 +95,7 @@ sent to commands vary for each command.
Sometimes [keybinding](/docs/architecture/keybind) is enough to Sometimes [keybinding](/docs/architecture/keybind) is enough to
accomplish a compound of already present commands. accomplish a compound of already present commands.
[]($section.id('command_arguments')) ### [Sending parameters to commands]($section.id('command_arguments'))
### Sending parameters to commands
`goto_line` (in the case of vim and helix mode, you first type the `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 number and then the action, `gg`) is a command that exemplifies
@ -146,8 +141,7 @@ A deeper explanation of the rules about parameter passing is exposed in
that parameters can be sent not only to commands, but other broader that parameters can be sent not only to commands, but other broader
use cases. use cases.
[]($section.id('deepen')) ## [Code organization]($section.id('deepen'))
## Code organization
Is common to define private functions in a given module meant to be Is common to define private functions in a given module meant to be
invoked from commands. As usual, reusing code with functions invoked from commands. As usual, reusing code with functions
@ -164,8 +158,7 @@ pub fn select_to_char_left_helix(_: *void, ctx: Ctx) Result {
} }
``` ```
[]($section.id('next')) ## [Next steps]($section.id('next'))
## Next steps
[Minimodes](/docs/architecture/minimode) pass arguments to the editor, [Minimodes](/docs/architecture/minimode) pass arguments to the editor,
if you wonder how to go beyond the current buffer window, when there if you wonder how to go beyond the current buffer window, when there

31
content/docs/architecture/index.smd
View file

@ -22,8 +22,7 @@ in deepwiki. Do not hesitate to ask in the channels and
[open a PR](https://github.com/neurocyte/flow-website/pulls) to improve [open a PR](https://github.com/neurocyte/flow-website/pulls) to improve
anything. anything.
[]($section.id("internals")) ## [Internals]($section.id("internals"))
## Internals
The foundational unit is the `Buffer` that holds the document in memory; The foundational unit is the `Buffer` that holds the document in memory;
there might be various opened files, each one loaded in a buffer. there might be various opened files, each one loaded in a buffer.
@ -41,8 +40,7 @@ hierarchy, interact with lsp and git. When flow is opened, only one
active project is loaded in the current session. The `Project Manager` active project is loaded in the current session. The `Project Manager`
offers services around the set of projects. offers services around the set of projects.
[]($section.id("commands")) ## [Editor commands and modes]($section.id("commands"))
## Editor commands and modes
When a buffer is active, it has an Editor When a buffer is active, it has an Editor
attached to it; an editor might have associated tree-sitter support, attached to it; an editor might have associated tree-sitter support,
@ -58,8 +56,7 @@ possible to create a nano mode with just keybindings. In the other hand,
`Vim` and [Helix](/docs/mode/helix) modes have particular definitions `Vim` and [Helix](/docs/mode/helix) modes have particular definitions
for commands that interact with the buffers, being modal editors. for commands that interact with the buffers, being modal editors.
[]($section.id("tui")) ## [Text user interface]($section.id("tui"))
## Text user interface
`Tui` governs it all offering support for `Tui` governs it all offering support for
[palettes](/docs/architecture/palette) that are known in other [palettes](/docs/architecture/palette) that are known in other
@ -71,15 +68,14 @@ that receive more keypresses to offer additional functionality, such
as finding in files, finding in the current buffer, open files as finding in files, finding in the current buffer, open files
and replacing a character. and replacing a character.
[]($section.id("oses"))
## Operating systems and UI ## [Operating systems and UI]($section.id("oses"))
[libvaxis](https://github.com/rockorager/libvaxis) is in charge of [libvaxis](https://github.com/rockorager/libvaxis) is in charge of
rendering the text and all the interface in Linux, MacOS, FreeBSD, rendering the text and all the interface in Linux, MacOS, FreeBSD,
and Android via Termux, while in Windows there is an special GUI. and Android via Termux, while in Windows there is an special GUI.
[]($section.id("thespian")) ## [Communication between components]($section.id("thespian"))
## Communication between components
[Thespian](https://github.com/neurocyte/thespian) is in charge of [Thespian](https://github.com/neurocyte/thespian) is in charge of
processes synchronization and allows sending processes synchronization and allows sending
@ -93,22 +89,19 @@ operations they perform, integration with git and running a `shell`
command via a `task` all are coordinated thanks to the infrastructure command via a `task` all are coordinated thanks to the infrastructure
that Thespian provides. that Thespian provides.
[]($section.id("languages")) ## [Programming languages support]($section.id("languages"))
## Programming languages support
There are plenty of programming languages that use tree-sitter via There are plenty of programming languages that use tree-sitter via
[flow-syntax](https://github.com/neurocyte/flow-syntax) and whose [flow-syntax](https://github.com/neurocyte/flow-syntax) and whose
language servers and formatters are configured via `file_type_lsp`. language servers and formatters are configured via `file_type_lsp`.
Currently one Language Server is supported for each language. Currently one Language Server is supported for each language.
[]($section.id("facilities")) ## [Facilities]($section.id("facilities"))
## Facilities
The clipboard is used for copy, paste operations and there is also The clipboard is used for copy, paste operations and there is also
support to use the system clipboard, copying and pasting to/from it. support to use the system clipboard, copying and pasting to/from it.
[]($section.id("logging")) ### [Logging support]($section.id("logging"))
### Logging support
Logging support offers various levels to give feedback for several Logging support offers various levels to give feedback for several
actions that ease developing Flow itself and also are used to offer actions that ease developing Flow itself and also are used to offer
@ -136,8 +129,7 @@ Log something
logger.print("{} unsaved buffer(s) remaining", .{remaining}); logger.print("{} unsaved buffer(s) remaining", .{remaining});
``` ```
[]($section.id("show_input")) ### [View key presses]($section.id("show_input"))
### View key presses
There are situations when you press some keys without the expected There are situations when you press some keys without the expected
behavior happening, to review if flow is getting the keys, the behavior happening, to review if flow is getting the keys, the
@ -146,8 +138,7 @@ executing the [desired command](/docs/architecture/command), or maybe
your desktop environment or something else is capturing them, you will your desktop environment or something else is capturing them, you will
want to invoke flow with the option `--show-input`. want to invoke flow with the option `--show-input`.
[]($section.id("next")) ## [Next steps]($section.id("next"))
## Next steps
* [Configure some keybinds](/docs/architecture/keybind) * [Configure some keybinds](/docs/architecture/keybind)
* [Guidelines for contributions](/docs/contributing) * [Guidelines for contributions](/docs/contributing)

15
content/docs/architecture/inner_data_exchange.smd
View file

@ -25,8 +25,7 @@ management is provided by
This chapter describes the mechanisms that flow has to pass arguments This chapter describes the mechanisms that flow has to pass arguments
between components. between components.
[]($section.id('libraries')) ## [Library usage]($section.id('libraries'))
## Library usage
* The Thespian library sends and receives `thespian.message` values, * The Thespian library sends and receives `thespian.message` values,
which are strongly typed, but schema free CBOR encoded structures. which are strongly typed, but schema free CBOR encoded structures.
@ -61,9 +60,7 @@ data, more samples on using cbor can be seen in
For example, when interacting with the clipboard, the messages sent are For example, when interacting with the clipboard, the messages sent are
multiple chunks of information, multiple chunks of information,
## [Buffer scoping]($section.id('scoping'))
[]($section.id('scoping'))
## Buffer scoping
CBOR structures are mostly stored in a way that avoids allocation CBOR structures are mostly stored in a way that avoids allocation
entirely. This is really fast, but requires that you always know where entirely. This is really fast, but requires that you always know where
@ -105,16 +102,14 @@ came from.
original CBOR data and will be invalidated implicitly when the CBOR original CBOR data and will be invalidated implicitly when the CBOR
buffer they came from is invalidated/overwritten. buffer they came from is invalidated/overwritten.
[]($section.id('next')) ## [Next steps]($section.id('next'))
## Next steps
* [Commands](/docs/architecture/command) * [Commands](/docs/architecture/command)
* [Minimodes](/docs/architecture/minimode) * [Minimodes](/docs/architecture/minimode)
* [Architecture](/docs/architecture) * [Architecture](/docs/architecture)
[]($section.id('more')) ## [More information]($section.id('more'))
## More information
* [Deepwiki on cbor](https://deepwiki.com/neurocyte/cbor) * [Deepwiki on cbor](https://deepwiki.com/neurocyte/cbor)
* [Samples of cbor usage](https://github.com/neurocyte/cbor/blob/master/test/tests.zig) * [Samples of cbor usage](https://github.com/neurocyte/cbor/blob/master/test/tests.zig)
* [Deepwiki on thespian](https://deepwiki.com/neurocyte/thespian) * [Deepwiki on thespian](https://deepwiki.com/neurocyte/thespian)

21
content/docs/architecture/keybind.smd
View file

@ -30,8 +30,7 @@ and the different [imodes](#hierarchy) present.
Command palette can also be reached left clicking on the current Command palette can also be reached left clicking on the current
mode in the status bar. mode in the status bar.
[]($section.id('tldr')) ## [;TLDR;]($section.id('tldr'))
## ;TLDR;
Once you open the corresponding json file, locate inside the Once you open the corresponding json file, locate inside the
[imode](#hierarchy)(internal mode) that will accept the key or [imode](#hierarchy)(internal mode) that will accept the key or
@ -46,16 +45,14 @@ like in
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. state derived from a wrong mapping of key combinations, read on.
[]($section.id('defaults')) ## [Resetting keys to factory defaults]($section.id('defaults'))
## Resetting keys to factory defaults
User configured keybindings are stored in Flow's configuration directory User configured keybindings are stored in Flow's configuration directory
under `keys/mode.json` where mode can be `flow`, `emacs`, `vim`, `helix` under `keys/mode.json` where mode can be `flow`, `emacs`, `vim`, `helix`
or customized ones. Removing the keys directory or the particular mode or customized ones. Removing the keys directory or the particular mode
file can take you out from a broken state. file can take you out from a broken state.
[]($section.id('modes')) ## [Keybinds for each mode]($section.id('modes'))
## Keybinds for each mode
Keybinds are edited per mode, and other modes inherit what is defined Keybinds are edited per mode, and other modes inherit what is defined
in your `flow.json` keybindings. Each mode override keybindings of its in your `flow.json` keybindings. Each mode override keybindings of its
@ -66,8 +63,7 @@ flow, and the default ones defined for emacs mode.
[introducing keybindings](/devlog/2024#2024-12-05T20:55:00) showcases [introducing keybindings](/devlog/2024#2024-12-05T20:55:00) showcases
how to get to edit keybindings. how to get to edit keybindings.
[]($section.id('hierarchy')) ## [Keybindings hierarchy]($section.id('hierarchy'))
## Keybindings hierarchy
Some terminology Some terminology
@ -134,8 +130,7 @@ and other modes inherit from it. Each mode inherits, extends and
overrides actions and define their internal imodes extending as overrides actions and define their internal imodes extending as
required each minimode. required each minimode.
[]($section.id('adding')) ## [Adding a Keybinding]($section.id('adding'))
## Adding a Keybinding
The most basic case to map a keybind to a command was covered in The most basic case to map a keybind to a command was covered in
[TLDR](#tldr) which used the combination of three keys pressed [TLDR](#tldr) which used the combination of three keys pressed
@ -146,8 +141,7 @@ A common use case is to add a keybinding to invoke an already existing
command and chain it to another, making Flow more suited to your own command and chain it to another, making Flow more suited to your own
needs. needs.
[]($section.id('shell')) ## [Running shell commands]($section.id('shell'))
## Running shell commands
For example, `f5` by default is used to run `zig build test` outputting For example, `f5` by default is used to run `zig build test` outputting
its results to a *scratch buffer* called `test`. its results to a *scratch buffer* called `test`.
@ -190,8 +184,7 @@ want to remap `f5` to a different shell command.
Observe [tasks running](/devlog/2025#2025-01-26T22:11:00) and maybe Observe [tasks running](/devlog/2025#2025-01-26T22:11:00) and maybe
consider using more keybindings or running tasks for your projects. consider using more keybindings or running tasks for your projects.
[]($section.id('next')) ## [Next steps]($section.id('next'))
## Next steps
If you realized that there is a handy combination that others can 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 benefit from or that a mode lacks the combination and it might be

18
content/docs/architecture/minimode.smd
View file

@ -16,8 +16,7 @@ action, i.e. find something in the current buffer or in project files,
open/save a file, and, in modal modes(like vim and helix), as receiving open/save a file, and, in modal modes(like vim and helix), as receiving
a number as a prefix to repeat an action many times. a number as a prefix to repeat an action many times.
[]($section.id("anatomy")) ## [Anatomy of minimodes]($section.id("anatomy"))
## Anatomy of minimodes
To create a minimode it's needed: To create a minimode it's needed:
@ -25,8 +24,7 @@ To create a minimode it's needed:
* An Action mapping * An Action mapping
* A Minimode definition * A Minimode definition
[]($section.id("keybind")) ### [Keybinding]($section.id("keybind"))
### Keybinding
When a key or a keystroke(set of keys) are pressed, the associated When a key or a keystroke(set of keys) are pressed, the associated
minimode gets activated and will start to capture the key/strokes minimode gets activated and will start to capture the key/strokes
@ -35,8 +33,7 @@ the minimode. Head to `src/keybind/builtin/flow.json`(flow keybinds)
and look for `mini_find`, where you will know which specific actions and look for `mini_find`, where you will know which specific actions
are triggered by the keybindings of the `find` minimode. are triggered by the keybindings of the `find` minimode.
[]($section.id("mapping")) ### [Action mapping]($section.id("mapping"))
### Action mapping
Actions executed by each minimode are stored one per file under Actions executed by each minimode are stored one per file under
`src/tui/mode/mini/`. The command that opens the door to the minimode `src/tui/mode/mini/`. The command that opens the door to the minimode
@ -46,8 +43,7 @@ when needed.
Look for `mini` inside `tui.zig` to find out which minimodes are present Look for `mini` inside `tui.zig` to find out which minimodes are present
and where to look, to learn how each minimode does its own task. and where to look, to learn how each minimode does its own task.
[]($section.id("definition")) ### [Minimode definition]($section.id("definition"))
### Minimode definition
Possibly the simplest minimode that does not require defining a Possibly the simplest minimode that does not require defining a
particular widget is the `replace` minimode, used in particular widget is the `replace` minimode, used in
@ -99,16 +95,14 @@ All the keys were handled and managed by the default "invisible" widget
that processes the keys for the minimode. And there is room for custom that processes the keys for the minimode. And there is room for custom
widgets. widgets.
[]($section.id("custom_widgets")) ## [A custom widget]($section.id("custom_widgets"))
## A custom widget
When there is a need for an specialized widget, it's possible to When there is a need for an specialized widget, it's possible to
define one, for example, the `file_browser` is used to load and define one, for example, the `file_browser` is used to load and
save files, and `numeric_input` is used to set the tab width for save files, and `numeric_input` is used to set the tab width for
example(look for it in the command palette `:`). example(look for it in the command palette `:`).
[]($section.id("next")) ## [Next steps]($section.id("next"))
## Next steps
* Create [palettes](/docs/architecture/palette) * Create [palettes](/docs/architecture/palette)
* Review [commands](/docs/architecture/command) * Review [commands](/docs/architecture/command)

21
content/docs/architecture/palette.smd
View file

@ -30,8 +30,7 @@ To get the most of this section, it's recommended to have read about
[commands](/docs/architecture/command), and optionally, [commands](/docs/architecture/command), and optionally,
[minimodes](/docs/architecture/minimode). [minimodes](/docs/architecture/minimode).
[]($section.id("anatomy")) ## [Defining the palette]($section.id("anatomy"))
## Defining the palette
Palettes are under `tui/overlay` and use the facilities offered by Palettes are under `tui/overlay` and use the facilities offered by
`palette.zig` to perform all the operations. `palette.zig` to perform all the operations.
@ -45,8 +44,7 @@ options to execute an action on the given selection. To maintain as
readable as possible the code and thus extensible, the data to be used readable as possible the code and thus extensible, the data to be used
should be prepared previously. should be prepared previously.
[]($section.id("basic")) ### [Fields]($section.id("basic"))
### Fields
Basic fields that give hints to the user and need to be set are: Basic fields that give hints to the user and need to be set are:
@ -57,8 +55,7 @@ pub const description = "clipboard";
pub const icon = " "; pub const icon = " ";
``` ```
[]($section.id("entries")) ### [Defining the list of elements in the palette]($section.id("entries"))
### Defining the list of elements in the palette
`load_entries` is in charge of populating the visible entries, each one `load_entries` is in charge of populating the visible entries, each one
with an index. with an index.
@ -87,8 +84,7 @@ try palette.menu.add_item_with_handler(value, select);
Which will apply the `select` function when the value is selected. Which will apply the `select` function when the value is selected.
[]($section.id("select")) ### [Acting on selection]($section.id("select"))
### Acting on selection
When the selection happens, it is time to invoke the command with the When the selection happens, it is time to invoke the command with the
selection making sure to close the palette. Those actions will be selection making sure to close the palette. Those actions will be
@ -102,8 +98,7 @@ Other common operations in the palettes can be inspected looking at the
source code of the palettes, all of them import `palette.zig`. Once the source code of the palettes, all of them import `palette.zig`. Once the
palette is ready, it's time to make the palette available as a command. palette is ready, it's time to make the palette available as a command.
[]($section.id("register")) ## [Registering the palette]($section.id("register"))
## Registering the palette
Commands that open the palette are defined in `tui.zig` in a similar way Commands that open the palette are defined in `tui.zig` in a similar way
it is done with [minimodes](/docs/architecture/minimode). We have got it is done with [minimodes](/docs/architecture/minimode). We have got
@ -113,9 +108,9 @@ you covered if in doubt about
To view a complete implementation of a palette, take a look at To view a complete implementation of a palette, take a look at
[clipboard history palette commit](https://github.com/neurocyte/flow/commit/634a18cb5685a3c3fcfc08301306e628d33c3256) [clipboard history palette commit](https://github.com/neurocyte/flow/commit/634a18cb5685a3c3fcfc08301306e628d33c3256)
[]($section.id("next")) ## [Next steps]($section.id("next"))
## Next steps
* [Minimodes](/docs/architecture/minimode) * [Minimodes](/docs/architecture/minimode)
* [On commands](/docs/architecture/command) * [On commands](/docs/architecture/command)
* [Architecture](/docs/architecture) * [Exchanging messages](/docs/architecture/inner_data_exchange)
* [Architecture](/docs/architecture)

32
content/docs/contributing.smd
View file

@ -1,6 +1,6 @@
--- ---
.title = "Contributing", .title = "Contributing",
.date = @date("2025-07-06T00:00:00"), .date = @date("2025-11-06T00:00:00"),
.author = "Igor Támara", .author = "Igor Támara",
.layout = "tutorial.shtml", .layout = "tutorial.shtml",
.draft = false, .draft = false,
@ -9,8 +9,7 @@
} }
--- ---
[]($section.id("request")) ## [Asking for a feature]($section.id("request"))
## Asking for a feature
Please [open an issue](https://github.com/neurocyte/flow/issues) that Please [open an issue](https://github.com/neurocyte/flow/issues) that
explains what is the requirement, being as descriptive as explains what is the requirement, being as descriptive as
@ -21,8 +20,7 @@ more information. At the end, the issues in github have more
chance to get developed, given that there are plenty of things chance to get developed, given that there are plenty of things
to do for this kind of software. to do for this kind of software.
[]($section.id("issues")) ## [Reporting a problem]($section.id("issues"))
## Reporting a problem
If you discover a problem, or unexpected behaviour, feel free to join If you discover a problem, or unexpected behaviour, feel free to join
[Discord](https://discord.com/invite/4wvteUPphx) to check if there is [Discord](https://discord.com/invite/4wvteUPphx) to check if there is
@ -41,8 +39,7 @@ Issues later on are tagged with proposed version to solve them, in case
of low hanging fruit, it's possible that it can be solved pretty of low hanging fruit, it's possible that it can be solved pretty
quick. quick.
[]($section.id("showcase")) ## [Help others and share your workflows]($section.id("showcase"))
## Help others and share your workflows
We are happy when you [share your workflows](https://discord.gg/XeYatDhh) We are happy when you [share your workflows](https://discord.gg/XeYatDhh)
or when someone asks something and gets a helpful answer, for example, a or when someone asks something and gets a helpful answer, for example, a
@ -55,8 +52,8 @@ making blog entries and sharing with others what you can build or achieve
with flow; battle testing flow on daily basis helps its improvement and with flow; battle testing flow on daily basis helps its improvement and
bring ideas from other places too. bring ideas from other places too.
[]($section.id("developing"))
## Developing ## [Developing]($section.id("developing"))
[Flow Control](https://flow-control.dev/) is programmed with [Flow Control](https://flow-control.dev/) is programmed with
[zig](https://ziglang.org/). [zig](https://ziglang.org/).
@ -76,8 +73,7 @@ agreements or find guidance.
This [summary](/docs/architecture) can help on getting started to This [summary](/docs/architecture) can help on getting started to
follow the codebase. follow the codebase.
[]($section.id("coding_style")) ### [Coding style]($section.id("coding_style"))
### Coding style
Please follow what you see in the source code for functions, Structs, Please follow what you see in the source code for functions, Structs,
variables, const names, etc... Functions have descriptive names to variables, const names, etc... Functions have descriptive names to
@ -90,8 +86,8 @@ inaccurate in this doc or others, do open an issue or jump to
[Discord](https://discord.com/invite/4wvteUPphx) and comment, it's [Discord](https://discord.com/invite/4wvteUPphx) and comment, it's
valid to [improve too](https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd"). valid to [improve too](https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd").
[]($section.id("commits"))
### Commit comments ### [Commit comments]($section.id("commits"))
It's better to use commits for different purposes, even if they look It's better to use commits for different purposes, even if they look
small and there is a temptation to include on the same new code, fixes small and there is a temptation to include on the same new code, fixes
@ -110,8 +106,8 @@ clearer for future readers and committers.
* `fix:` When something changed to a more expected behaviour. * `fix:` When something changed to a more expected behaviour.
* `build`: the commit doesn't change code at all. * `build`: the commit doesn't change code at all.
[]($section.id("testing"))
### Testing ### [Testing]($section.id("testing"))
It's possible that the test set grows as the project evolves, given It's possible that the test set grows as the project evolves, given
that the amount of relationships among components increase the that the amount of relationships among components increase the
@ -119,8 +115,7 @@ opportunity to generate regressions. If you are new to zig a good
place to start to learn about the codebase is place to start to learn about the codebase is
[adding some tests](/docs/testing) [adding some tests](/docs/testing)
[]($section.id("resources")) ## [Resources]($section.id("resources"))
## Resources
* [nerd fonts cheatsheet](https://www.nerdfonts.com/cheat-sheet): When * [nerd fonts cheatsheet](https://www.nerdfonts.com/cheat-sheet): When
icons are needed, you can look for them. icons are needed, you can look for them.
@ -129,8 +124,7 @@ to trace some messages.
* [showing key-presses](/docs/architecture#show_input): When the keyboard * [showing key-presses](/docs/architecture#show_input): When the keyboard
don't seem to work. don't seem to work.
[]($section.id("next")) ## [Next steps]($section.id("next"))
## Next steps
* [Join Discord](https://discord.com/invite/4wvteUPphx) * [Join Discord](https://discord.com/invite/4wvteUPphx)
* [Fill an issue](https://github.com/neurocyte/flow/issues) * [Fill an issue](https://github.com/neurocyte/flow/issues)

41
content/docs/testing.smd
View file

@ -24,8 +24,7 @@ To work with tests you will need to:
Flow tests are placed in the directory `test`. Flow tests are placed in the directory `test`.
[]($section.id("running_tests")) ## [Running the tests]($section.id("running_tests"))
## Running the tests
To run the full set of tests, inside flow, use `f5`, which runs a task that To run the full set of tests, inside flow, use `f5`, which runs a task that
invokes: invokes:
@ -37,8 +36,7 @@ zig build test
it will work if flow was invoked from the project root, which is the same it will work if flow was invoked from the project root, which is the same
place that you would normally run the tests when on the terminal. place that you would normally run the tests when on the terminal.
[]($section.id("running_a_test")) ### [Run a particular test]($section.id("running_a_test"))
### Run a particular test
To run an specific test use `Dtest-filter` option with the name of your To run an specific test use `Dtest-filter` option with the name of your
test, i.e., for the test called **test_block_name** use: test, i.e., for the test called **test_block_name** use:
@ -47,8 +45,7 @@ test, i.e., for the test called **test_block_name** use:
zig build test -Dtest-filter="test_block_name" zig build test -Dtest-filter="test_block_name"
``` ```
[]($section.id("first_test")) ## [Adding tests]($section.id("first_test"))
## Adding tests
Tests are needed when: Tests are needed when:
@ -68,8 +65,7 @@ additional functions to make the tests readable and extendable though.
public functions are straightforward tested, while there are some public functions are straightforward tested, while there are some
conventions for testing private functions. conventions for testing private functions.
[]($section.id("private_functions_testing")) ### [Testing private functions]($section.id("private_functions_testing"))
### Testing private functions
Some internal logic of a module can be tested without the need to be Some internal logic of a module can be tested without the need to be
exposed to other modules. exposed to other modules.
@ -111,8 +107,7 @@ try helix.test_internal.move_cursor_long_word_right_end(root, cursor, the_metric
In case there is need of a new test file for concern separation, continue In case there is need of a new test file for concern separation, continue
to the next section. to the next section.
[]($section.id("new_test_file")) ## [Adding a new test file]($section.id("new_test_file"))
## Adding a new test file
Three steps are required for adding a new test file: Three steps are required for adding a new test file:
@ -121,8 +116,7 @@ Three steps are required for adding a new test file:
1. Optionally, make available a module to the build system 1. Optionally, make available a module to the build system
for your particular test for your particular test
[]($section.id("create_test_file")) ### [Create the test file]($section.id("create_test_file"))
### Create the test file
Place your test file under `test` directory, the name should be prefixed Place your test file under `test` directory, the name should be prefixed
with `tests_`. with `tests_`.
@ -130,8 +124,7 @@ with `tests_`.
For the rest of this section we will use as a sample For the rest of this section we will use as a sample
`tests_project_manager.zig`. `tests_project_manager.zig`.
[]($section.id("linking_tests")) ### [Include the test file]($section.id("linking_tests"))
### Include the test file
Tests files are linked via `test/tests.zig`, import your new test_file Tests files are linked via `test/tests.zig`, import your new test_file
alphabetically as in our sample: alphabetically as in our sample:
@ -140,8 +133,7 @@ alphabetically as in our sample:
pub const project_manager = @import("tests_project_manager.zig"); pub const project_manager = @import("tests_project_manager.zig");
``` ```
[]($section.id("import_in_build_zig")) ### [Import required modules when building tests]($section.id("import_in_build_zig"))
### Import required modules when building tests
In `build.zig` import the required module under `tests.root_module`, for In `build.zig` import the required module under `tests.root_module`, for
the current example: the current example:
@ -153,21 +145,16 @@ tests.root_module.addImport("project_manager", project_manager_mod);
[Sample](https://github.com/neurocyte/flow/commit/e053a0dcf4b4c93f1ce1fe6d14a3c04e886d393c) [Sample](https://github.com/neurocyte/flow/commit/e053a0dcf4b4c93f1ce1fe6d14a3c04e886d393c)
of adding a new test file for project manager. of adding a new test file for project manager.
[]($section.id("faq")) ## [FAQ on tests]($section.id("faq"))
## FAQ on tests
[]($section.id("import_editor")) ### [I need to test something that requires importing the editor ¿What do I do?]($section.id("import_editor"))
### I need to test something that requires importing the editor ¿What
do I do?
There are two paths from here: There are two paths from here:
1. Refactor your code to test the lower level functions 1. Refactor your code to test the lower level functions
1. Extend the tests to automate via external tools 1. Extend the tests to automate via external tools
### [Refactor to test lower level functions]($section.id("lower_level"))
[]($section.id("lower_level"))
### Refactor to test lower level functions
Refactor the functions involved in the functionality to make them Refactor the functions involved in the functionality to make them
not rely directly with editor and other higher level components, and not rely directly with editor and other higher level components, and
@ -194,8 +181,7 @@ The group of functions `beyond_eol` can be seen in
and whose tests are and whose tests are
[here](https://github.com/neurocyte/flow/pull/330/commits/38a08aed49f4fbba18aab9ccbd3c8b9758414221). [here](https://github.com/neurocyte/flow/pull/330/commits/38a08aed49f4fbba18aab9ccbd3c8b9758414221).
[]($section.id("end_to_end")) ### [Use additional tools to test a running flow session]($section.id("end_to_end"))
### Use additional tools to test a running flow session
Use additional tools to invoke the built editor and send keys to Use additional tools to invoke the built editor and send keys to
it, modify a file and then compare the initial contents of the file it, modify a file and then compare the initial contents of the file
@ -204,8 +190,7 @@ and the resulting contents of your file and the expected ones.
If in doubt about how to do something, If in doubt about how to do something,
[please ask](https://discord.com/invite/4wvteUPphx). [please ask](https://discord.com/invite/4wvteUPphx).
[]($section.id("next")) ## [Next steps]($section.id("next"))
## Next steps
* [How to contribute](/docs/contributing) * [How to contribute](/docs/contributing)
* [Personalizing keybindings](/docs/architecture/keybind) * [Personalizing keybindings](/docs/architecture/keybind)