feat(#37): head tail movement support + deprecate previous API's

README.md

@@ -91,18 +91,31 @@ paredit.setup({
     ["<localleader>O"] = { paredit.api.raise_element, "Raise element" },
 
     ["E"] = {
-      paredit.api.move_to_next_element,
+      paredit.api.move_to_next_element_tail,
       "Jump to next element tail",
       -- by default all keybindings are dot repeatable
       repeatable = false,
       mode = { "n", "x", "o", "v" },
     },
+    ["W"] = {
+      paredit.api.move_to_next_element_head,
+      "Jump to next element head",
+      repeatable = false,
+      mode = { "n", "x", "o", "v" },
+    },
+
     ["B"] = {
-      paredit.api.move_to_prev_element,
+      paredit.api.move_to_prev_element_head,
       "Jump to previous element head",
       repeatable = false,
       mode = { "n", "x", "o", "v" },
     },
+    ["gE"] = {
+      paredit.api.move_to_prev_element_tail,
+      "Jump to previous element tail",
+      repeatable = false,
+      mode = { "n", "x", "o", "v" },
+    },
 
     -- These are text object selection keybindings which can used with standard `d, y, c`, `v`
     ["af"] = {

lua/nvim-paredit/api/init.lua

@@ -5,6 +5,7 @@ local raising = require("nvim-paredit.api.raising")
 local motions = require("nvim-paredit.api.motions")
 local selections = require("nvim-paredit.api.selections")
 local deletions = require("nvim-paredit.api.deletions")
+local common = require("nvim-paredit.utils.common")
 
 local M = {
   slurp_forwards = slurping.slurp_forwards,
@@ -20,8 +21,15 @@ local M = {
   raise_form = raising.raise_form,
   raise_element = raising.raise_element,
 
-  move_to_next_element = motions.move_to_next_element,
-  move_to_prev_element = motions.move_to_prev_element,
+  -- TODO: remove deprecated code in next versions
+  move_to_next_element = common.deprecate(motions.move_to_next_element_tail, "use `api.move_to_next_element_tail`"),
+  move_to_next_element_tail = motions.move_to_next_element_tail,
+  move_to_next_element_head = motions.move_to_next_element_head,
+
+  -- TODO: remove deprecated code in next versions
+  move_to_prev_element = common.deprecate(motions.move_to_prev_element_head, "use `api.move_to_prev_element_head`"),
+  move_to_prev_element_head = motions.move_to_prev_element_head,
+  move_to_prev_element_tail = motions.move_to_prev_element_tail,
 
   select_around_form = selections.select_around_form,
   select_in_form = selections.select_in_form,

lua/nvim-paredit/api/motions.lua

@@ -52,7 +52,8 @@ local function get_next_node_from_cursor(lang, reversed)
   end
 end
 
-function M._move_to_element(count, reversed)
+function M._move_to_element(count, reversed, is_head)
+  is_head = is_head or false
   local lang = langs.get_language_api()
 
   local current_node = get_next_node_from_cursor(lang, reversed)
@@ -67,16 +68,20 @@ function M._move_to_element(count, reversed)
 
   local is_in_middle = false
   if reversed then
-    node_edge = { current_node:start() }
     traversal_fn = traversal.get_prev_sibling_ignoring_comments
-    if common.compare_positions(cursor_pos, node_edge) == 1 then
-      is_in_middle = true
+    if is_head then
+      node_edge = { current_node:start() }
+      if common.compare_positions(cursor_pos, node_edge) == 1 then
+        is_in_middle = true
+      end
     end
   else
-    node_edge = { current_node:end_() }
     traversal_fn = traversal.get_next_sibling_ignoring_comments
-    if common.compare_positions({ node_edge[1], node_edge[2] - 1 }, cursor_pos) == 1 then
-      is_in_middle = true
+    if not is_head then
+      node_edge = { current_node:end_() }
+      if common.compare_positions({ node_edge[1], node_edge[2] - 1 }, cursor_pos) == 1 then
+        is_in_middle = true
+      end
     end
   end
 
@@ -95,7 +100,7 @@ function M._move_to_element(count, reversed)
       count = count,
     })
     if sibling then
-      if reversed then
+      if is_head then
         next_pos = { sibling:start() }
       else
         next_pos = { sibling:end_() }
@@ -107,7 +112,7 @@ function M._move_to_element(count, reversed)
     return
   end
 
-  if reversed then
+  if is_head then
     cursor_pos = { next_pos[1] + 1, next_pos[2] }
   else
     cursor_pos = { next_pos[1] + 1, next_pos[2] - 1 }
@@ -125,16 +130,28 @@ local function ensure_visual_if_operator_pending()
   end
 end
 
-function M.move_to_prev_element()
+function M.move_to_prev_element_head()
+  local count = vim.v.count1
+  ensure_visual_if_operator_pending()
+  M._move_to_element(count, true, true)
+end
+
+function M.move_to_prev_element_tail()
+  local count = vim.v.count1
+  ensure_visual_if_operator_pending()
+  M._move_to_element(count, true, false)
+end
+
+function M.move_to_next_element_tail()
   local count = vim.v.count1
   ensure_visual_if_operator_pending()
-  M._move_to_element(count, true)
+  M._move_to_element(count, false, false)
 end
 
-function M.move_to_next_element()
+function M.move_to_next_element_head()
   local count = vim.v.count1
   ensure_visual_if_operator_pending()
-  M._move_to_element(count, false)
+  M._move_to_element(count, false, true)
 end
 
 return M

lua/nvim-paredit/defaults.lua

@@ -19,17 +19,29 @@ M.default_keys = {
   ["<localleader>O"] = { api.raise_element, "Raise element" },
 
   ["E"] = {
-    api.move_to_next_element,
+    api.move_to_next_element_tail,
     "Next element tail",
     repeatable = false,
     mode = { "n", "x", "o", "v" },
   },
+  ["W"] = {
+    api.move_to_next_element_head,
+    "Next element head",
+    repeatable = false,
+    mode = { "n", "x", "o", "v" },
+  },
   ["B"] = {
-    api.move_to_prev_element,
+    api.move_to_prev_element_head,
     "Previous element head",
     repeatable = false,
     mode = { "n", "x", "o", "v" },
   },
+  ["gE"] = {
+    api.move_to_prev_element_tail,
+    "Previous element tail",
+    repeatable = false,
+    mode = { "n", "x", "o", "v" },
+  },
 
   ["af"] = {
     api.select_around_form,

lua/nvim-paredit/utils/common.lua

@@ -79,4 +79,11 @@ function M.is_whitespace_under_cursor(lang)
     or char_under_cursor[1] == ""
 end
 
+function M.deprecate(fn, message)
+  return function(...)
+    print("Warning: Deprecated function called. " .. message)
+    return fn(...)
+  end
+end
+
 return M