doc: example for functional config (#170)

* chore(doc): auto generate docs

* doc: add example for function config

* chore(doc): auto generate docs

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

ADVANCED.md

@@ -232,3 +232,36 @@ vim.api.nvim_create_autocmd("User", {
 [demo](https://github.com/xiaoshihou514/guard.nvim/assets/108414369/339ff4ff-288c-49e4-8ab1-789a6175d201)
 
 You can do the similar for your statusline plugin of choice as long as you "refresh" it on `GuardFmt`.
+
+## Dynamic formatters
+
+A formatter can be a function that returns a config, using this you can implement some pretty interesting behaviour, in [#168](https://github.com/nvimdev/guard.nvim/issues/168), one of the users asked for a particular formatter to respect editor space/tab settings. It's achievable by using `fn`, but using function configs are easier and more straight forward, let's see how we can cook up the behaviour we want:
+
+```lua
+local ft = require("guard.filetype")
+
+ft("c"):fmt(function()
+  if vim.uv.fs_stat(".clang-format") then
+    return {
+      cmd = "clang-format",
+      stdin = true,
+    }
+  else
+    return {
+      cmd = "clang-format",
+      args = {
+        ("--style={BasedOnStyle: llvm, IndentWidth: %d, TabWidth: %d, UseTab: %s}"):format(
+          vim.bo.shiftwidth,
+          vim.bo.tabstop,
+          vim.bo.expandtab and "Never" or "Always"
+        ),
+      },
+      stdin = true,
+    }
+  end
+end)
+```
+
+What we are doing here is try look for a `.clang-format` configuration file, if found, great, just use that. Otherwise, we want `clang-format` to respect the editor's settings, here I am using space/tab settings as an example, but you can easily tell that this can extend to anything.
+
+By using this config, we get a formatting behaviour that respects our _live 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:).

CUSTOMIZE.md

@@ -1,4 +1,5 @@
 # Creating new configurations
+
 A tool is specified as follows:
 
 ```lua
@@ -28,9 +29,10 @@ A tool is specified as follows:
 
 guard also tries to require them if you have `guard-collection`.
 
-You can also pass in a function that evaluates to the table above, it will be evaluated every time you call format.
+You can also pass in a function that evaluates to the table above, it will be evaluated every time you call format. See more [here](https://github.com/nvimdev/guard.nvim/blob/main/ADVANCED.md#dynamic-formatters)
 
 ## Examples: formatters
+
 Let's see a few formatters from `guard-collection`:
 
 ```lua
@@ -40,6 +42,7 @@ rustfmt = {
   stdin = true,
 }
 ```
+
 NB: Sometimes you may wish to run multiple formatters sequentially, this is only possible if you have `stdin` set ([or if you are using fn](./ADVANCED.md)) for all your formatters. This design is intentional for keeping buffer contents "valid". However, if you only wish to use one formatter, then letting the tool itself to do the IO _may be_ faster.
 
 ```lua
@@ -58,14 +61,17 @@ black = {
 ```
 
 ## Examples: linters
+
 In addition to all the formatter fields, a linter needs to provide a `parse` function that takes the linter output and turns it into neovim diagnostics (`:h vim.Diagnostic`).
 
 This sounds very cumbersome! Fortunately guard provides some api to make it smoother.
 
 Let's see an example: clang-tidy
+
 ```bash
 clang-tidy /tmp/test.c
 ```
+
 <details>
 <summary>Output</summary>
 
@@ -89,23 +95,27 @@ Running without flags.
       |                  ~~^~~
 
 ```
-</details>
 
+</details>
 
 In this case we are most interested in this line:
 
 ```
 /tmp/test.c:6:20: warning: Division by zero [clang-analyzer-core.DivideZero]
 ```
+
 And we can identify some elements:
+
 ```
 lnum = 6
 col = 20
 severity = warning
 message = Division by zero
 code = clang-analyzer-core.DivideZero
 ```
+
 The following regex will give us the elements, and we just need them in a table
+
 ```lua
 local xs = { line:match(":(%d+):(%d+):%s+(%w+):%s+(.-)%s+%[(.-)%]") }
 local lookup = { ... } -- omitted
@@ -137,7 +147,9 @@ clang_tidy = {
   }),
 }
 ```
+
 Another example:
+
 ```lua
 ktlint = {
   cmd = 'ktlint',
@@ -151,12 +163,15 @@ ktlint = {
   }),
 }
 ```
+
 Figuring out the patterns can take a while, so for tools that support json output, it's usually easier to take the json, put it into a table, and get the respective key.
 
 This pattern is encapsulated by `require("guard.lint").from_json`, an example:
+
 ```bash
 cat /tmp/test.py | pylint --from-stdin true --output-format json
 ```
+
 <details>
 <summary>Output</summary>
 
@@ -190,7 +205,7 @@ cat /tmp/test.py | pylint --from-stdin true --output-format json
     }
 ]
 
-```
+````
 </details>
 
 ```lua
@@ -212,9 +227,10 @@ pylint = {
     source = 'pylint',
   }),
 }
-```
+````
 
 Another example:
+
 ```lua
 ruff = {
   cmd = 'ruff',

doc/guard.nvim.txt

@@ -1,4 +1,4 @@
-*guard.nvim.txt*          For NVIM v0.8.0         Last change: 2024 October 24
+*guard.nvim.txt*          For NVIM v0.8.0         Last change: 2024 October 25
 
 ==============================================================================
 Table of Contents                               *guard.nvim-table-of-contents*
@@ -13,6 +13,7 @@ Table of Contents                               *guard.nvim-table-of-contents*
   - 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|
 
 ==============================================================================
@@ -154,7 +155,8 @@ A tool is specified as follows:
 guard also tries to require them if you have `guard-collection`.
 
 You can also pass in a function that evaluates to the table above, it will be
-evaluated every time you call format.
+evaluated every time you call format. See more here
+<https://github.com/nvimdev/guard.nvim/blob/main/ADVANCED.md#dynamic-formatters>
 
 
 EXAMPLES: FORMATTERS*guard.nvim-creating-new-configurations-examples:-formatters*
@@ -645,6 +647,50 @@ demo
 You can do the similar for your statusline plugin of choice as long as you
 "refresh" it on `GuardFmt`.
 
+
+DYNAMIC FORMATTERS               *guard.nvim-advanced-tips-dynamic-formatters*
+
+A formatter can be a function that returns a config, using this you can
+implement some pretty interesting behaviour, in #168
+<https://github.com/nvimdev/guard.nvim/issues/168>, one of the users asked for
+a particular formatter to respect editor space/tab settings. It’s achievable
+by using `fn`, but using function configs are easier and more straight forward,
+let’s see how we can cook up the behaviour we want:
+
+>lua
+    local ft = require("guard.filetype")
+
+    ft("c"):fmt(function()
+      if vim.uv.fs_stat(".clang-format") then
+        return {
+          cmd = "clang-format",
+          stdin = true,
+        }
+      else
+        return {
+          cmd = "clang-format",
+          args = {
+            ("--style={BasedOnStyle: llvm, IndentWidth: %d, TabWidth: %d, UseTab: %s}"):format(
+              vim.bo.shiftwidth,
+              vim.bo.tabstop,
+              vim.bo.expandtab and "Never" or "Always"
+            ),
+          },
+          stdin = true,
+        }
+      end
+    end)
+<
+
+What we are doing here is try look for a `.clang-format` configuration file, if
+found, great, just use that. Otherwise, we want `clang-format` to respect the
+editor’s settings, here I am using space/tab settings as an example, but you
+can easily tell that this can extend to anything.
+
+By using this config, we get a formatting behaviour that respects our _live
+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*