summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorw0rp <devw0rp@gmail.com>2019-03-05 14:07:29 +0000
committerw0rp <devw0rp@gmail.com>2019-03-05 14:07:38 +0000
commitcf883aa5a8b9a8b6403732c4d094be6e65479ddd (patch)
tree1b707168eabebc3b0e0411a4d5b0597035e22d51 /doc
parente5746d9a83a351144b4defb91f65cae7917766b5 (diff)
downloadale-cf883aa5a8b9a8b6403732c4d094be6e65479ddd.zip
#2132 - Document ale#command#Run
Diffstat (limited to 'doc')
-rw-r--r--doc/ale.txt162
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*