summaryrefslogtreecommitdiff
path: root/mut/vis/vis-format/README.md
diff options
context:
space:
mode:
authorMike Vink <59492084+ivi-vink@users.noreply.github.com>2025-01-29 14:24:53 +0000
committerMike Vink <59492084+ivi-vink@users.noreply.github.com>2025-01-29 14:24:53 +0000
commit8eaa94e7af55bc6ceb2ffbd208143efcf392370a (patch)
tree387db097736ead99be705eb385b6ee12597e4024 /mut/vis/vis-format/README.md
parent83373a6b042f9eb552b4ebaffc35a21c77e78cec (diff)
fixup
Diffstat (limited to 'mut/vis/vis-format/README.md')
-rw-r--r--mut/vis/vis-format/README.md153
1 files changed, 0 insertions, 153 deletions
diff --git a/mut/vis/vis-format/README.md b/mut/vis/vis-format/README.md
deleted file mode 100644
index 4435542..0000000
--- a/mut/vis/vis-format/README.md
+++ /dev/null
@@ -1,153 +0,0 @@
-# vis-format - integrates vis with external formatters
-
-A plugin for [vis](https://github.com/martanne/vis) to integrate `prettier`,
-`rustfmt` etc.
-
-### Installation
-
-Clone this repository to where you install your plugins. (If this is your first
-plugin, running `git clone https://github.com/milhnl/vis-format` in
-`~/.config/vis/` will probably work).
-
-Then, add something like the following to your `visrc`.
-
- local format = require('vis-format')
- vis:map(vis.modes.NORMAL, '=', format.apply)
-
-### Usage
-
-Press `=` to format the whole file.
-
-Currently, the following formatters are supported out-of-the-box.
-
-- `bash`: [shfmt](https://github.com/mvdan/sh)
-- `csharp`: [CSharpier](https://csharpier.com/). Although
- [dotnet-format](https://github.com/dotnet/format) is the 'default' formatter
- for dotnet, it does not support formatting stdin (and does not break lines).
-- `git-commit`: Actually `diff` with an extra check, as that's how
- `vis.ftdetect` ends up labeling it. Uses `fmt -w` and some glue code to
- reformat the commit body, but not the summary and comments.
-- `go`: `gofmt`
-- `lua`: [StyLua](https://github.com/JohnnyMorganz/StyLua) and
- [LuaFormatter](https://github.com/Koihik/LuaFormatter), depending on which
- config file is in the working directory.
-- `markdown`: `prettier` with `--prose-wrap` enabled if `colorcolumn` is set.
-- `powershell`:
- [PSScriptAnalyzer](https://learn.microsoft.com/en-gb/powershell/utility-modules/psscriptanalyzer/overview?view=ps-modules#installing-psscriptanalyzer)
- via `powershell.exe` in the WSL if available or `pwsh`.
-- `rust`: `rustfmt`
-- `text`: `fmt` with width based on colorcolumn if set, otherwise joined
- paragraphs.
-
-I'm working on some more heuristics for detecting which formatter to use for
-languages without a 'blessed' formatter. In the meantime, this is how you add
-the ones you want to use:
-
- format.formatters.html = format.stdio_formatter("prettier --parser html")
-
-### Advanced usage
-
-The following methods and tables are fields of the table that is returned by
-`require('vis-format')` (e.g. `format`). You can use them to extend or
-configure `vis-format`.
-
-#### `formatters`
-
-A table containing the configured formatters. There are some predefined (see
-the list above under "Usage"), and you can add or override those by assigning
-your formatter to a key corresponding to the vis `syntax` it is relevant for.
-Each entry is of either of these forms:
-
- {
- apply = func(win, range, pos) end,
- options = {
- ranged = nil,
- check_same = nil,
- }
- }
-
-or
-
- {
- pick = func(win, range, pos) end,
- }
-
-The first form directly defines a formatter. An entry containing `pick` is
-executed and its result is directly used as a formatter. A recommended way to
-use `pick` is to return a different formatter from the `formatters` table. Note
-that using the vis `syntax` as keys in this table is only necessary for
-formatters that are run directly. This means that `lua` is a good key for a
-`pick` entry, which chooses between the formatters found at `stylua` and
-`luaformatter`.
-
-#### `stdio_formatter`
-
-The `stdio_formatter` function wraps the command to produce something like
-this:
-
- {
- apply = function(win, range, pos) end,
- options = { ranged = false }
- }
-
-The command given can also be a function, which is expected to return a string,
-which is then used as a command. This allows you to use the given range, or
-options from `win`. `ranged` is automatically set to true in this case.
-
-Apart from mapping `vis-format` in normal mode, you can also define an operator
-(with `vis:operator_new`) to format ranges of code/text. This will require a
-formatter that can work with ranges of text. Configuring that looks like this:
-
- -- Add a formatter that can use a range
- format.formatters.lua = format.stdio_formatter(function(win, range, pos)
- return 'stylua -s --range-start ' .. range.start .. ' --range-end '
- .. range.finish .. ' -'
- end)
-
- -- Bind it to keys
- vis:operator_new('=', format.apply) -- this'll handle ranges
- vis:map(vis.modes.NORMAL, '=', function() -- this'll format whole files
- format.apply(vis.win.file, nil, vis.win.selection.pos)
- end)
-
-#### `with_filename`
-
-Most formatters take a path for where `stdin` would be. If the file has a path
-`with_filename` concatenates the option and the shell-escaped path. Note that
-it does not add any spaces to separate options/arguments.
-
- stdio_formatter(function(win)
- return 'shfmt ' .. with_filename(win, '--filename ') .. ' -'
- end, { ranged = false })
-
-#### `options`
-
-- `options.check_same` (`boolean|number`) — After formatting, to avoid updating
- the file, `vis-format` can compare the old and the new. If this is set to a
- number, that's the maximum size of the file for which it is enabled. This
- option is also available in the per-formatter options.
-
-### Bugs
-
-Ranged formatting is not enabled and will currently not work with `prettier`.
-Prettier extends the range given on the command line to the beginning and end
-of the statement containing it. This will not work with how `vis-format`
-currently applies the output. I have some ideas on how to fix this, but wanted
-to release what works first.
-
-#### Note on editor options and vis versions before 0.9
-
-`vis` has an `options` table with editor settings like tab width etc. built-in
-since 0.9. `vis-format` will not read this most of the time, because the
-correct way to configure formatters is with their dedicated configuration
-files, or `.editorconfig` (Which can be read in vis with
-[vis-editorconfig](https://github.com/seifferth/vis-editorconfig) and
-[vis-editorconfig-options](https://github.com/milhnl/vis-editorconfig-options)
-).
-
-The included formatter integrations that _do_ use this information assume that
-the `options` table in `vis` and `win` is present. If you use an older version,
-`vis-format` will still work, but can't detect your editor settings. To fix
-that, look at the
-[vis-options-backport](https://github.com/milhnl/vis-options-backport) plugin.
-This will 'polyfill' that for older versions.