diff options
| -rw-r--r-- | README.md | 147 |
1 files changed, 147 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..0da3da7 --- /dev/null +++ b/README.md @@ -0,0 +1,147 @@ +# clever-tee + +clever-tee extends Nvim's `f`, `F`, `t`, and `T` character motions with shared repetition, multiline search, counts, multibyte text, dot-repeat, configurable matching, and visual feedback. + +## Installation + +Install the complete repository root so that `plugin/`, `lua/`, and `autoload/` are on `runtimepath`. Load it at startup because it replaces core motion keys. + +Example for lazy.nvim: + +```lua +{ + "<owner>/clever-tee", + lazy = false, + + init = function() + -- Set configuration here, before plugin activation. + vim.g.clever_tee_smart_case = true + end, + + config = function() + local clever_tee = require("clever_tee") + + -- Optional explicit repeat mappings. + vim.keymap.set( + { "n", "x", "o" }, + ";", + clever_tee.RepeatSameDirection, + { silent = true } + ) + vim.keymap.set( + { "n", "x", "o" }, + ",", + clever_tee.RepeatOppositeDirection, + { silent = true } + ) + end, +} +``` + +Replace `<owner>/clever-tee` with the published repository identifier. For a local installation, use the repository root as the plugin manager's `dir`. + +`plugin/clever_tee.lua` activates the plugin automatically. A manual runtime loader can call: + +```lua +require("clever_tee").activate() +``` + +## Default mappings + +The plugin installs these silent, non-recursive mappings in Normal, Visual, and operator-pending modes: + +- `f`: find forward +- `F`: find backward +- `t`: till forward +- `T`: till backward + +Counts work, for example `2fa`. + +All four keys share the active FIND or TILL sequence. With the default direction policy, lower-case keys repeat the stored direction and upper-case keys use the opposite direction. + +The explicit repeat functions provide semicolon and comma behavior: + +- `RepeatSameDirection` +- `RepeatOppositeDirection` + +## Suppressing the default mappings + +Set this global before activation: + +```lua +vim.g.clever_tee_not_overwrites_standard_mappings = true +``` + +Its presence suppresses the default mappings. Values such as `false` and `0` also suppress them. Leave the global absent to install the defaults. + +Custom mappings can call these functions from `require("clever_tee")`: + +- `StartFindForward` +- `StartFindBackward` +- `StartTillForward` +- `StartTillBackward` +- `RepeatSameDirection` +- `RepeatOppositeDirection` +- `Reset` + +## Configuration + +All regular settings use the `vim.g.clever_tee_` prefix. + +Search and matching: + +- `search_current_line_only`: Boolean, default `false`. The default searches toward the buffer boundary. +- `ignore_case`: Boolean, default `false`. +- `smart_case`: Boolean, default `false`. Lower-case ASCII targets ignore case; upper-case targets preserve case. +- `use_migemo`: Boolean, default `false`. UTF-8, CP932, and EUC-JP dictionaries are bundled. +- `chars_match_any_signs`: String, default `""`. Each listed trigger matches the complete supported symbol class. + +Sequence behavior: + +- `fix_key_direction`: Boolean, default `false`. When true, lower-case primary keys always move forward and upper-case keys always move backward. +- `repeat_timeout_ms`: Nonnegative integer, default `0`. Zero keeps repetition active without expiration. +- `repeat_last_char_inputs`: List of strings, default `{ "\r" }`. Enter reuses the last acquired target. + +Input feedback: + +- `show_prompt`: Boolean, default `false`. +- `mark_cursor`: Boolean, default `true`. +- `mark_cursor_color`: Highlight-group name, default target `Cursor`. +- `hide_cursor_on_cmdline`: Boolean, default `true`. +- `mark_direct`: Boolean, default `false`. +- `mark_direct_color`: Highlight-group name, default target `CleverTeeDefaultLabel`. + +Persistent feedback: + +- `mark_char`: Boolean, default `true`. +- `mark_char_color`: Highlight-group name, default target `CleverTeeDefaultLabel`. +- `highlight_timeout_ms`: Nonnegative integer, default `0`. Zero keeps labels until a lifecycle event clears them. +- `clean_labels_eagerly`: Boolean, default `true`. + +Example: + +```lua +vim.g.clever_tee_search_current_line_only = true +vim.g.clever_tee_smart_case = true +vim.g.clever_tee_mark_direct = true +vim.g.clever_tee_repeat_timeout_ms = 1500 +vim.g.clever_tee_highlight_timeout_ms = 500 +vim.g.clever_tee_mark_char_color = "Search" +``` + +Set `clean_labels_eagerly` and the mapping-suppression sentinel before activation. Setting all options before activation gives predictable highlight initialization. Most search and motion settings are sampled again for each action. + +The available highlight groups are: + +- `CleverTeeDefaultLabel` +- `CleverTeeCursor` +- `CleverTeeChar` +- `CleverTeeDirect` + +The plugin refreshes their links after `ColorScheme`. + +## Requirements + +- Nvim 1.12.5 +- The complete plugin repository, including the bundled Migemo assets +- A startup package or plugin manager that adds the repository root to `runtimepath` |