#2132 - Document ale#command#Run

1 files changed, 91 insertions, 71 deletions

diff --git a/doc/ale.txt b/doc/ale.txt
index efba5e35..44ddb2e2 100644
--- a/doc/ale.txt
+++ b/doc/ale.txt
@@ -580,8 +580,8 @@ for a function set in the ALE fixer registry.
 Each function for fixing errors must accept either one argument `(buffer)` or
 two arguments `(buffer, lines)`, representing the buffer being fixed and the
 lines to fix. The functions must return either `0`, for changing nothing, a
-|List| for new lines to set, or a |Dictionary| for describing a command to be
-run in the background.
+|List| for new lines to set, a |Dictionary| for describing a command to be
+run in the background, or the result of |ale#command#Run()|.
 
 Functions receiving a variable number of arguments will not receive the second
 argument `lines`. Functions should name two arguments if the `lines` argument
@@ -611,26 +611,6 @@ are supported for running the commands.
 
                       A |List| of |String|s must be returned.
 
-  `chain_with`          An optional key for defining a callback to call next.
-
-                      The callback must accept two or three arguments,
-                      `(buffer, output)` or `(buffer, output, input)` .
-                      Functions receiving a variable number of arguments will
-                      only receive the first two values. The `output` argument
-                      will contain the lines of output from the command run.
-                      The `input` argument is the List of lines for the
-                      buffer, after applying any previous fixers.
-
-                      The callback must return the same values returned for
-                      any fixer function. This allows fixer functions to be
-                      chained recursively.
-
-                      When the command string returned for a fixer is an empty
-                      string, the next command in the chain will still be run.
-                      This allows commands to be skipped, like version checks
-                      that are cached. An empty List will be passed to the
-                      next callback in the chain for the `output`.
-
   `read_buffer`         An optional key for disabling reading the buffer.
 
                       When set to `0`, ALE will not pipe the buffer's data
@@ -638,10 +618,7 @@ are supported for running the commands.
                       the buffer is not read when `read_temporary_file` is
                       `1`.
 
-                      This option defaults to `0` when `chain_with` is defined
-                      as anything other than `v:null`, and defaults to `1`
-                      otherwise. This is so earlier commands in a chain
-                      do not receive the buffer's data by default.
+                      This option defaults to `1`.
 
                                                         *ale-fix-configuration*
 
@@ -2936,6 +2913,85 @@ ale#command#CreateFile(buffer)                       *ale#command#CreateFile()*
   returning a linter command to run.
 
 
+ale#command#Run(buffer, command, callback, [options])       *ale#command#Run()*
+
+  Start running a job in the background, and pass the results to the given
+  callback later.
+
+  This function can be used for computing the results of ALE linter or fixer
+  functions asynchronously with jobs. `buffer` must match the buffer being
+  linted or fixed, `command` must be a |String| for a shell command to
+  execute, `callback` must be defined as a |Funcref| to call later with the
+  results, and an optional |Dictionary| of `options` can be provided.
+
+  The `callback` will receive the arguments `(buffer, output, metadata)`,
+  where the `buffer` will match the buffer given to the function, the `output`
+  will be a `List` of lines of output from the job that was run, and the
+  `metadata` will be a |Dictionary| with additional information about the job
+  that was run, including:
+
+    `exit_code` - A |Number| with the exit code for the program that was run.
+
+  The result of this function is either a special |Dictionary| ALE will use
+  for waiting for the command to finish, or `0` if the job is not started. The
+  The return value of the `callback` will be used as the eventual result for
+  whatever value is being given to ALE. For example: >
+
+    function! s:GetCommand(buffer, output, meta) abort
+        " Do something with a:output here, from the foo command.
+
+        " This is used as the command to run for linting.
+        return 'final command'
+    endfunction
+
+    " ...
+
+    'command': {b -> ale#command#Run(b, 'foo', function('s:GetCommand'))}
+<
+  The result of a callback can also be the result of another call to this
+  function, so that several commands can be arbitrarily chained together. For
+  example: >
+
+    function! s:GetAnotherCommand(buffer, output, meta) abort
+        " We can finally return this command.
+        return 'last command'
+    endfunction
+
+    function! s:GetCommand(buffer, output, meta) abort
+        " We can return another deferred result.
+        return ale#command#Run(
+        \   a:buffer,
+        \   'second command',
+        \   function('s:GetAnotherCommand')
+        \)
+    endfunction
+
+    " ...
+
+    'command': {b -> ale#command#Run(b, 'foo', function('s:GetCommand'))}
+<
+
+  The following `options` can be provided.
+
+    `output_stream` - Either `'stdout'`, `'stderr'`, `'both'`, or `'none`' for
+                    selecting which output streams to read lines from.
+
+                    The default is `'stdout'`
+
+    `executable`    - An executable for formatting into `%e` in the command.
+                    If this option is not provided, formatting commands with
+                    `%e` will not work.
+
+    `read_buffer`   - If set to `1`, the buffer will be piped into the
+                    command.
+
+                    The default is `0`.
+
+    `input`         - When creating temporary files with `%t` or piping text
+                    into a command `input` can be set to a |List| of text to
+                    use instead of the buffer's text.
+
+
 ale#command#EscapeCommandPart(command_part)   *ale#command#EscapeCommandPart()*
 
   Given a |String|, return a |String| with all `%` characters replaced with
@@ -3106,6 +3162,8 @@ ale#linter#Define(filetype, linter)                       *ale#linter#Define()*
                          for computing the executable, accepting a buffer
                          number.
 
+                         The result can be computed with |ale#command#Run()|.
+
                          This value will be used to check if the program
                          requested is installed or not.
 
@@ -3118,50 +3176,12 @@ ale#linter#Define(filetype, linter)                       *ale#linter#Define()*
                          |Funcref| for a function to call for computing the
                          command, accepting a buffer number.
 
+                         The result can be computed with |ale#command#Run()|.
+
                          This command will be fed the lines from the buffer to
                          check, and will produce the lines of output given to
                          the `callback`.
 
-                                                            *ale-command-chain*
-  `command_chain`          A |List| of |Dictionary| items defining a series
-                         of commands to be run. At least one |Dictionary|
-                         should be provided. Each Dictionary must contain the
-                         key `callback`, defining a |String| or |Funcref| for
-                         a function returning a |String| for a command to run.
-
-                         The callback functions for each command after the
-                         first command in in the chain should accept two
-                         arguments `(buffer, output)`, a buffer number and a
-                         |List| of lines of output from the previous command
-                         in the chain.
-
-                         The first callback function in a chain accepts only
-                         a `(buffer)` argument, as there are no previous
-                         commands to run which return `output`.
-
-                         If an empty string is returned for a command in a
-                         chain, that command in the chain will be skipped,
-                         and the next function in the chain will be called
-                         immediately instead. If the last command in a chain
-                         returns an empty string, then no linting will be
-                         performed.
-
-                         Commands in the chain will all use the
-                         `output_stream` value provided in the root
-                         |Dictionary|. Each command in the chain can also
-                         provide an `output_stream` key to override this value.
-                         See the `output_stream` description for more
-                         information.
-
-                         Commands in the chain all behave as if `read_buffer`
-                         is set to `0` by default, except for the last command
-                         in the chain, which uses the value set for
-                         `read_buffer` in the root |Dictionary|. Each command
-                         in the chain can also provide a `read_buffer` key
-                         to override these values.
-                         See the `read_buffer` description for more
-                         information.
-
   `output_stream`          A |String| for the output stream the lines of output
                          should be read from for the command which is run. The
                          accepted values are `'stdout'`, `'stderr'`, and
@@ -3238,6 +3258,8 @@ ale#linter#Define(filetype, linter)                       *ale#linter#Define()*
                          or a |Funcref| accepting a buffer number and
                          returning the |String|.
 
+                         The result can be computed with |ale#command#Run()|.
+
                          This argument must only be set if the `lsp` argument
                          is set to `'socket'`.
 
@@ -3292,12 +3314,10 @@ ale#linter#Define(filetype, linter)                       *ale#linter#Define()*
                          This will be fed (as JSON) to the LSP in the
                          workspace/didChangeConfiguration command.
 
-  Only one of `command` or `command_chain` should be specified.
-
   If temporary files or directories are created for commands run with
-  `command` or `command_chain`, then these temporary files or directories can
-  be managed by ALE, for automatic deletion.  See |ale#command#ManageFile()|
-  and |ale#command#ManageDirectory| for more information.
+  `command`, then these temporary files or directories can be managed by ALE,
+  for automatic deletion. See |ale#command#ManageFile()| and
+  |ale#command#ManageDirectory| for more information.
 
                                                    *ale-command-format-strings*