From 948328bcd0a3411a7976633fd7c1fdf3af3df809 Mon Sep 17 00:00:00 2001 From: CJ van den Berg Date: Thu, 1 Aug 2024 18:10:05 +0200 Subject: [PATCH] docs: update readme and help --- README.md | 52 ++++++++++++------------ help.md | 31 +++++++------- src/tui/mode/input/flow.zig | 4 +- src/tui/mode/input/home.zig | 10 ++--- src/tui/mode/input/vim/insert.zig | 4 +- src/tui/mode/input/vim/normal.zig | 6 +-- src/tui/mode/input/vim/visual.zig | 6 +-- src/tui/mode/overlay/command_palette.zig | 8 ++-- src/tui/mode/overlay/open_recent.zig | 8 ++-- 9 files changed, 62 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 1702bb8..7393442 100644 --- a/README.md +++ b/README.md @@ -6,37 +6,23 @@ and is my daily driver for most things coding related. https://github.com/neurocyte/flow/assets/1552770/97aae817-c209-4c08-bc65-0a0bf1f2d4c6 # Requirements -- A modern terminal with 24bit color and kitty keyboard protocol support. Kitty, Foot - and Ghostty are the only recommended terminals at this time. Most other terminals +- A modern terminal with 24bit color and, ideally, kitty keyboard protocol support. Kitty, + Foot and Ghostty are the only recommended terminals at this time. Most other terminals will work, but with reduced functionality. -- NerdFonts support -- Linux, MacOS, (somewhat experimental) Windows, Android (Termux) or FreeBSD. Other BSDs - probably work too, but nobody has tried it yet. -- A UTF-8 locale (very important!) +- NerdFont support. Either via terminal font fallback or a patched font. +- Linux, MacOS, Windows, Android (Termux) or FreeBSD. +- A UTF-8 locale # Building Make sure your system meets the requirements listed above. -Flow tracks zig master most of the time. Build with: +Flow builds with zig 0.13 at this time. Build with: ```shell zig build -Doptimize=ReleaseFast ``` -Sometimes zig master may introduce breaking changes and Flow may take a few days to -catch up. In that case there is a simple zig wrapper script provided that will download -and build with the last known compatible version of zig. The version is stored in -`build.zig.version`. - -Build with the zig wrapper: -```shell -./zig build -Doptimize=ReleaseFast -``` - -The zig wrapper places the downloaded zig compiler in the `.cache` directory and does -not touch your system. It requires `bash`, `curl` and `jq` to run. - Thanks to Zig you may also cross-compile from any host to pretty much any target. For example: @@ -48,7 +34,7 @@ zig build -Doptimize=ReleaseFast -Dtarget=aarch64-linux-musl --prefix zig-out/aa # Running Flow Control -The output binary is: +The binary is: ```shell zig-out/bin/flow @@ -60,7 +46,13 @@ Place it in your path for convenient access: sudo cp zig-out/bin/flow /usr/local/bin ``` -Flow Control is a single statically linked binary. No further runtime is required. +Or if you prefer, let zig install it in your home directory: + +```shell +zig build -Doptimize=ReleaseFast --prefix ~/.local +``` + +Flow Control is a single statically linked binary. No further runtime files are required. You may install it on another system by simply copying the binary. ```shell @@ -68,11 +60,12 @@ scp zig-out/bin/flow root@otherhost:/usr/local/bin ``` Configuration is mostly dynamically maintained with various commands in the UI. -It stored under the standard user configuration path. Usually `~/.config/flow`. -(%APPDATA%\Roaming\flow on Windows) +It is stored under the standard user configuration path. Usually `~/.config/flow` +on Linux. %APPDATA%\Roaming\flow on Windows. Somewhere magical on MacOS Logs, traces and per-project most recently used file lists are stored in the -standard user runtime cache directory. Usually `~/.cache/flow`. +standard user application state directory. Usually `~/.local/state/flow` on +Linux and %APPDATA%\Roaming\flow on Windows. Files to load may be specifed on the command line: @@ -80,6 +73,9 @@ Files to load may be specifed on the command line: flow fileA.zig fileB.zig ``` +The last file will be opened and the previous files will be placed in reverse +order at the top of the recent files list. Switch to recent files with Ctrl-e. + Common target line specifiers are supported too: ```shell @@ -98,6 +94,8 @@ Use the --language option to force the file type of a file: flow --language bash ~/.bash_profile ``` +Show supported language names with `--list-languages`. + See `flow --help` for the full list of command line options. # Terminal configuration @@ -126,11 +124,11 @@ For Ghostty each conflicting binding has to be reconfigured individually. - theme support (compatible with vscode themes via the flow-themes project) - infinite undo/redo (at least until you run out of ram) - stuff I've forgotten to mention... +- find in files +- command palette # Features in progress (aka, the road to 1.0) - completion UI/LSP support for completion -- find in files -- command palette - persistent undo/redo - file watcher for auto reload diff --git a/help.md b/help.md index ba97eff..d76e8bd 100644 --- a/help.md +++ b/help.md @@ -30,8 +30,7 @@ settings) is persisted in the configuration file automatically. - F2 => Cycle major input modes (flow, vim, ...) -The current input mode Input mode is displayed in the `modestatus` -widget at the left side of the statusbar. +The current input mode is displayed in the at the left side of the statusbar. ## Flow mode @@ -70,15 +69,15 @@ cycle style of editing. - Ctrl-t, Ctrl-b => Enter move to next/previous character mode -- Ctrl-n, Ctrl-p, F3, Shift-F3, Alt-n, Alt-p => +- Ctrl-n, Ctrl-p, F3, Shift-F3 => Goto next/previous match - Ctrl-l => - Scroll cursor to center of screen, cycle cursor to - top/bottom of screen + Scroll cursor to center of screen. Press again to cycle the cursor to + the top/bottom/center of the screen - MouseLeft => - Clear all cursors and selections and place cursor at mouse pointer + Clear all cursors and selections and the place cursor at the mouse pointer - MouseWheel => Scroll @@ -116,7 +115,7 @@ cycle style of editing. Select word under cursor, or add cursor at next match (see Multi Cursor Commands) -- Ctrl-Space => +- Ctrl-Shift-Space => Reverse selection direction - Double-MouseLeft => @@ -204,6 +203,9 @@ cycle style of editing. - Alt-Shift-f => Reformat file or selection +- Alt-u, Alt-l => + Convert the selection or word at cursor to upper/lower case + ### File Commands - Ctrl-s => @@ -213,13 +215,7 @@ cycle style of editing. Open file - Ctrl-e => - Open recent file, repeat for quick select - -- Ctrl-q => - Exit - -- Ctrl-q => - Exit + Open recent file. Repeat for quick select - Ctrl-q => Exit @@ -247,7 +243,8 @@ cycle style of editing. ### Language Server Commands - Alt-n, Alt-p - Goto next/previous diagnostic + Goto the next/previous diagnostic, or if the matching files list is open, + goto the next/previous matching file position. - F12 => Goto definition of symbol at cursor @@ -266,8 +263,8 @@ cycle style of editing. - F7 => Dump current line to log view -- F11, Ctrl-J, Alt-l => - Toggle log view +- F11, Ctrl-J => + Toggle panel view (defaults to log view) - Ctrl-Shift-/ => Dump current widget tree to log view diff --git a/src/tui/mode/input/flow.zig b/src/tui/mode/input/flow.zig index 39c29a5..842e2ca 100644 --- a/src/tui/mode/input/flow.zig +++ b/src/tui/mode/input/flow.zig @@ -382,7 +382,7 @@ const hints = tui.KeybindHints.initComptime(.{ .{ "select_buffer_end", "C-S-end" }, .{ "select_down", "S-down" }, .{ "select_end", "S-end" }, - .{ "selections_reverse", "C-space" }, + .{ "selections_reverse", "C-S-space" }, .{ "select_left", "S-left" }, .{ "select_page_down", "S-pgdn" }, .{ "select_page_up", "S-pgup" }, @@ -404,7 +404,7 @@ const hints = tui.KeybindHints.initComptime(.{ .{ "toggle_input_mode", "F2" }, .{ "toggle_inputview", "A-i" }, .{ "toggle_inspector_view", "F5, C-F5, C-S-i" }, - .{ "toggle_logview", "C-j, F11" }, + .{ "toggle_panel", "C-j, F11" }, .{ "toggle_whitespace", "C-F10" }, .{ "to_lower", "A-l" }, .{ "to_upper", "A-u" }, diff --git a/src/tui/mode/input/home.zig b/src/tui/mode/input/home.zig index d654b2c..9527c73 100644 --- a/src/tui/mode/input/home.zig +++ b/src/tui/mode/input/home.zig @@ -56,7 +56,7 @@ fn mapPress(self: *Self, keypress: u32, modifiers: u32) tp.result { return switch (modifiers) { mod.CTRL => switch (keynormal) { 'F' => self.sheeran(), - 'J' => self.cmd("toggle_logview", .{}), + 'J' => self.cmd("toggle_panel", .{}), 'Q' => self.cmd("quit", .{}), 'W' => self.cmd("quit", .{}), 'O' => self.cmd("enter_open_file_mode", .{}), @@ -70,7 +70,7 @@ fn mapPress(self: *Self, keypress: u32, modifiers: u32) tp.result { 'Q' => self.cmd("quit_without_saving", .{}), 'R' => self.cmd("restart", .{}), 'F' => self.cmd("enter_find_in_files_mode", .{}), - 'L' => self.cmd_async("toggle_logview"), + 'L' => self.cmd_async("toggle_panel"), 'I' => self.cmd_async("toggle_inputview"), '/' => self.cmd("open_help", .{}), else => {}, @@ -80,7 +80,7 @@ fn mapPress(self: *Self, keypress: u32, modifiers: u32) tp.result { else => {}, }, mod.ALT => switch (keynormal) { - 'L' => self.cmd("toggle_logview", .{}), + 'L' => self.cmd("toggle_panel", .{}), 'I' => self.cmd("toggle_inputview", .{}), key.LEFT => self.cmd("jump_back", .{}), key.RIGHT => self.cmd("jump_forward", .{}), @@ -99,7 +99,7 @@ fn mapPress(self: *Self, keypress: u32, modifiers: u32) tp.result { key.F06 => self.cmd("open_config", .{}), key.F09 => self.cmd("theme_prev", .{}), key.F10 => self.cmd("theme_next", .{}), - key.F11 => self.cmd("toggle_logview", .{}), + key.F11 => self.cmd("toggle_panel", .{}), key.F12 => self.cmd("toggle_inputview", .{}), key.UP => self.cmd("home_menu_up", .{}), key.DOWN => self.cmd("home_menu_down", .{}), @@ -148,5 +148,5 @@ const hints = tui.KeybindHints.initComptime(.{ .{ "theme_next", "F10" }, .{ "theme_prev", "F9" }, .{ "toggle_inputview", "F12, A-i, C-S-i" }, - .{ "toggle_logview", "F11, C-j, A-l, C-S-l" }, + .{ "toggle_panel", "F11, C-j, A-l, C-S-l" }, }); diff --git a/src/tui/mode/input/vim/insert.zig b/src/tui/mode/input/vim/insert.zig index 629a1a0..bc6ebc8 100644 --- a/src/tui/mode/input/vim/insert.zig +++ b/src/tui/mode/input/vim/insert.zig @@ -88,7 +88,7 @@ fn mapPress(self: *Self, keypress: u32, egc: u32, modifiers: u32) !void { 'E' => self.cmd("open_recent", .{}), 'U' => self.cmd("move_scroll_page_up", .{}), 'D' => self.cmd("move_scroll_page_down", .{}), - 'J' => self.cmd("toggle_logview", .{}), + 'J' => self.cmd("toggle_panel", .{}), 'Z' => self.cmd("undo", .{}), 'Y' => self.cmd("redo", .{}), 'Q' => self.cmd("quit", .{}), @@ -201,7 +201,7 @@ fn mapPress(self: *Self, keypress: u32, egc: u32, modifiers: u32) !void { key.F07 => self.cmd("dump_current_line", .{}), key.F09 => self.cmd("theme_prev", .{}), key.F10 => self.cmd("theme_next", .{}), - key.F11 => self.cmd("toggle_logview", .{}), + key.F11 => self.cmd("toggle_panel", .{}), key.F12 => self.cmd("goto_definition", .{}), key.F34 => self.cmd("toggle_whitespace", .{}), // C-F10 key.F58 => self.cmd("gutter_mode_next", .{}), // A-F10 diff --git a/src/tui/mode/input/vim/normal.zig b/src/tui/mode/input/vim/normal.zig index ea8b12c..6b13bc3 100644 --- a/src/tui/mode/input/vim/normal.zig +++ b/src/tui/mode/input/vim/normal.zig @@ -95,7 +95,7 @@ fn mapPress(self: *Self, keypress: u32, egc: u32, modifiers: u32) !void { 'O' => self.cmd("jump_back", .{}), 'I' => self.cmd("jump_forward", .{}), - 'J' => self.cmd("toggle_logview", .{}), + 'J' => self.cmd("toggle_panel", .{}), 'Z' => self.cmd("undo", .{}), 'Y' => self.cmd("redo", .{}), 'Q' => self.cmd("quit", .{}), @@ -221,7 +221,7 @@ fn mapPress(self: *Self, keypress: u32, egc: u32, modifiers: u32) !void { key.F07 => self.cmd("dump_current_line", .{}), key.F09 => self.cmd("theme_prev", .{}), key.F10 => self.cmd("theme_next", .{}), - key.F11 => self.cmd("toggle_logview", .{}), + key.F11 => self.cmd("toggle_panel", .{}), key.F12 => self.cmd("goto_definition", .{}), key.F34 => self.cmd("toggle_whitespace", .{}), // C-F10 key.F58 => self.cmd("gutter_mode_next", .{}), // A-F10 @@ -595,7 +595,7 @@ const hints = tui.KeybindHints.initComptime(.{ .{ "toggle_input_mode", "F2" }, .{ "toggle_inputview", "A-i" }, .{ "toggle_inspector_view", "F5, C-F5, C-S-i" }, - .{ "toggle_logview", "C-j, F11" }, + .{ "toggle_panel", "C-j, F11" }, .{ "toggle_whitespace", "C-F10" }, .{ "to_lower", "A-l" }, .{ "to_upper", "A-u" }, diff --git a/src/tui/mode/input/vim/visual.zig b/src/tui/mode/input/vim/visual.zig index c3fe455..c2daf80 100644 --- a/src/tui/mode/input/vim/visual.zig +++ b/src/tui/mode/input/vim/visual.zig @@ -95,7 +95,7 @@ fn mapPress(self: *Self, keypress: u32, egc: u32, modifiers: u32) !void { 'O' => self.cmd("jump_back", .{}), 'I' => self.cmd("jump_forward", .{}), - 'J' => self.cmd("toggle_logview", .{}), + 'J' => self.cmd("toggle_panel", .{}), 'Z' => self.cmd("undo", .{}), 'Y' => self.cmd("redo", .{}), 'Q' => self.cmd("quit", .{}), @@ -219,7 +219,7 @@ fn mapPress(self: *Self, keypress: u32, egc: u32, modifiers: u32) !void { key.F07 => self.cmd("dump_current_line", .{}), key.F09 => self.cmd("theme_prev", .{}), key.F10 => self.cmd("theme_next", .{}), - key.F11 => self.cmd("toggle_logview", .{}), + key.F11 => self.cmd("toggle_panel", .{}), key.F12 => self.cmd("goto_definition", .{}), key.F34 => self.cmd("toggle_whitespace", .{}), // C-F10 key.F58 => self.cmd("gutter_mode_next", .{}), // A-F10 @@ -555,7 +555,7 @@ const hints = tui.KeybindHints.initComptime(.{ .{ "toggle_input_mode", "F2" }, .{ "toggle_inputview", "A-i" }, .{ "toggle_inspector_view", "F5, C-F5, C-S-i" }, - .{ "toggle_logview", "C-j, F11" }, + .{ "toggle_panel", "C-j, F11" }, .{ "toggle_whitespace", "C-F10" }, .{ "to_lower", "A-l" }, .{ "to_upper", "A-u" }, diff --git a/src/tui/mode/overlay/command_palette.zig b/src/tui/mode/overlay/command_palette.zig index aec36f1..f0b4890 100644 --- a/src/tui/mode/overlay/command_palette.zig +++ b/src/tui/mode/overlay/command_palette.zig @@ -209,7 +209,7 @@ fn mapPress(self: *Self, keypress: u32, egc: u32, modifiers: u32) !void { const keynormal = if ('a' <= keypress and keypress <= 'z') keypress - ('a' - 'A') else keypress; return switch (modifiers) { mod.CTRL => switch (keynormal) { - 'J' => self.cmd("toggle_logview", .{}), + 'J' => self.cmd("toggle_panel", .{}), 'Q' => self.cmd("quit", .{}), 'W' => self.cmd("close_file", .{}), 'P' => self.cmd("command_palette_menu_up", .{}), @@ -231,7 +231,7 @@ fn mapPress(self: *Self, keypress: u32, egc: u32, modifiers: u32) !void { 'Q' => self.cmd("quit_without_saving", .{}), 'W' => self.cmd("close_file_without_saving", .{}), 'R' => self.cmd("restart", .{}), - 'L' => self.cmd_async("toggle_logview"), + 'L' => self.cmd_async("toggle_panel"), 'I' => self.cmd_async("toggle_inputview"), else => {}, }, @@ -241,7 +241,7 @@ fn mapPress(self: *Self, keypress: u32, egc: u32, modifiers: u32) !void { }, mod.ALT => switch (keynormal) { 'P' => self.cmd("command_palette_menu_up", .{}), - 'L' => self.cmd("toggle_logview", .{}), + 'L' => self.cmd("toggle_panel", .{}), 'I' => self.cmd("toggle_inputview", .{}), else => {}, }, @@ -253,7 +253,7 @@ fn mapPress(self: *Self, keypress: u32, egc: u32, modifiers: u32) !void { 0 => switch (keypress) { key.F09 => self.cmd("theme_prev", .{}), key.F10 => self.cmd("theme_next", .{}), - key.F11 => self.cmd("toggle_logview", .{}), + key.F11 => self.cmd("toggle_panel", .{}), key.F12 => self.cmd("toggle_inputview", .{}), key.ESC => self.cmd("exit_overlay_mode", .{}), key.UP => self.cmd("command_palette_menu_up", .{}), diff --git a/src/tui/mode/overlay/open_recent.zig b/src/tui/mode/overlay/open_recent.zig index 641be49..2110201 100644 --- a/src/tui/mode/overlay/open_recent.zig +++ b/src/tui/mode/overlay/open_recent.zig @@ -229,7 +229,7 @@ fn mapPress(self: *Self, keypress: u32, egc: u32, modifiers: u32) !void { const keynormal = if ('a' <= keypress and keypress <= 'z') keypress - ('a' - 'A') else keypress; return switch (modifiers) { mod.CTRL => switch (keynormal) { - 'J' => self.cmd("toggle_logview", .{}), + 'J' => self.cmd("toggle_panel", .{}), 'Q' => self.cmd("quit", .{}), 'W' => self.cmd("close_file", .{}), 'E' => self.cmd("open_recent_menu_down", .{}), @@ -249,13 +249,13 @@ fn mapPress(self: *Self, keypress: u32, egc: u32, modifiers: u32) !void { 'Q' => self.cmd("quit_without_saving", .{}), 'W' => self.cmd("close_file_without_saving", .{}), 'R' => self.cmd("restart", .{}), - 'L' => self.cmd_async("toggle_logview"), + 'L' => self.cmd_async("toggle_panel"), 'I' => self.cmd_async("toggle_inputview"), 'E' => self.cmd("open_recent_menu_up", .{}), else => {}, }, mod.ALT => switch (keynormal) { - 'L' => self.cmd("toggle_logview", .{}), + 'L' => self.cmd("toggle_panel", .{}), 'I' => self.cmd("toggle_inputview", .{}), else => {}, }, @@ -267,7 +267,7 @@ fn mapPress(self: *Self, keypress: u32, egc: u32, modifiers: u32) !void { 0 => switch (keypress) { key.F09 => self.cmd("theme_prev", .{}), key.F10 => self.cmd("theme_next", .{}), - key.F11 => self.cmd("toggle_logview", .{}), + key.F11 => self.cmd("toggle_panel", .{}), key.F12 => self.cmd("toggle_inputview", .{}), key.ESC => self.cmd("exit_overlay_mode", .{}), key.UP => self.cmd("open_recent_menu_up", .{}),