Added Readme and docs

README.md

@@ -0,0 +1,102 @@
+# Format.nvim
+
+format.nvim applies formatting to the current buffer.
+
+Main goals
+
+1. fast
+2. async
+3. no magic
+
+## Details
+
+format.nvim is a lua plugin and only works in Neovim.
+
+It writes the buffer content into a temporary file, runs user defined commands
+on that file, then writes the content back into the buffer.
+
+Everything happens asynchronously.
+
+There is no hidden configuration to resolve executables. The commands are run as
+is. If you need a specific executable, define the path in the command.
+
+By defalt unsaved changes will not be overwritten, so `Format` and `FormatWrite`
+are save to call anytime.
+
+## Embedded syntax blocks.
+
+format.nvim supports formatting embedded blocks of code with different
+command than the current filetype. For example `lua << EOF` blocks in
+vimscript, or code blocks in markdown.
+Just specify a start and end-pattern.
+
+## Format on save
+
+There is no format on save functionality build in, the plugin only provides the
+`Format` and `FormatWrite` commands.
+To format on save, you can put this in your `vimrc`
+
+```vimscript
+augroup Format
+    autocmd!
+    autocmd BufWritePost * FormatWrite
+augroup END
+```
+
+## Example configuration
+
+Please see `:help format.txt` for more information on configuration.
+
+````lua
+require "format".setup {
+    ["*"] = {
+        {cmd = {"sed -i 's/[ \t]*$//'"}} -- remove trailing whitespace
+    },
+    vim = {
+        {
+            cmd = {"luafmt -w replace"},
+            start_pattern = "^lua << EOF$",
+            end_pattern = "^EOF$"
+        }
+    },
+    vimwiki = {
+        {
+            cmd = {"prettier -w --parser babel"},
+            start_pattern = "^{{{javascript$",
+            end_pattern = "^}}}$"
+        }
+    },
+    lua = {
+        {
+            cmd = {
+                function(file)
+                    return string.format("luafmt -l %s -w replace %s", vim.bo.textwidth, file)
+                end
+            }
+        }
+    },
+    go = {
+        {
+            cmd = {"gofmt -w", "goimports -w"},
+            tempfile_postfix = ".tmp"
+        }
+    },
+    javascript = {
+        {cmd = {"prettier -w", "./node_modules/.bin/eslint --fix"}}
+    },
+    markdown = {
+        {cmd = {"prettier -w"}},
+        {
+            cmd = {"black"},
+            start_pattern = "^```python$",
+            end_pattern = "^```$",
+            target = "current"
+        }
+    }
+}
+````
+
+## Mentions
+
+At first this was supposed to be a PR to [mhartington/formatter.nvim](https://github.com/mhartington/formatter.nvim)
+but I ended up rewriting everything.

doc/format.txt

@@ -0,0 +1,225 @@
+*format.txt*                  Format the current buffer with external commands
+
+
+Author: Lukas Reineke <lukas.reineke@protonmail.com>
+Version: 1.0.0
+
+==============================================================================
+CONTENTS                                                              *format*
+
+  1. Introduction                          |format-introduction|
+  2. Setup                                 |format-setup|
+  3. Variables                             |format-variables|
+  4. Commands                              |format-commands|
+  5. Changelog                             |format-changelog|
+  6. License                               |format-license|
+
+==============================================================================
+ 1. INTRODUCTION                               *format-introduction*
+
+format.nvim applies formatting to the current buffer.
+
+Main goals
+1. fast
+2. async
+3. no magic
+
+------------------------------------------------------------------------------
+
+Details
+
+format.nvim is a lua plugin and only works in Neovim.
+
+It writes the buffer content into a temporary file, runs user defined commands
+on that file, then writes the content back into the buffer.
+
+Everything happens asynchronously.
+
+There is no hidden configuration to resolve executables. The commands are run as
+is. If you need a specific executable, define the path in the command.
+
+By defalt unsaved changes will not be overwritten, so `Format` and `FormatWrite`
+are save to call anytime.
+
+------------------------------------------------------------------------------
+
+Embedded syntax blocks
+
+format.nvim supports formatting embedded blocks of code with different
+command than the current filetype. For example `lua << EOF` blocks in
+vimscript, or code blocks in markdown.
+
+==============================================================================
+ 3. SETUP                                                       *format-setup*
+
+To setup formatting, call the `setup` function.
+`lua require "format".setup {}`
+
+The setup table is a list of |filetypes|, each with a list of format tables.
+`*` can be used as a filetype wildcard.
+ >
+    require "format".setup {
+        lua = {
+            {cmd = {"luafmt -w replace"}}
+        }
+    }
+
+One format table can have following keys
+
+    cmd:                                                                     ~
+        Table of either command strings or functions that get the temporary
+        file path as argument and need to return a command string
+        The commands will be run in sequence
+    start_pattern:                                                           ~
+        Regex to define a pattern where an embedded syntax block starts
+        The whole file is formatted when left empty
+    end_pattern:                                                             ~
+        Regex to define a pattern where an embedded syntax block ends
+        The whole file is formatted when left empty
+    tempfile_prefix:                                                         ~
+        String to prepend to the temporary file
+        Defaults to "~formatting"
+    tempfile_postfix:                                                        ~
+        String to append to the temporary file
+        Defaults to ""
+    target:                                                                  ~
+        Either "all" or "current"
+        When "current", the plugin only formats embedded syntax blocks when the
+        cursor is in them.
+        When "all" the plugin formats all embedded syntax blocks in the buffer.
+        Defaults to "all"
+
+Example configuration >
+
+    require "format".setup {
+        ["*"] = {
+            {cmd = {"sed -i 's/[ \t]*$//'"}} -- remove trailing whitespace
+        },
+        vim = {
+            {
+                cmd = {"luafmt -w replace"},
+                start_pattern = "^lua << EOF$",
+                end_pattern = "^EOF$"
+            }
+        },
+        vimwiki = {
+            {
+                cmd = {"prettier -w --parser babel"},
+                start_pattern = "^{{{javascript$",
+                end_pattern = "^}}}$"
+            }
+        },
+        lua = {
+            {
+                cmd = {
+                    function(file)
+                        return string.format("luafmt -l %s -w replace %s", vim.bo.textwidth, file)
+                    end
+                }
+            }
+        },
+        go = {
+            {
+                cmd = {"gofmt -w", "goimports -w"},
+                tempfile_postfix = ".tmp"
+            }
+        },
+        javascript = {
+            {cmd = {"prettier -w", "./node_modules/.bin/eslint --fix"}}
+        },
+        markdown = {
+            {cmd = {"prettier -w"}},
+            {
+                cmd = {"black"},
+                start_pattern = "^```python$",
+                end_pattern = "^```$",
+                target = "current"
+            }
+        }
+    }
+
+
+==============================================================================
+ 3. VARIABLES                                               *format-variables*
+
+g:format_debug                                                *g:format_debug*
+
+    Turns on logging.
+
+    Default: v:false                                                         ~
+
+    Example: >
+
+        let g:format_debug = v:true
+
+==============================================================================
+ 4. COMMANDS                                                 *format-commands*
+
+Format                                                                *Format*
+
+    Formats the current buffer.
+
+    Bang:
+        By default |Format| will not overwrite unsaved changes.
+        Running it with a bang `:Format!` will overwrite changes.
+
+    Range:
+        |Format| takes a range to apply the formatting to.
+        By default it is run on the whole file.
+
+    Example: >
+
+        autocmd BufWritePre * Format
+
+------------------------------------------------------------------------------
+FormatWrite                                                      *FormatWrite*
+
+    Formats the current buffer like |Format|. Then calls |:update| to save the
+    changes if there are any.
+
+    Bang:
+        By default |FormatWrite| will not overwrite unsaved changes.
+        Running it with a bang `:FormatWrite!` will overwrite changes.
+
+    Range:
+        |FormatWrite| takes a range to apply the formatting to.
+        By default it is run on the whole file.
+
+    Example: >
+
+        autocmd BufWritePre * FormatWrite
+
+==============================================================================
+ 5. CHANGELOG                                               *format-changelog*
+
+1.0.0
+  * First release
+
+==============================================================================
+ 6. LICENSE                                                   *format-license*
+
+The MIT Licence
+http://www.opensource.org/licenses/mit-license.php
+
+Copyright (c) 2020 Lukas Reineke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+==============================================================================
+vim:tw=78:ts=8:ft=help:norl

lua/format/embedded.lua

@@ -24,7 +24,7 @@ function M.format_all_embedded(current, options, line, step)
         M.format_all_embedded(current, options, options.endline, step)
     end
 
-    format(current.formatter, options, callback)
+    format(current.cmd, options, callback)
 
     vim.fn.winrestview(view)
 end
@@ -42,7 +42,7 @@ function M.format_embedded(current, options, step)
     options.startline = startline + 1
     options.endline = endline - 1
 
-    format(current.formatter, options, step)
+    format(current.cmd, options, step)
 end
 
 return M

lua/format/format.lua

@@ -8,9 +8,9 @@ function expand_cmd(cmd, tempfile_name)
     return string.format("%s %s", cmd, tempfile_name)
 end
 
-function M.format(formatter, options, callback)
+function M.format(cmd, options, callback)
     options.startline = options.startline - 1
-    formatter = {unpack(formatter)}
+    cmd = {unpack(cmd)}
 
     local bufname = vim.fn.bufname(options.bufnr)
     local lines = vim.api.nvim_buf_get_lines(options.bufnr, options.startline, options.endline, true)
@@ -72,8 +72,8 @@ function M.format(formatter, options, callback)
             print(string.format("Format event %s: %s %s", job_id, event, vim.inspect(data)))
         end
         if event == "exit" then
-            if #formatter > 0 then
-                F.run_job(table.remove(formatter, 1))
+            if #cmd > 0 then
+                F.run_job(table.remove(cmd, 1))
             else
                 F.done()
             end
@@ -98,7 +98,7 @@ function M.format(formatter, options, callback)
         end
     end
 
-    return F.run_job(table.remove(formatter, 1))
+    return F.run_job(table.remove(cmd, 1))
 end
 
 return M

lua/format/init.lua

@@ -38,8 +38,10 @@ function M.format(bang, write, startline, endline)
                     undojoin = undojoin
                 }
 
-                if current.start_pattern == nil or current.end_pattern == nil then
-                    format(current.formatter, options, step)
+                if current.cmd == nil then
+                    step()
+                elseif current.start_pattern == nil or current.end_pattern == nil then
+                    format(current.cmd, options, step)
                 elseif current.target ~= "current" then
                     embedded.format_all_embedded(current, options, 1, step)
                 else