Merge pull request #54 from kyazdani42/feat/expose-api

Expose internal api.

README.md

@@ -102,16 +102,6 @@ require'nvim-treesitter.configs'.setup {
           scope_decremental = "grm",      -- decrement to the previous scope
         }
     },
-    node_movement = {                     -- allows cursor movement in node hierarchy
-        enable = true,
-        disable = { 'cpp', 'rust' },
-        keymaps = {                       -- mappings for scope movement (normal mappings)
-          parent_scope = "<a-k>",         -- default is to move with alt key hold
-          child_scope = "<a-j>",
-          next_scope = "<a-h>",
-          previous_scope = "<a-l>",
-        }
-    },
     ensure_installed = 'all' -- one of 'all', 'language', or a list of languages
 }
 EOF
@@ -136,12 +126,25 @@ Some of these features are :
   - [x] Incremental selection
   - [ ] Syntax based code folding
   - [x] Consistent syntax highlighting (the api is not quite stable yet)
-  - [x] Cursor movement in scope hierachy
   - [x] Statusline indicator (`require'nvim-treesitter'.statusline(size)`)
 
 You can find the roadmap [here](https://github.com/nvim-treesitter/nvim-treesitter/projects/1).
 The roadmap and all features of this plugin are open to change, and any suggestion will be highly appreciated!
 
+## Api
+
+Nvim-treesitter exposes an api to extend node capabilites. You can retrieve the api like this:
+```lua
+local ts_node_api = require 'nvim-treesitter'.get_node_api()
+```
+
+You can also retrieve the current state of the current buffer with:
+```lua
+local buf_state = require'nvim-treesitter'.get_buf_state()
+```
+
+More information is available in neovim documentation (`:help nvim-treesitter-api`).
+
 ## Supported Languages
 
 For treesitter to work, we need to use query files such as those you can find in `queries/{lang}/{locals,highlights}.scm`

doc/nvim-treesitter.txt

@@ -44,16 +44,6 @@ By default, everything is disabled. To enable support for features, in your `ini
           scope_decremental = "grm",      -- decrement to the previous scope
         }
     },
-    node_movement = {                           -- this cursor movement in node hierachy
-        enable = true,
-        disable = { 'cpp', 'rust' },
-        keymaps = {                       -- mappings for scope movement
-          parent_scope = "<a-k>",         -- default is to move with alt key hold
-          child_scope = "<a-j>",
-          next_scope = "<a-h>",
-          previous_scope = "<a-l>",
-        }
-    },
     ensure_installed = 'all' -- one of 'all', 'language', or a list of languages
   }
 <
@@ -100,8 +90,71 @@ A list of languages can be found at |:TSInstallInfo|
 List modules state for the current session.
 
 ==============================================================================
-FUNCTIONS~
+API                                               *nvim-treesitter-api*
-						   *nvim-treesitter-functions*
+
+Nvim treesitter exposes extended functions to use on nodes and scopes.
+you can retrieve the api with:
+>
+    local ts_node_api = require 'nvim-treesitter'.get_node_api()
+<
+Methods
+
+get_node_text(node, bufnr)                        *ts_api.get_node_text*
+    return the text content of a node
+
+is_parent(dest, source)                           *ts_api.is_parent*
+    determines wether `dest` is a parent of `source` 
+    return a boolean
+
+get_named_children(node)                          *ts_api.get_named_children*
+    return a table of named children of `node`
+
+get_next_node(node, allow_switch_parent, allow_next_parent) *ts_api.get_next_node*
+    return the next node within the same parent.
+    if no node is found, returns `nil`.
+    if `allow_switch_parent` is true, it will allow switching parent
+    when the node is the last node
+    if `allow_next_parent` is true, it will allow next parent if 
+    the node is the last node and the next parent doesn't have children.
+
+get_previous_node(node, allow_switch_parents, allow_prev_parent) *ts_api.get_previous_node*
+    return the previous node within the same parent.
+    `allow_switch_parent` and `allow_prev_parent` follow the same rule
+    as |ts_api.get_next_node| but if the node is the first node.
+
+containing_scope(node)                           *ts_api.containing_scope*
+    return the smallest scope containing the node
+
+parent_scope(node, cursor_pos)                   *ts_api.parent_scope*
+    return the parent scope of the current scope that contains the node.
+    `cursor_pos` should be `{ row = number, col = number }`
+    you can retrieve the cursor_pos with the buffer state
+
+nested_scope(node, cursor_pos)                   *ts_api.nested_scope*
+    return the first scope within current scope that contains the node.
+    `cursor_pos` should be `{ row = number, col = number }`
+    you can retrieve the cursor_pos with the buffer state
+
+next_scope(node)                                 *ts_api.next_scope*
+    return the neighbour scope of the current node
+
+previous_scope(node)                             *ts_api.previous_scope*
+    return the previous neighbour scope of the current node
+
+Nvim-treesitter also provides access to the state of the current buffer:
+>
+    local cur_buf_state = require'nvim-treesitter'.get_buf_state()
+    print(vim.inspect(cur_buf_state))
+    --[[
+	{
+	    cursor_pos = { row = number, col = number }, (current cursor pos in the buffer)
+	    current_node = tsnode                        (smallest node the cursor is on)
+	}
+    ]]--
+<
+
+==============================================================================
+FUNCTIONS                                         *nvim-treesitter-functions*
 
 |nvim_treesitter#statusline(size)|
 						*nvim_treesitter#statusline()*

doc/tags

@@ -6,8 +6,19 @@
 :TSInstallInfo	nvim-treesitter.txt	/*:TSInstallInfo*
 :TSModuleInfo	nvim-treesitter.txt	/*:TSModuleInfo*
 nvim-treesitter	nvim-treesitter.txt	/*nvim-treesitter*
+nvim-treesitter-api	nvim-treesitter.txt	/*nvim-treesitter-api*
 nvim-treesitter-commands	nvim-treesitter.txt	/*nvim-treesitter-commands*
 nvim-treesitter-functions	nvim-treesitter.txt	/*nvim-treesitter-functions*
 nvim-treesitter-intro	nvim-treesitter.txt	/*nvim-treesitter-intro*
 nvim-treesitter-quickstart	nvim-treesitter.txt	/*nvim-treesitter-quickstart*
 nvim_treesitter#statusline()	nvim-treesitter.txt	/*nvim_treesitter#statusline()*
+ts_api.containing_scope	nvim-treesitter.txt	/*ts_api.containing_scope*
+ts_api.get_named_children	nvim-treesitter.txt	/*ts_api.get_named_children*
+ts_api.get_next_node	nvim-treesitter.txt	/*ts_api.get_next_node*
+ts_api.get_node_text	nvim-treesitter.txt	/*ts_api.get_node_text*
+ts_api.get_previous_node	nvim-treesitter.txt	/*ts_api.get_previous_node*
+ts_api.is_parent	nvim-treesitter.txt	/*ts_api.is_parent*
+ts_api.nested_scope	nvim-treesitter.txt	/*ts_api.nested_scope*
+ts_api.next_scope	nvim-treesitter.txt	/*ts_api.next_scope*
+ts_api.parent_scope	nvim-treesitter.txt	/*ts_api.parent_scope*
+ts_api.previous_scope	nvim-treesitter.txt	/*ts_api.previous_scope*

lua/nvim-treesitter.lua

@@ -5,6 +5,7 @@ local utils = require'nvim-treesitter.utils'
 local info = require'nvim-treesitter.info'
 local configs = require'nvim-treesitter.configs'
 local state = require'nvim-treesitter.state'
+local ts_utils = require'nvim-treesitter.ts_utils'
 
 local M = {}
 
@@ -55,4 +56,13 @@ function M.statusline(indicator_size)
   end
 end
 
+function M.get_buf_state()
+  local bufnr = api.nvim_get_current_buf()
+  return state.exposed_state(bufnr)
+end
+
+function M.get_node_api()
+  return ts_utils
+end
+
 return M

lua/nvim-treesitter/configs.lua

@@ -228,19 +228,6 @@ local config = {
       is_supported = function(ft)
         return queries.get_query(ft, 'locals')
       end
-    },
-    node_movement = {
-      enable = false,
-      disable = {},
-      is_supported = function(ft)
-        return queries.get_query(ft, 'locals')
-      end,
-      keymaps = {
-        parent_scope = "<a-k>",
-        child_scope = "<a-j>",
-        next_scope = "<a-l>",
-        previous_scope = "<a-h>",
-      },
     }
   },
   ensure_installed = nil

lua/nvim-treesitter/node_movement.lua

@@ -1,72 +0,0 @@
-local api = vim.api
-
-local configs = require'nvim-treesitter.configs'
-local state = require'nvim-treesitter.state'
-local ts_utils = require'nvim-treesitter.ts_utils'
-
-local M = {}
-
-local NodeMovementKind = {
-  parent_scope = 'parent',
-  child_scope = 'child',
-  next_scope = 'next',
-  previous_scope = 'previous',
-}
-
-local get_node_fn = {
-  [NodeMovementKind.parent_scope] = function(node, curpos)
-    return ts_utils.parent_scope(node, curpos)
-  end,
-  [NodeMovementKind.child_scope] = function(node, curpos)
-    return ts_utils.nested_scope(node, curpos)
-  end,
-  [NodeMovementKind.next_scope] = function(node)
-    return ts_utils.next_scope(node)
-  end,
-  [NodeMovementKind.previous_scope] = function(node)
-    return ts_utils.previous_scope(node)
-  end,
-}
-
-M.do_node_movement = function(kind)
-  local buf = api.nvim_get_current_buf()
-
-  local buf_state = state.get_buf_state(buf)
-  if not buf_state then return end
-
-  local current_node = buf_state.current_node
-  if not current_node then return end
-
-  local destination_node = get_node_fn[kind](current_node, buf_state.cursor_pos)
-
-  if destination_node then
-    local row, col = destination_node:start()
-    vim.fn.setpos(".", { buf, row+1, col+1, 0 })
-  end
-end
-
-function M.parent_scope() M.do_node_movement(NodeMovementKind.parent_scope) end
-function M.child_scope() M.do_node_movement(NodeMovementKind.child_scope) end
-function M.next_scope() M.do_node_movement(NodeMovementKind.next_scope) end
-function M.previous_scope() M.do_node_movement(NodeMovementKind.previous_scope) end
-
-function M.attach(bufnr)
-  local bufnr = bufnr or api.nvim_get_current_buf()
-
-  local config = configs.get_module('node_movement')
-  for funcname, mapping in pairs(config.keymaps) do
-    local cmd = string.format(":lua require'nvim-treesitter.node_movement'.%s()<CR>", funcname)
-    api.nvim_buf_set_keymap(bufnr, 'n', mapping, cmd, { silent = true })
-  end
-end
-
-function M.detach(bufnr)
-  local buf = bufnr or api.nvim_get_current_buf()
-
-  local config = configs.get_module('node_movement')
-  for _, mapping in pairs(config.keymaps) do
-    api.nvim_buf_del_keymap(buf, 'n', mapping)
-  end
-end
-
-return M

lua/nvim-treesitter/state.lua

@@ -111,4 +111,12 @@ function M.get_buf_state(bufnr)
   return buffers[bufnr]
 end
 
+function M.exposed_state(bufnr)
+  local buf_state = buffers[bufnr]
+  return {
+    cursor_pos = buf_state.cursor_pos,
+    current_node = buf_state.current_node
+  }
+end
+
 return M