mini-comment.txt

*mini.comment* Comment lines
*MiniComment*

MIT License Copyright (c) 2021 Evgeni Chasnovski

==============================================================================

Features:
- Commenting in Normal mode respects |count| and is dot-repeatable.

- Comment structure by default is inferred from 'commentstring': either
  from current buffer or from locally active tree-sitter language (only on
  Neovim>=0.9). It can be customized via `options.custom_commentstring`
  (see |MiniComment.config| for details).

- Allows custom hooks before and after successful commenting.

- Configurable options for some nuanced behavior.

What it doesn't do:
- Block and sub-line comments. This will only support per-line commenting.

- Handle indentation with mixed tab and space.

- Preserve trailing whitespace in empty lines.

Notes:
- To use tree-sitter aware commenting, global value of 'commentstring'
  should be `''` (empty string). This is the default value in Neovim>=0.9,
  so make sure to not set it manually.

# Setup ~

This module needs a setup with `require('mini.comment').setup({})` (replace
`{}` with your `config` table). It will create global Lua table
`MiniComment` which you can use for scripting or manually (with
`:lua MiniComment.*`).

See |MiniComment.config| for `config` structure and default values.

You can override runtime config settings locally to buffer inside
`vim.b.minicomment_config` which should have same structure as
`MiniComment.config`. See |mini.nvim-buffer-local-config| for more details.

# Disabling ~

To disable core functionality, set `vim.g.minicomment_disable` (globally) or
`vim.b.minicomment_disable` (for a buffer) to `true`. Considering high number
of different scenarios and customization intentions, writing exact rules
for disabling module's functionality is left to user. See
|mini.nvim-disabling-recipes| for common recipes.

------------------------------------------------------------------------------
                                                           *MiniComment.setup()*
                         `MiniComment.setup`({config})
Module setup

Parameters ~
{config} `(table|nil)` Module config table. See |MiniComment.config|.

Usage ~
>lua
  require('mini.comment').setup() -- use default config
  -- OR
  require('mini.comment').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
                                                            *MiniComment.config*
                              `MiniComment.config`
Module config

Default values:
>lua
  MiniComment.config = {
    -- Options which control module behavior
    options = {
      -- Function to compute custom 'commentstring' (optional)
      custom_commentstring = nil,

      -- Whether to ignore blank lines when commenting
      ignore_blank_line = false,

      -- Whether to recognize as comment only lines without indent
      start_of_line = false,

      -- Whether to force single space inner padding for comment parts
      pad_comment_parts = true,
    },

    -- Module mappings. Use `''` (empty string) to disable one.
    mappings = {
      -- Toggle comment (like `gcip` - comment inner paragraph) for both
      -- Normal and Visual modes
      comment = 'gc',

      -- Toggle comment on current line
      comment_line = 'gcc',

      -- Toggle comment on visual selection
      comment_visual = 'gc',

      -- Define 'comment' textobject (like `dgc` - delete whole comment block)
      -- Works also in Visual mode if mapping differs from `comment_visual`
      textobject = 'gc',
    },

    -- Hook functions to be executed at certain stage of commenting
    hooks = {
      -- Before successful commenting. Does nothing by default.
      pre = function() end,
      -- After successful commenting. Does nothing by default.
      post = function() end,
    },
  }
<
# Options ~

## Custom commentstring ~

`options.custom_commentstring` can be a function customizing 'commentstring'
option used to infer comment structure. It is called once before every
commenting action with the following arguments:
- `ref_position` - position at which to compute 'commentstring' (might be
  relevant for a text with locally different commenting rules). Its structure
  is the same as `opts.ref_position` in |MiniComment.toggle_lines()|.

Its output should be a valid 'commentstring' (string containing `%s`).

If not set or the output is `nil`, |MiniComment.get_commentstring()| is used.

For example, this option can be used to always use buffer 'commentstring'
even in case of present active tree-sitter parser: >lua

  require('mini.comment').setup({
    options = {
      custom_commentstring = function() return vim.bo.commentstring end,
    }
  })
<
# Hooks ~

`hooks.pre` and `hooks.post` functions are executed before and after successful
commenting action (toggle or computing textobject). They will be called
with a single table argument which has the following fields:
- <action> `(string)` - action name. One of "toggle" (when actual toggle
  direction is yet unknown), "comment", "uncomment", "textobject".
- <line_start> `(number|nil)` - action start line. Can be absent if yet unknown.
- <line_end> `(number|nil)` - action end line. Can be absent if yet unknown.
- <ref_position> `(table|nil)` - reference position.

Notes:
- Changing 'commentstring' in `hooks.pre` is allowed and will take effect.
- If hook returns `false`, any further action is terminated.

------------------------------------------------------------------------------
                                                        *MiniComment.operator()*
                         `MiniComment.operator`({mode})
Main function to be mapped

It is meant to be used in expression mappings (see |map-<expr>|) to enable
dot-repeatability and commenting on range. There is no need to do this
manually, everything is done inside |MiniComment.setup()|.

It has a somewhat unintuitive logic (because of how expression mapping with
dot-repeatability works): it should be called without arguments inside
expression mapping and with argument when action should be performed.

Parameters ~
{mode} `(string|nil)` Optional string with 'operatorfunc' mode (see |g@|).

Return ~
`(string|nil)` 'g@' if called without argument, '' otherwise (but after
  performing action).

------------------------------------------------------------------------------
                                                    *MiniComment.toggle_lines()*
          `MiniComment.toggle_lines`({line_start}, {line_end}, {opts})
Toggle comments between two line numbers

It uncomments if lines are comment (every line is a comment) and comments
otherwise. It respects indentation and doesn't insert trailing
whitespace. Toggle commenting not in visual mode is also dot-repeatable
and respects |count|.

# Notes ~

- Comment structure is inferred from buffer's 'commentstring' option or
  local language of tree-sitter parser (if active; only on Neovim>=0.9).

- Call to this function will remove all |extmarks| from target range.

Parameters ~
{line_start} `(number)` Start line number (inclusive from 1 to number of lines).
{line_end} `(number)` End line number (inclusive from 1 to number of lines).
{opts} `(table|nil)` Options. Possible fields:
  - <ref_position> `(table)` - A two-value array with `{ row, col }` (both
    starting at 1) of reference position at which 'commentstring' value
    will be computed. Default: `{ line_start, 1 }`.

------------------------------------------------------------------------------
                                                      *MiniComment.textobject()*
                           `MiniComment.textobject`()
Select comment textobject

This selects all commented lines adjacent to cursor line (if it itself is
commented). Designed to be used with operator mode mappings (see |mapmode-o|).

------------------------------------------------------------------------------
                                               *MiniComment.get_commentstring()*
                `MiniComment.get_commentstring`({ref_position})
Get 'commentstring'

This function represents default approach of computing relevant
'commentstring' option in current buffer. Used to infer comment structure.

It has the following logic:
- (Only on Neovim>=0.9) If there is an active tree-sitter parser, try to get
  'commentstring' from the local language at `ref_position`.

- If first step is not successful, use buffer's 'commentstring' directly.

Parameters ~
{ref_position} `(table)` Reference position inside current buffer at which
  to compute 'commentstring'. Same structure as `opts.ref_position`
  in |MiniComment.toggle_lines()|.

Return ~
`(string)` Relevant value of 'commentstring'.


 vim:tw=78:ts=8:noet:ft=help:norl: