From 3eba91caf662aafb428a958b89993d2bcd002b3e Mon Sep 17 00:00:00 2001 From: iff Date: Tue, 22 Apr 2025 15:38:16 +0200 Subject: [PATCH] docs: cleanup --- module-runtime-rules/README.md | 13 ++++- rules.md | 58 ++++++++++++++----- rules/{pr_general.toml => _PR_GENERAL.toml} | 0 .../{pr_privilege.toml => _PR_PRIVILEGE.toml} | 0 4 files changed, 52 insertions(+), 19 deletions(-) rename rules/{pr_general.toml => _PR_GENERAL.toml} (100%) rename rules/{pr_privilege.toml => _PR_PRIVILEGE.toml} (100%) diff --git a/module-runtime-rules/README.md b/module-runtime-rules/README.md index c54e0af..1a66e3a 100644 --- a/module-runtime-rules/README.md +++ b/module-runtime-rules/README.md @@ -1,8 +1,11 @@ # Runtime Rules Module -Module for [pay-respects](https://codeberg.org/iff/pay-respects) which allows you to parse rules at runtime. +Module for [pay-respects] which allows you to add rules at runtime. -Syntax is currently 100% compatible with [upstream's compile-time rules](https://codeberg.org/iff/pay-respects/src/branch/main/rules.md). +Syntax is currently 100% compatible with [upstream's compile-time rules]. + +[pay-respects]: https://codeberg.org/iff/pay-respects +[upstream's compile-time rules]: https://codeberg.org/iff/pay-respects/src/branch/main/rules.md Rules are searched in these directories: @@ -10,4 +13,8 @@ Rules are searched in these directories: - `XDG_CONFIG_DIRS`, defaults to `/etc/xdg`. - `XDG_DATA_DIRS`, defaults to `/usr/local/share:/usr/share`. -The actual rule file should be placed under `pay-respects/rules/`, for example: `~/.config/pay-respects/rules/cargo.toml`. To avoid parsing unnecessary rules, the name of the file **MUST** match the command name. +The actual rule file should be placed under `pay-respects/rules/`, for example: +`~/.config/pay-respects/rules/cargo.toml`. To avoid parsing unnecessary rules, +the name of the file **MUST** match the command name. + +An exception is `_PR_GENERAL.toml` that is always parsed. diff --git a/rules.md b/rules.md index 1bf30c0..1ba0828 100644 --- a/rules.md +++ b/rules.md @@ -1,19 +1,26 @@ # Writing Rules -Rule files placed under [rules](./rules) in the project directory are parsed at compilation, everything is parsed to Rust code before compiling. You don't have to know the project structure nor Rust to write blazing fast rules! +Rule files placed under [rules](./rules) in the project directory are parsed at +compilation, everything is parsed to Rust code before compiling. You don't have +to know the project structure nor Rust to write blazing fast rules! -For compile-time rules, if only rules are changed, cargo won't recompile the project because Rust code were intact. You will have to notify it manually by: +For compile-time rules, if only rules are changed, cargo won't recompile the +project because Rust code were intact. You will have to notify it manually by: ```shell touch core/src/rules.rs && cargo build ``` -Runtime-rules support is provided by `runtime-rules` module. Directories are searched with the following priority: +Runtime-rules support is provided by `runtime-rules` module. Directories are +searched with the following priority: - `XDG_CONFIG_HOME`, defaults to `$HOME/.config`. - `XDG_CONFIG_DIRS`, defaults to `/etc/xdg`. - `XDG_DATA_DIRS`, defaults to `/usr/local/share:/usr/share`. -The actual rule file should be placed under `pay-respects/rules/`, for example: `~/.config/pay-respects/rules/cargo.toml`. Note that for runtime rules, the name of the file **MUST** match the command name. +The actual rule file should be placed under `pay-respects/rules/`, for example: +`~/.config/pay-respects/rules/cargo.toml`. Note that for runtime rules, the +name of the file **MUST** match the command name. Except `_PR_GENERAL.toml` +that is always parsed ## Syntax @@ -55,30 +62,49 @@ sudo {{command}} ''' The placeholder is evaluated as following: - `{{command}}`: All the command without any modification -- `{{command[1]}}`: The first argument of the command (the command itself has index of 0) +- `{{command[1]}}`: The first argument of the command (the command itself has +index of 0) - Negative values will count from reverse. - `{{command[2:5]}}`: The second to fifth arguments - - If any of the side is not specified, then it defaults to the start (if it is left) or the end (if it is right) -- `{{typo[2](fix1, fix2)}}`: Try to change the second argument to candidates in the parenthesis. + - If any of the side is not specified, then it defaults to the start (if it + is left) or the end (if it is right) +- `{{typo[2](fix1, fix2)}}`: Try to change the second argument to candidates in +the parenthesis. - The argument in parentheses must have at least 2 values - - Single arguments are reserved for specific matches, for instance, `path` to search all commands found in the `$PATH` environment, or the `{{shell}}` placeholder, among others -- `{{select[3](selection1, selection2)}}`: A derivative of `typo` placeholder. Will create a suggestion for each selection in the parenthesis + - Single arguments are reserved for specific matches, for instance, `path` to + search all commands found in the `$PATH` environment, or the `{{shell}}` + placeholder, among others +- `{{select[3](selection1, selection2)}}`: A derivative of `typo` placeholder. +Will create a suggestion for each selection in the parenthesis - The argument in parentheses also must have at least 2 values - - Single arguments are reserved for specific selections, for instance, `path` to search all commands found in the `$PATH` environment with the minimum shared linguistic distance, or the `{{shell}}` placeholder - - To avoid permutations and combinations, only one instance is evaluated. If you need to apply the same selection in multiple places, use `{{selection}}` - - Index is optional as it only has effect when using with `path`, and defaults to `0` -- `{{opt::}}`: Optional patterns captured in the command with RegEx ([see regex crate for syntax](https://docs.rs/regex-lite/latest/regex_lite/#syntax)) + - Single arguments are reserved for specific selections, for instance, `path` + to search all commands found in the `$PATH` environment with the minimum + shared linguistic distance, or the `{{shell}}` placeholder + - To avoid permutations and combinations, only one instance is evaluated. If + you need to apply the same selection in multiple places, use + `{{selection}}` + - Index is optional as it only has effect when using with `path`, and + defaults to `0` +- `{{opt::}}`: Optional patterns captured in the command +with RegEx ([see regex crate for syntax]) - All patterns matching this placeholder will be removed from indexing - `{{cmd::}}`: Get the matching captures from the last command - Unlike `{{opt}}`, this won't remove the string after matching - `{{err::)}}`: Replace with the output of the shell command - - Can be used along `{{typo}}` or `{{select}}` as its only argument, where each newline will be evaluated to a candidate/selection + - Can be used along `{{typo}}` or `{{select}}` as its only argument, where + each newline will be evaluated to a candidate/selection -Suggestions can have additional conditions to check. To specify conditions, add a `#[...]` at the first line (just like derive macros in Rust). Available conditions: +[see regex crate for syntax]: https://docs.rs/regex-lite/latest/regex_lite/#syntax + +Suggestions can have additional conditions to check. To specify conditions, add +a `#[...]` at the first line (just like derive macros in Rust). Available +conditions: - `executable`: Check if the argument can be found in path -- `cmd_contains`: Check if the last user input contains the argument. Regex supported (you can't use `,` currently because it's used as condition separator) +- `cmd_contains`: Check if the last user input contains the argument. Regex +supported (you can't use `,` currently because it's used as condition +separator) - `err_contains`: Same as `cmd_contains` but for error message - `length`: Check if the given command has the length of the argument - `min_length`: Check if the given command has at least the length of the argument diff --git a/rules/pr_general.toml b/rules/_PR_GENERAL.toml similarity index 100% rename from rules/pr_general.toml rename to rules/_PR_GENERAL.toml diff --git a/rules/pr_privilege.toml b/rules/_PR_PRIVILEGE.toml similarity index 100% rename from rules/pr_privilege.toml rename to rules/_PR_PRIVILEGE.toml