diff --git a/README.md b/README.md index 30d3d8f..80088a9 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,3 @@ -# guard.nvim - [![LuaRocks](https://img.shields.io/luarocks/v/xiaoshihou514/guard.nvim?logo=lua&color=green)](https://luarocks.org/modules/xiaoshihou514/guard.nvim) ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/nvimdev/guard.nvim/test.yml?label=tests) ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/nvimdev/guard.nvim/ci.yml?label=lint) @@ -13,94 +11,116 @@ Async formatting and linting utility for neovim `0.10+`. - Minimal API allowing for full customization - Light-weight -## Usage +## TLDR -For rocks.nvim +[`help guard.nvim-tldr`](#tldr) -```vim -Rocks install guard.nvim +- Install with your favorite package manager + +``` +nvimdev/guard.nvim ``` -For lazy.nvim +- Register formatters: ```lua -{ - "nvimdev/guard.nvim", - -- lazy load by ft - ft = { "lua", "c", "markdown" }, - -- Builtin configuration, optional - dependencies = { - "nvimdev/guard-collection", - }, -} +local ft = require('guard.filetype') +ft('c'):fmt('clang-format') ``` -To register formatters and linters: +[demo](https://github.com/user-attachments/assets/3160f979-6683-4288-870d-2447ee445431) + +- Register linters ```lua local ft = require('guard.filetype') +ft('lua'):lint('selene') +``` --- Assuming you have guard-collection --- Put this in your ftplugin/lang.lua to lazy load guard -ft('lang'):fmt('format-tool-1') - :append('format-tool-2') - :env(env_table) - :lint('lint-tool-1') - :extra(extra_args) +[demo](https://github.com/user-attachments/assets/2ee2fdaa-42b2-41b3-80ad-26a53bf16809) --- change this anywhere in your config (or not), these are the defaults -vim.g.guard_config = { - -- format on write to buffer - fmt_on_save = true, - -- use lsp if no formatter was defined for this filetype - lsp_as_default_formatter = false, - -- whether or not to save the buffer after formatting - save_on_fmt = true, - -- automatic linting - auto_lint = true, - -- how frequently can linters be called - lint_interval = 500 -} +- They can also be chained together: + +```lua +local ft = require('guard.filetype') +ft('haskell'):fmt('ormolu') + :lint('hlint') ``` -- Use `Guard fmt` to manually call format, when there is a visual selection only the selection is formatted. **NOTE**: Regional formatting is best-effort, expect inconsistencies. -- `enable-fmt`, `disable-fmt` turns auto formatting on and off for the current buffer. -- Use `Guard Lint` to lint manually. -- `enable-lint` and `disable-lint` controls auto linting for the current buffer. +- Formatters and linters can also be chained: -## Examples +```lua +local ft = require('guard.filetype') +ft('python'):fmt('isort') + :append('black') + :lint('mypy') + :append('mypyc') + :append('dmypy') +``` -Format c files with clang-format and lint with clang-tidy: +- You can register the same formatter for multiple filetypes: ```lua -ft('c'):fmt('clang-format') - :lint('clang-tidy') +local ft = require('guard.filetype') +ft('typescript,javascript,typescriptreact'):fmt('prettier') ``` -Or use lsp to format lua files first, then format with stylua, then lint with selene: +- Lint all your files with `codespell` ```lua -ft('lua'):fmt('lsp') - :append('stylua') - :lint('selene') +-- this does not work with formatters +ft('*'):lint('codespell') ``` -Register multiple filetypes to a single linter or formatter: +- Custom formatters: ```lua -ft('typescript,javascript,typescriptreact'):fmt('prettier') +-- always use 4 spaces for c files +ft('c'):fmt({ + cmd = "clang-format", + args = { "--style={IndentWidth: 4}" }, + stdin = true, +}) ``` -Lint all your files with `codespell` +## Usage + +[`help guard.nvim-usage`](#usage) + +Some presets can be configured via `vim.g.guard_config` ```lua --- NB: this does not work with formatters -ft('*'):lint('codespell') +-- defaults +vim.g.guard_config = { + -- format on write to buffer + fmt_on_save = true, + -- use lsp if no formatter was defined for this filetype + lsp_as_default_formatter = false, + -- whether or not to save the buffer after formatting + save_on_fmt = true, + -- automatic linting + auto_lint = true, + -- how frequently can linters be called + lint_interval = 500 +} ``` -You can also easily create your own configuration that's not in `guard-collection`, see [CUSTOMIZE.md](./CUSTOMIZE.md). +Here are all the `Guard` subcommands + +| Name | Desc | +| :----------------: | :------------------------------------------------------------------------------: | +| Guard fmt | Manually call format, also works with visual mode (best effort range formatting) | +| Guard lint | Manually request for lint | +| Guard enable-fmt | Turns auto formatting on for the current buffer | +| Guard disable-fmt | Turns auto formatting off for the current buffer | +| Guard enable-lint | Turns linting on for the current buffer | +| Guard disable-lint | Turns linting off for the current buffer | + +## Further configuration + +You can easily create your own configuration that's not in `guard-collection`, see [`help guard.nvim-creating-new-configurations`](./CUSTOMIZE.md). -For more niche use cases, [ADVANCED.md](./ADVANCED.md) demonstrates how to: +For more niche use cases, [`help guard.nvim-advanced-tips`](./ADVANCED.md) demonstrates how to: - Write your own formatting logic using the `fn` field. - Write your own linting logic using the `fn` field. diff --git a/doc/guard.nvim.txt b/doc/guard.nvim.txt index 1db0c34..7b09d20 100644 --- a/doc/guard.nvim.txt +++ b/doc/guard.nvim.txt @@ -1,31 +1,27 @@ -*guard.nvim.txt* For NVIM v0.8.0 Last change: 2025 January 19 +*guard.nvim.txt* For NVIM v0.8.0 Last change: 2025 February 22 ============================================================================== Table of Contents *guard.nvim-table-of-contents* -1. guard.nvim |guard.nvim-guard.nvim| - - Features |guard.nvim-guard.nvim-features| - - Usage |guard.nvim-guard.nvim-usage| - - Examples |guard.nvim-guard.nvim-examples| -2. Creating new configurations |guard.nvim-creating-new-configurations| + - Features |guard.nvim-features| + - TLDR |guard.nvim-tldr| + - Usage |guard.nvim-usage| + - Further configuration |guard.nvim-further-configuration| +1. Creating new configurations |guard.nvim-creating-new-configurations| - Examples: formatters|guard.nvim-creating-new-configurations-examples:-formatters| - Examples: linters|guard.nvim-creating-new-configurations-examples:-linters| -3. Advanced tips |guard.nvim-advanced-tips| +2. Advanced tips |guard.nvim-advanced-tips| - Special case formatting logic|guard.nvim-advanced-tips-special-case-formatting-logic| - Custom logic with linters|guard.nvim-advanced-tips-custom-logic-with-linters| - Take advantage of autocmd events|guard.nvim-advanced-tips-take-advantage-of-autocmd-events| - Dynamic formatters |guard.nvim-advanced-tips-dynamic-formatters| -4. Links |guard.nvim-links| - -============================================================================== -1. guard.nvim *guard.nvim-guard.nvim* - +3. Links |guard.nvim-links| Async formatting and linting utility for neovim `0.10+`. -FEATURES *guard.nvim-guard.nvim-features* +FEATURES *guard.nvim-features* - Async and blazingly fast - Builtin support for popular formatters and linters @@ -33,42 +29,89 @@ FEATURES *guard.nvim-guard.nvim-features* - Light-weight -USAGE *guard.nvim-guard.nvim-usage* +TLDR *guard.nvim-tldr* + +|guard.nvim-`help-guard.nvim-tldr`| -For rocks.nvim +- Install with your favorite package manager ->vim - Rocks install guard.nvim +> + nvimdev/guard.nvim < -For lazy.nvim +- Register formatters: >lua - { - "nvimdev/guard.nvim", - -- lazy load by ft - ft = { "lua", "c", "markdown" }, - -- Builtin configuration, optional - dependencies = { - "nvimdev/guard-collection", - }, - } + local ft = require('guard.filetype') + ft('c'):fmt('clang-format') < -To register formatters and linters: +demo + + +- Register linters >lua local ft = require('guard.filetype') - - -- Assuming you have guard-collection - -- Put this in your ftplugin/lang.lua to lazy load guard - ft('lang'):fmt('format-tool-1') - :append('format-tool-2') - :env(env_table) - :lint('lint-tool-1') - :extra(extra_args) - - -- change this anywhere in your config (or not), these are the defaults + ft('lua'):lint('selene') +< + +demo + + +- They can also be chained together: + +>lua + local ft = require('guard.filetype') + ft('haskell'):fmt('ormolu') + :lint('hlint') +< + +- Formatters and linters can also be chained: + +>lua + local ft = require('guard.filetype') + ft('python'):fmt('isort') + :append('black') + :lint('mypy') + :append('mypyc') + :append('dmypy') +< + +- You can register the same formatter for multiple filetypes: + +>lua + local ft = require('guard.filetype') + ft('typescript,javascript,typescriptreact'):fmt('prettier') +< + +- Lint all your files with `codespell` + +>lua + -- this does not work with formatters + ft('*'):lint('codespell') +< + +- Custom formatters: + +>lua + -- always use 4 spaces for c files + ft('c'):fmt({ + cmd = "clang-format", + args = { "--style={IndentWidth: 4}" }, + stdin = true, + }) +< + + +USAGE *guard.nvim-usage* + +|guard.nvim-`help-guard.nvim-usage`| + +Some presets can be configured via `vim.g.guard_config` + +>lua + -- defaults vim.g.guard_config = { -- format on write to buffer fmt_on_save = true, @@ -83,47 +126,37 @@ To register formatters and linters: } < -- Use `Guard fmt` to manually call format, when there is a visual selection only the selection is formatted. **NOTE**: Regional formatting is best-effort, expect inconsistencies. -- `enable-fmt`, `disable-fmt` turns auto formatting on and off for the current buffer. -- Use `Guard Lint` to lint manually. -- `enable-lint` and `disable-lint` controls auto linting for the current buffer. - - -EXAMPLES *guard.nvim-guard.nvim-examples* +Here are all the `Guard` subcommands -Format c files with clang-format and lint with clang-tidy: - ->lua - ft('c'):fmt('clang-format') - :lint('clang-tidy') -< + ------------------------------------------------------------------------ + Name Desc + -------------- --------------------------------------------------------- + Guard fmt Manually call format, also works with visual mode (best + effort range formatting) -Or use lsp to format lua files first, then format with stylua, then lint with -selene: + Guard lint Manually request for lint ->lua - ft('lua'):fmt('lsp') - :append('stylua') - :lint('selene') -< + Guard Turns auto formatting on for the current buffer + enable-fmt -Register multiple filetypes to a single linter or formatter: + Guard Turns auto formatting off for the current buffer + disable-fmt ->lua - ft('typescript,javascript,typescriptreact'):fmt('prettier') -< + Guard Turns linting on for the current buffer + enable-lint -Lint all your files with `codespell` + Guard Turns linting off for the current buffer + disable-lint + ------------------------------------------------------------------------ ->lua - -- NB: this does not work with formatters - ft('*'):lint('codespell') -< +FURTHER CONFIGURATION *guard.nvim-further-configuration* -You can also easily create your own configuration that’s not in -`guard-collection`, see CUSTOMIZE.md <./CUSTOMIZE.md>. +You can easily create your own configuration that’s not in +`guard-collection`, see `help guard.nvim-creating-new-configurations` +<./CUSTOMIZE.md>. -For more niche use cases, ADVANCED.md <./ADVANCED.md> demonstrates how to: +For more niche use cases, `help guard.nvim-advanced-tips` <./ADVANCED.md> +demonstrates how to: - Write your own formatting logic using the `fn` field. - Write your own linting logic using the `fn` field. @@ -132,7 +165,7 @@ For more niche use cases, ADVANCED.md <./ADVANCED.md> demonstrates how to: ============================================================================== -2. Creating new configurations *guard.nvim-creating-new-configurations* +1. Creating new configurations *guard.nvim-creating-new-configurations* A tool is specified as follows: @@ -400,7 +433,7 @@ Another example: ============================================================================== -3. Advanced tips *guard.nvim-advanced-tips* +2. Advanced tips *guard.nvim-advanced-tips* SPECIAL CASE FORMATTING LOGIC*guard.nvim-advanced-tips-special-case-formatting-logic* @@ -702,7 +735,7 @@ input_, you can run `set sw=16` and the next time `clang-format` will give you a file that uses 16 spaces as indent (please do not try this at home :smile:). ============================================================================== -4. Links *guard.nvim-links* +3. Links *guard.nvim-links* 1. *LuaRocks*: https://img.shields.io/luarocks/v/xiaoshihou514/guard.nvim?logo=lua&color=green 2. *GitHub Actions Workflow Status*: https://img.shields.io/github/actions/workflow/status/nvimdev/guard.nvim/test.yml?label=tests