-
Notifications
You must be signed in to change notification settings - Fork 6
Actions API
Emilien Jegou edited this page Jun 18, 2026
·
3 revisions
This document describes the action namespace hierarchy exposed to the configuration engine.
Below is a graph showcasing how actions are defined internally. In your rune config to call any action you need to follow the module nesting. e.g. theme::bg::set("red").
The @getset(T) modifier expands to { get(|| -> T), set(T) }
define_actions! {
global {
/// Terminate the application (exit 1)
quit()
/// Write the merge OR open the confirmation modal if enabled.
confirm()
/// Write the merge
execute_merge()
/// Open command mode.
open_command_mode()
/// Enable or disable the confirmation modal before writing/merging changes.
confirm_merge_window_enabled { @getset(bool) }
}
theme {
/// Set the active base theme (syntax theme + ui theme).
/// Accepts built-in themes (e.g., "weywot", "quaoar", ...),
/// full list at https://github.com/emilien-jegou/oyui/blob/main/docs/themes.md
/// Or a path to TextMate file "path:/..."
/// Default to terminal theme "ansi"
set(String)
/// Set the syntax theme
/// same arguments as `theme::set`
syntax(String)
/// Query whether the current theme follow a light or dark color scheme.
is_dark(|| -> bool)
/// Default background color.
bg { @getset(Color) }
/// Default foreground text color.
fg { @getset(Color) }
/// Color of the active cursor cell background.
cursor_bg { @getset(Color) }
/// Color representing inactive or secondary UI text.
dim { @getset(Color) }
/// Text color representing fully staged changes or files.
staged { @getset(Color) }
/// Text color representing unstaged changes or files.
unstaged { @getset(Color) }
/// Text color representing partially staged elements.
partial { @getset(Color) }
/// Text color for directory names inside the tree view.
dir { @getset(Color) }
/// Text/prompt color for the active command bar.
cmd { @getset(Color) }
/// Background color for code additions inside diff lines.
add_bg { @getset(Color) }
/// Background color for code deletions inside diff lines.
del_bg { @getset(Color) }
/// Text foreground color for added line content.
add_fg { @getset(Color) }
/// Text foreground color for deleted line content.
del_fg { @getset(Color) }
/// Custom line-highlight rendering mode for staged changes.
file_staged_highlight { @getset(LineHighlightMode) }
/// Transparency value (0.0 to 1.0) for staged line backgrounds.
file_staged_highlight_opacity { @getset(f64) }
/// Custom line-highlight rendering mode for unstaged modifications.
file_change_highlight { @getset(LineHighlightMode) }
/// Transparency value (0.0 to 1.0) for modified line backgrounds.
file_change_highlight_opacity { @getset(f64) }
/// Symbol separating diff hunks.
char_hunk_split { @getset(String) }
/// Symbol drawn for splitting lines in the viewport.
char_line_split { @getset(String) }
/// Icon representing general UI states or indicators.
char_indicator { @getset(String) }
/// Prefix icon for code additions (e.g., "+").
char_add_sign { @getset(String) }
/// Prefix icon for code deletions (e.g., "-").
char_del_sign { @getset(String) }
/// Text color of the trailing whitespace placeholder.
char_trailing_space_fg { @getset(Color) }
/// Text color of the tab visualization placeholder.
char_tab_fg { @getset(Color) }
/// Color code of active horizontal scroll indicators.
char_scroll_fg { @getset(Color) }
/// Color code applied to the hunk split symbol.
char_hunk_split_color { @getset(Color) }
/// Color applied to the line split symbol.
char_line_split_color { @getset(Color) }
/// Visual placeholder replacement symbol for trailing whitespace.
char_trailing_space { @getset(String) }
/// Visual placeholder replacement symbol for tab characters.
char_tab { @getset(String) }
/// Indicator representing scrollable area to both left and right directions.
char_scroll_both { @getset(String) }
/// Indicator representing hidden scrollable content to the left.
char_scroll_left { @getset(String) }
/// Indicator representing hidden scrollable content to the right.
char_scroll_right { @getset(String) }
/// Toggles progressive dimming of additions/deletions in tree view.
/// e.g. Large addition appear brighter than small additions.
tree_progressive_change_dim { @getset(bool) }
}
view {
file {
scroll {
/// Scroll viewport left by the specified column offset.
left(u32)
/// Scroll viewport right by the specified column offset.
right(u32)
}
cursor {
/// Move cursor upwards by the specified number of lines.
up(u32)
/// Move cursor downwards by the specified number of lines.
down(u32)
/// Scroll viewport up by a full page height.
page_up()
/// Scroll viewport down by a full page height.
page_down()
/// Scroll viewport up by half a page height.
half_page_up()
/// Scroll viewport down by half a page height.
half_page_down()
/// Snap cursor to the first line of the file.
top()
/// Snap cursor to the final line of the file.
bottom()
}
nav {
/// Move focus to the subsequent modified hunk in the active diff.
next_hunk()
/// Move focus to the preceding modified hunk in the active diff.
prev_hunk()
}
staging {
/// Toggle staging state of the selected line or current hunk.
toggle()
/// Toggle staging state of a specific hunk by its index.
toggle_hunk(u32)
/// Toggle staging status of the precise line matching current cursor position.
toggle_line()
/// Split the current hunk into smaller standalone blocks.
split()
/// Invert the staging state across all lines in the active diff view.
invert()
}
fold {
/// Expand or collapse the logical code folding block under the cursor.
toggle()
}
/// Close the active file view to return focus back to the file tree.
close()
}
tree {
cursor {
/// Move file tree cursor up by the specified number of elements.
up(u32)
/// Move file tree cursor down by the specified number of elements.
down(u32)
/// Scroll tree viewport up by a full page.
page_up()
/// Scroll tree viewport down by a full page.
page_down()
/// Scroll tree viewport up by half a page.
half_page_up()
/// Scroll tree viewport down by half a page.
half_page_down()
/// Snap focus to the top node of the file tree.
top()
/// Snap focus to the lowest expanded node of the file tree.
bottom()
}
directory {
/// Expand the selected directory node.
expand()
/// Collapse the selected directory node.
collapse()
}
staging {
/// Toggle staging state for the selected file or folder recursively.
toggle_selected()
/// Invert staging selection states recursively across all items inside the tree.
invert()
}
/// Open the active item. Opens files in the file viewer or expands directory folders.
open_selected()
/// Force load a specific file view for the given system path.
open_file(String)
}
}
}Properties accepting a Color type parse configurations according to the following formats:
| Format | Example | Description |
|---|---|---|
| Hexadecimal |
"#f4f4f4", "fff"
|
3-digit or 6-digit RGB hex colors, parsed optionally with the leading # symbol. |
| RGB function | "rgb(41, 41, 41)" |
Functional triplet notation declaring explicit Red, Green, and Blue integers. |
| Theme Reference |
"theme:bg", "theme:staged"
|
Binds color definitions dynamically to an existing field value loaded in the UI theme. |
| TextMate Token |
"tm:accent", "tm:foreground"
|
Extracts settings variables or scope-based highlights directly from the active TextMate syntax file. |
| ANSI Index | "ansi:9" |
Targets one of the standard 16-color ANSI terminal index positions (values 0–15). |
| ANSI 256 Index | "ansi256:129" |
Targets the extended 256-color palette (values 0–255) for compatible terminal applications. |
| Keyword |
"red", "bg", "reset"
|
Evaluates case-insensitive standard system keywords, default channels ("bg", "fg"), or palette colors. |
The underlying parser filters resolved values based on the terminal's reported rendering capabilities:
- TrueColor Mode: Resolves TrueColor RGB values, ANSI, or ANSI256 structures. Fallback values are handled using active palette entries.
- ANSI256 Mode: Permits matching on ANSI indices and 256-color configurations. High-fidelity RGB specifications are omitted or degraded depending on the display mode.
- ANSI Mode: Permits standard 16-color index variations and fallback system keywords.
Below are all exact values supported by the theme:, tm:, and keyword color prefixes.
Refer to fields configured within the active UI theme:
bg,fg,cursor_bg,dim,dimmer,staged,unstaged,partial,dir,cmd,add_bg,del_bg,add_fg,del_fg,char_trailing_space_fg,char_tab_fg,char_scroll_fg,char_line_split_color,char_hunk_split_color
Retrieve values directly from TextMate format properties or custom fallback scopes defined in the active syntax file:
foreground,background,caret,line_highlight,misspelling,minimap_border,accent,bracket_contents_foreground,brackets_foreground,brackets_background,tags_foreground,highlight,find_highlight,find_highlight_foreground,gutter,gutter_foreground,selection,selection_foreground,selection_border,inactive_selection,inactive_selection_foreground,guide,active_guide,stack_guide,shadow
Directly resolve to terminal-defined standard registers:
reset,default,bg,fg,black,red,green,yellow,blue,magenta,cyan,gray,grey,darkgray,darkgrey,lightred,lightgreen,lightyellow,lightblue,lightmagenta,lightcyan,white
Custom keyboard configurations are loaded via standard API functions registered to the execution context. Keyboard mappings can be configured globally or enclosed within viewport scopes.
Binds a keyboard shortcut pattern to a callback block.
-
key_sequence: String representing the key trigger configuration (e.g.,"Ctrl-d","j","Esc","Enter"). -
callback: Context execution block mapping to internal actions or custom routines.
Initializes a scoping environment to register mode-specific keybindings. Keybinds declared within this environment only register when the target mode is active.
-
mode: Target viewport selector. Supported identifiers are:-
"file": View context for the code File Viewer. -
"tree": View context for the directory Tree Explorer.
-
These examples illustrate how to structure bindings and theme customizations within your configuration file (config.rn).
pub fn config() {
// Set default terminal theme (v0.2.0 default is "ansi")
theme::set("ansi");
// Conditional syntax theme based on terminal light/dark background
if theme::is_dark() {
theme::syntax("quaoar");
} else {
theme::syntax("dayfox");
}
// Enable the safety merge confirmation popup
global::confirm_merge_window_enabled::set(true);
// Customize special character visualizations
theme::char_tab::set("❘");
theme::char_tab_fg::set("red");
theme::char_trailing_space::set("༞");
theme::char_trailing_space_fg::set("red");
// Customize file staged highlight appearance
theme::file_staged_highlight::set(LineHighlightMode::Gradient(0.08));
theme::file_staged_highlight_opacity::set(0.35);
// Global Keybindings
keybind("q", || {
global::quit();
});
// Mode-Specific Tree Explorer Keybindings
on_mode("tree", || {
keybind("Space", || {
view::tree::staging::toggle_selected();
});
});
// Mode-Specific File Viewer Keybindings
on_mode("file", || {
keybind("Ctrl-d", || {
view::file::cursor::half_page_down();
});
});
}