Add hook functionality, update docs

CHANGELOG.md

@@ -1,5 +1,6 @@
 Changelog
 ======================
 
+2021-07-10 - Add hook function to be called before reading `commentstring`
 2021-02-16 - Fix issue with `gv` causing entire buffer range to be acted on
 2021-02-12 - Fix issue with motion acting on last visual selection

README.md

@@ -1,38 +1,47 @@
 # nvim-comment
 
-Toggle comments in Neovim, using built in **commentstring** filetype option; written in Lua.
-Without a doubt this plugin **is not required** and is a rip off of [TPope's Commentary](https://github.com/tpope/vim-commentary) with less features! What makes this plugin stand out over the numerous other comment plugins written in Lua are:
-
-* Doesn't require nightly build (works on NeoVim 0.4.x)
-* Comments each line, rather than adds block comments; making it easier to toggle code when debugging
-* Uses the built in **commentstring** buffer option to define comment markers
-* Where a marker doesn't have a **space** character as padding this is added, configurable
-** This can be disabled in the options, see below but if useful when workig with numerous linters
-* Supports motions
-
-When the plugin is called it works out the range to comment/uncomment; if all lines in the given range are commented then it uncomments, otherwise it comments the range. This is useful when commenting a block out for testing with a real like comment in it; as for the plugin a comment is a comment.
-
-# Usage
+Toggle comments in Neovim, using built in `commentstring` filetype option;
+written in Lua. Without a doubt this plugin **is not required** and is a rip off
+of [TPope's Commentary](https://github.com/tpope/vim-commentary) with less
+features! What makes this plugin stand out over the numerous other comment
+plugins written in Lua are:
+
+- Comments each line, rather than adds block comments; making it easier to
+  toggle code when debugging
+- Uses the built in `commentstring` buffer option to define comment markers
+- Where a marker doesn't have a **space** character as padding this is added,
+  configurable (this can be disabled in the options, see below but if useful
+  when working with numerous linters)
+- Supports motions
+- Dot `.` repeatable
+
+When the plugin is called it works out the range to comment/uncomment; if all
+lines in the given range are commented then it uncomments, otherwise it comments
+the range. This is useful when commenting a block out for testing with a real
+like comment in it; as for the plugin a comment is a comment.
+
+## Usage
 
 Either use the command `CommentToggle`, e.g.:
 
-* `CommentToggle` comment/uncomment current line
-* `67,69CommentToggle` comment/uncomment a range
-* `'<,'>CommentToggle` comment/uncomment a visual selection
+- `CommentToggle` comment/uncomment current line
+- `67,69CommentToggle` comment/uncomment a range
+- `'<,'>CommentToggle` comment/uncomment a visual selection
 
 Or use the default mappings:
 
-* `gcc` comment/uncomment current line, this does not take a count, if you want a count use the `gc{count}{motion}`
-* `gc{motion}` comment/uncomment selection defined by a motion:
-** As lines are commented, any comment toggling actions will default to a linewise.
-** `gcc` comment/uncomment current line
-** `gcip` comment/uncomment a paragraph
-** `gc4w` comment/uncomment current line
-** `gc4j` comment/uncomment 4 lines below the current line
+- `gcc` comment/uncomment current line, this does not take a count, if you want
+  a count use the `gc{count}{motion}`
+- `gc{motion}` comment/uncomment selection defined by a motion (as lines are
+  commented, any comment toggling actions will default to a linewise):
+  - `gcip` comment/uncomment a paragraph
+  - `gc4w` comment/uncomment current line
+  - `gc4j` comment/uncomment 4 lines below the current line
 
-## Configure
+### Configure
 
 The comment plugin needs to be initialised using:
+
 ```lua
 require('nvim_comment').setup()
 ```
@@ -50,40 +59,65 @@ However you can pass in some config options, the defaults are:
   -- Normal mode mapping left hand side
   line_mapping = "gcc",
   -- Visual/Operator mapping left hand side
-  operator_mapping = "gc"
+  operator_mapping = "gc",
+  -- Hook function to call before commenting takes place
+  hook = nil
 }
 ```
 
-**Ignore Empty Lines**
+- Ignore Empty Lines
+
 ```lua
 require('nvim_comment').setup({comment_empty = false})
 ```
 
-**Disable mappings**
+- Disable mappings
+
 ```lua
 require('nvim_comment').setup({create_mappings = false})
 ```
 
-**Custom mappings**
+- Custom mappings
+
 ```lua
 require('nvim_comment').setup({line_mapping = "<leader>cl", operator_mapping = "<leader>c"})
 ```
 
-**Disable marker padding**
+- Disable marker padding
+
 ```lua
 require('nvim_comment').setup({marker_padding = false})
 ```
 
-**Changing/Setting commentstring**
+- Hook function called before reading `commentstring`
 
-If you want to override the comment markers or add a new filetype just set the **commentstring** options:
+You can run arbitrary function which will be called before plugin reads value of
+`commentstring`. This can be used to integrate with
+[JoosepAlviste/nvim-ts-context-commentstring](https://github.com/JoosepAlviste/nvim-ts-context-commentstring):
+
+```lua
+require('nvim_comment').setup({
+  hook = function()
+    if vim.api.nvim_buf_get_option(0, "filetype") == "vue" then
+      require("ts_context_commentstring.internal").update_commentstring()
+    end
+  end
+})
+```
+
+- Changing/Setting `commentstring`
+
+If you want to override the comment markers or add a new filetype just set the
+`commentstring` options:
 
 ```lua
 -- Assumes this is being run in the context of the filetype...
 vim.api.nvim_buf_set_option(0, "commentstring", "# %s")
 ```
 
-You can also use an autocommand to automatically load your **commentstring** for certain file types:
+You can also use an autocommand to automatically load your `commentstring` for
+certain file types:
+
 ```vim
 " when you enter a (new) buffer
 augroup set-commentstring-ag
@@ -95,6 +129,7 @@ auground END
 ```
 
 Or add the comment string option in the relevant `filetype` file:
+
 ```vim
 let commentstring="# %s"
 ```
@@ -103,21 +138,22 @@ let commentstring="# %s"
 vim.api.nvim_buf_set_option(0, "commentstring", "# %s")
 ```
 
-# Installation
+## Installation
 
 Install just as you would a normal plugin, here are some options:
 
-**Built in package manager**
+### Built in package manager
 
 ```bash
 mkdir -p ~/.local/share/nvim/site/pack/plugins/start
 cd ~/.local/share/nvim/site/pack/plugins/start
 git clone https://github.com/terrortylor/nvim-comment
 ```
 
-**Via a plugin manager**
+### Via a plugin manager
 
 Using [nvim-pluginman](https://github.com/terrortylor/nvim-pluginman):
+
 ```lua
 plug.add({
   url = "terrortylor/nvim-comment",
@@ -128,6 +164,7 @@ plug.add({
 ```
 
 Using [packer.nvim](https://github.com/wbthomason/packer.nvim):
+
 ```lua
 use "terrortylor/nvim-comment"
 require('nvim_comment').setup()

lua/nvim_comment.lua

@@ -13,7 +13,9 @@ M.config = {
   -- Normal mode mapping left hand side
   line_mapping = "gcc",
   -- Visual/Operator mapping left hand side
-  operator_mapping = "gc"
+  operator_mapping = "gc",
+  -- Hook function to call before commenting takes place
+  hook = nil
 }
 
 function M.get_comment_wrapper()
@@ -88,6 +90,10 @@ function M.operator(mode)
 end
 
 function M.comment_toggle(line_start, line_end)
+  if type(M.config.hook) == 'function' then
+    M.config.hook()
+  end
+
   local left, right = M.get_comment_wrapper()
   if not left or not right then return end
 
@@ -138,7 +144,7 @@ function M.setup(user_opts)
   M.config = vim.tbl_extend('force', M.config, user_opts or {})
 
   -- Messy, change with nvim_exec once merged
-  vim.api.nvim_command('let g:loaded_text_objects_plugin = 1')
+  vim.g.loaded_text_objects_plugin = 1
   local vim_func = [[
   function! CommentOperator(type) abort
     let reg_save = @@
@@ -151,9 +157,9 @@ function M.setup(user_opts)
 
   if M.config.create_mappings then
     local opts = {noremap = true, silent = true}
-    vim.api.nvim_set_keymap("n", M.config.line_mapping, ":set operatorfunc=CommentOperator<cr>g@l", opts)
-    vim.api.nvim_set_keymap("n", M.config.operator_mapping, ":set operatorfunc=CommentOperator<cr>g@", opts)
-    vim.api.nvim_set_keymap("v", M.config.operator_mapping, ":<c-u>call CommentOperator(visualmode())<cr>", opts)
+    api.nvim_set_keymap("n", M.config.line_mapping, "<Cmd>set operatorfunc=CommentOperator<CR>g@l", opts)
+    api.nvim_set_keymap("n", M.config.operator_mapping, "<Cmd>set operatorfunc=CommentOperator<CR>g@", opts)
+    api.nvim_set_keymap("v", M.config.operator_mapping, ":<C-u>call CommentOperator(visualmode())<CR>", opts)
   end
 end