*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: - `(string)` - action name. One of "toggle" (when actual toggle direction is yet unknown), "comment", "uncomment", "textobject". - `(number|nil)` - action start line. Can be absent if yet unknown. - `(number|nil)` - action end line. Can be absent if yet unknown. - `(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-|) 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: - `(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: