Merge pull request #190 from phaazon/extension-api-enhancements

Extension api enhancements
hadronized · Nov 21, 2021 · e3c9fc3 · e3c9fc3
2 parents d2a9f2a + c51d1df
commit e3c9fc3
Show file tree

Hide file tree

Showing 5 changed files with 62 additions and 27 deletions.
diff --git a/README.md b/README.md
@@ -222,10 +222,12 @@ If you want to create a key binding from within Lua:
 
 ```lua
 -- place this in one of your configuration file(s)
-vim.api.nvim_set_keymap('n', 'f', "<cmd>lua require'hop'.hint_char1({ direction = require'hop.hint'.HintDirection.AFTER_CURSOR, current_line_only = true, inclusive_jump = true })<cr>", {})
-vim.api.nvim_set_keymap('n', 'F', "<cmd>lua require'hop'.hint_char1({ direction = require'hop.hint'.HintDirection.BEFORE_CURSOR, current_line_only = true, inclusive_jump = true })<cr>", {})
-vim.api.nvim_set_keymap('n', 't', "<cmd>lua require'hop'.hint_char1({ direction = require'hop.hint'.HintDirection.AFTER_CURSOR, current_line_only = true })<cr>", {})
-vim.api.nvim_set_keymap('n', 'T', "<cmd>lua require'hop'.hint_char1({ direction = require'hop.hint'.HintDirection.BEFORE_CURSOR, current_line_only = true })<cr>", {})
+vim.api.nvim_set_keymap('n', 'f', "<cmd>lua require'hop'.hint_char1({ direction = require'hop.hint'.HintDirection.AFTER_CURSOR, current_line_only = true })<cr>", {})
+vim.api.nvim_set_keymap('n', 'F', "<cmd>lua require'hop'.hint_char1({ direction = require'hop.hint'.HintDirection.BEFORE_CURSOR, current_line_only = true })<cr>", {})
+vim.api.nvim_set_keymap('o', 'f', "<cmd>lua require'hop'.hint_char1({ direction = require'hop.hint'.HintDirection.AFTER_CURSOR, current_line_only = true, inclusive_jump = true })<cr>", {})
+vim.api.nvim_set_keymap('o', 'F', "<cmd>lua require'hop'.hint_char1({ direction = require'hop.hint'.HintDirection.BEFORE_CURSOR, current_line_only = true, inclusive_jump = true })<cr>", {})
+vim.api.nvim_set_keymap('', 't', "<cmd>lua require'hop'.hint_char1({ direction = require'hop.hint'.HintDirection.AFTER_CURSOR, current_line_only = true })<cr>", {})
+vim.api.nvim_set_keymap('', 'T', "<cmd>lua require'hop'.hint_char1({ direction = require'hop.hint'.HintDirection.BEFORE_CURSOR, current_line_only = true })<cr>", {})
 ```
 
 For a more complete user guide and help pages:

diff --git a/doc/hop.txt b/doc/hop.txt
@@ -310,7 +310,7 @@ implementing your own.
 
 Jump targets are locations in buffers where users might jump to. They are
 wrapped in a table and provide the required information so that Hop can
-associate label and display the hints. Such a table must have the following
+associate labels and display the hints. Such a table must have the following
 form:
 >
     {
@@ -319,16 +319,24 @@ form:
     }
 >
 The `jump_targets` field is a list-table of jump targets. A single jump target
-is simply a location in a given window. So you can picture a jump target as
-a triple (line, column, window).
+is simply a location in a given window. Actually, the location will be set on
+the buffer that is being displayed by that window. So you can picture a jump
+target as a triple (line, column, window).
 >
     {
       line = 0,
       column = 0,
       window = 0,
     }
 <
-`indirect_jump_targets` are encoded as a flat list-table of pairs
+`indirect_jump_targets` is an optional yet highly recommended table. They
+provide an indirect access to `jump_targets` to re-order them. They are for
+instance used to be able to distribute hints according to their distance to
+the current location of the cursor. Not providing that table (`nil`) will
+result in the jump targets being considered fully ordered and will be assigned
+sequences based on their index in `jump_targets`.
+
+Indirect jump targets are encoded as a flat list-table of pairs
 (index, score). This table allows to quickly score and sort jump targets.
 >
     {
@@ -355,9 +363,22 @@ such a table:
       },
     }
 <
+
+If you don’t need to change the score, or if the scores are always ascending
+with the indices ascending, you can completely omit the
+`indirect_jump_targets` table:
+>
+    {
+      jump_targets = {
+        { line = 1, column = 14, window = 0 },
+        { line = 2, column = 1, window = 0 },
+      },
+    }
+<
 This module provides several functions, named `jump_targets_*`, which are
-called jump target generator. Such functions are to be passed to
-|hop.hint_with|. Most of the Vim commands are doing this for you.
+called jump target generators. Such functions are to be passed to
+|hop.hint_with| or |hop.hint_with_callback|. Most of the Vim commands are already
+doing that for you.
 
 `hop.jump_target.jump_targets_by_scanning_line(` *hop.jump_target.jump_targets_by_scanning_line*
   {regex}
@@ -372,10 +393,11 @@ called jump target generator. Such functions are to be passed to
 
                 If you want to create your own regex-like table, you need to
                 provide a table with two fields: `oneshot`, a boolean value,
-                that is to be set to `true` if the regex should be applied to
-                each line only once, and `match`, which is the actual matcher
-                that returns the beginning / end (inclusive / exclusive) byte
-                indices of the match. You are advised to use |vim.regex|.
+                that is to be set to `true` if the regex should be applied
+                only once to each line, and `match`, which is the actual
+                matcher that returns the beginning / end
+                (inclusive / exclusive) byte indices of the match. You are
+                advised to use |vim.regex|.
 
 `hop.jump_target.jump_targets_for_current_line(` *hop.jump_target.jump_targets_for_current_line*
   {regex}
@@ -447,8 +469,8 @@ called jump target generator. Such functions are to be passed to
   {b}`,`
   {x_bias}
 `)`
-    Manhattan distance between two buffer position. Both {a} and {b} must be
-    table containing two values: the first one for the line and the second one
+    Manhattan distance between two buffer positions. Both {a} and {b} must be
+    tables containing two values: the first one for the line and the second one
     for the column.
 
     {x_bias} is to be used to skew the Manhattan distance in terms of lines.
@@ -696,7 +718,7 @@ below.
 
 `extensions`                                               *hop-config-extensions*
     List-table of extensions to enable (names). As described in |hop-extension|,
-    extensions for which the name is in that list must have a `register(opts)`
+    extensions for which the name in that list must have a `register(opts)`
     function in their public API for Hop to correctly initialized them.
 
     Defaults:~

diff --git a/examples/hop-extension-hello-world/lua/hop-extension-hello-world/init.lua b/examples/hop-extension-hello-world/lua/hop-extension-hello-world/init.lua
@@ -1,33 +1,24 @@
 local M = {}
 M.opts = {}
 
-local function override_opts(opts)
-  return setmetatable(opts or {}, {__index = M.opts})
-end
-
 function M.hint_around_cursor(opts)
-  opts = override_opts(opts)
-
   -- the jump target generator; we are simply going to retreive the cursor position and hint around it as an example
   local jump_targets = function() -- opts ignored
     local cursor_pos = require'hop.window'.get_window_context().cursor_pos
     local line = cursor_pos[1] - 1
     local col = cursor_pos[2] + 1
 
     local jump_targets = {}
-    local indirect_jump_targets = {}
 
     -- left
     if col > 0 then
       jump_targets[#jump_targets + 1] = { line = line, column = col - 1, window = 0 }
-      indirect_jump_targets[#indirect_jump_targets + 1] = { index = #jump_targets, score = 0 }
     end
 
     -- right
     jump_targets[#jump_targets + 1] = { line = line, column = col + 1, window = 0 }
-    indirect_jump_targets[#indirect_jump_targets + 1] = { index = #jump_targets, score = 0 }
 
-    return { jump_targets = jump_targets, indirect_jump_targets = indirect_jump_targets }
+    return { jump_targets = jump_targets }
   end
 
   require'hop'.hint_with(jump_targets, opts)

diff --git a/lua/hop/hint.lua b/lua/hop/hint.lua
@@ -57,10 +57,22 @@ end
 --
 -- This function associates jump targets with permutations, creating hints. A hint is then a jump target along with a
 -- label.
+--
+-- If `indirect_jump_targets` is `nil`, `jump_targets` is assumed already ordered with all jump target with the same
+-- score (0)
 function M.create_hints(jump_targets, indirect_jump_targets, opts)
   local hints = {}
   local perms = perm.permutations(opts.keys, #jump_targets, opts)
 
+  -- get or generate indirect_jump_targets
+  if indirect_jump_targets == nil then
+    indirect_jump_targets = {}
+
+    for i = 1, #jump_targets do
+      indirect_jump_targets[i] = { index = i, score = 0 }
+    end
+  end
+
   for i, indirect in pairs(indirect_jump_targets) do
     hints[indirect.index] = {
       label = tbl_to_str(perms[i]),

diff --git a/lua/hop/init.lua b/lua/hop/init.lua
@@ -122,12 +122,20 @@ function M.move_cursor_to(w, line, column, inclusive)
 end
 
 function M.hint_with(jump_target_gtr, opts)
+  if opts == nil then
+    opts = override_opts(opts)
+  end
+
   M.hint_with_callback(jump_target_gtr, opts, function(jt)
     M.move_cursor_to(jt.window, jt.line + 1, jt.column - 1, opts.inclusive_jump)
   end)
 end
 
 function M.hint_with_callback(jump_target_gtr, opts, callback)
+  if opts == nil then
+    opts = override_opts(opts)
+  end
+
   if not M.initialized then
     vim.notify('Hop is not initialized; please call the setup function', 4)
     return