HELPERS.md

Helpers

null-ls provides helpers to streamline the process of transforming command line output into LSP diagnostics, code actions, or formatting.

The plugin exports available helpers under null_ls.helpers:

local helpers = require("null-ls.helpers")

Please see the built-in files for examples of how to use helpers to create generators.

generator_factory

generator_factory is a general-purpose helper that returns a generator which will spawns a command with the given options, optionally transforms its output, then calls an on_output callback with the command's output. It accepts one argument, opts, which is a table with the following structure.

All options are required unless specified otherwise.

local helpers = require("null-ls.helpers")

helpers.generator_factory({
    command, -- string or function
    args, -- table (optional)
    on_output, -- function
    format, -- "raw", "line", "json", or "json_raw" (optional)
    ignore_stderr, -- boolean (optional)
    from_stderr, -- boolean (optional)
    to_stdin, -- boolean (optional)
    suppress_errors, -- boolean (optional)
    check_exit_code, -- function or table of numbers (optional)
    timeout, -- number (optional)
    to_temp_file, -- boolean (optional)
    use_cache, -- boolean (optional)
    runtime_condition, -- function (optional)
    cwd, -- function (optional)
})

null-ls validates each option using vim.validate when the generator runs for the first time.

command

A string containing the command that the generator will spawn or a function that takes one argument, params (an object containing information about the current editor status) and returns a command string.

If command is a function, it will run once when the generator first runs and keep the same return value as long as the same Neovim instance is running, making it suitable for resolving executables based on the current project.

args

A table containing the arguments passed when spawning the command. Defaults to {}.

null-ls will transform the following special arguments before spawning:

• $FILENAME: replaced with the current buffer's full path

• $TEXT: replaced with the current buffer's content

• $FILEEXT: replaced with the current buffer's file extension (e.g. my-file.lua produces "lua")

• $ROOT: replaced with the LSP workspace root path

on_output

A callback function that receives a params object, which contains information about the current buffer and editor state (see Generators in MAIN for details).

Generators created by generator_factory have access to an extra parameter, params.output, which contains the output from the spawned command. The structure of params.output depends on format, described below.

format

Specifies the format used to transform output before passing it to on_output. Supports the following options:

• "raw": passes command output directly as params.output (string) and error output as params.err (string).

  This format will call on_output(params, done), where done() is a callback that on_output must call with its results (see Generators in MAIN for details).

• nil: same as raw, but does not receive error output. Instead, error output will cause the generator to throw an error, unless suppress_errors is also enabled (see below).

• "line": splits generator output into lines and calls on_output(line, params) once for each line, where line is a string.

  on_output should return nil or an object that matches the structure expected for its method, not a list of results (see Generators in MAIN for details). The wrapper will automatically call done when once it's done iterating over output lines.

• "json": decodes generator output into JSON, sets params.output to the resulting JSON object, and calls on_output(params). The wrapper will automatically call done once on_output returns.

• "json_raw": same as json, but will not throw on errors, either from stderr or from json_decode. Instead, it'll pass errors to on_output via params.err.

ignore_stderr

Usually when a command outputs anything on stderr it would cause the command to fail (unless from_stderr is set to true, see below).

This option tells the runner that the command's stderr output is irrelevant and should be discarded. This is similar to running a command with a 2>/dev/null redirect, but the error output will still be logged in debug mode before being rejected.

Note that setting ignore_stderr = true will make from_stderr not do anything.

from_stderr

Captures a command's stderr output and assigns it to params.output. Useful for linters that output to stderr.

Note that setting from_stderr = true will discard stdin output. Will not work with ignore_stderr set.

to_stdin

Sends the current buffer's content to the spawned command via stdin.

suppress_errors

Suppresses errors, regardless of stderr output or the command's exit code.

Note that most formats won't call on_output if there is an error. To handle errors manually or ignore them entirely, use format = "raw".

check_exit_code

Can either be a table of valid exit codes (numbers) or a callback that receives one argument, code, which containing the exit code from the spawned command as a number. The callback should return a boolean value indicating whether the code indicates success.

If not specified, null-ls will assume that a non-zero exit code indicates failure.

timeout

The amount of time, in milliseconds, until null-ls aborts the command and returns an empty response. If not set, will default to the user's default_timeout setting.

to_temp_file

Writes the current buffer's content to a temporary file and replaces the special argument $FILENAME with the path to the temporary file. Useful for formatters and linters that don't accept input via stdin.

Setting to_temp_file = true will also assign the path to the temp file to params.temp_path.

from_temp_file

Reads the contents of the temp file created by to_temp_file after running command and assigns it to params.content. Useful for formatters that don't output to stdin (see formatter_factory).

This option depends on to_temp_file.

use_cache

Caches command output on run. When available, the generator will use cached output instead of spawning the command, which can increase performance for slow commands.

The plugin resets cached output when Neovim's LSP client notifies it of a buffer change, meaning that cache validity depends on a user's debounce setting. Sources that rely on up-to-date buffer content should avoid using this option.

Note that this option effectively does nothing for diagnostics, since the handler will always invalidate the buffer's cache before running generators.

runtime_condition

Optional function that will be called when generating a list of sources to run for a given method. The calculations here must be conscious that this is called every time a source is potentially run, and hence should avoid doing anything overly expensive.

• Takes a single argument, params, which is a table of parameters containing the following useful keys, amongst a few others (one can print(vim.inspect(params)) inside of the function to see more):
  • bufnr: The buffer number being formatted
  • bufname: The name of the above buffer number
  • client_id: The ID of the attached client
  • content: The contents of the buffer, potentially updated from formatters that have been run prior
  • ft: The filetype of the aforementioned buffer
• If the function returns nil or false, the associated source will be skipped, otherwise it will be added to the set of valid sources to run upon meeting other neccessary conditions (filetype, etc.) as well.
• Defaults to true, hence any configured source will be run every time unless this condition specifies otherwise.

cwd

Optional function to set the working directory for the process being spawned.

• Takes a single argument, params, which has the root key added of the project root
• With no function or no return, the working directory remains set to the project root

formatter_factory

formatter_factory is a wrapper around generator_factory meant to streamline the process of capturing a formatter's output and replacing a buffer's entire content with that output. It supports the same options as generator_factory with the following changes:

• suppress_errors: set to true unless specifically set to false.

• from_temp_file: always set to true if to_temp_file is true (since formatting from a temp file won't work otherwise).

• on_output: will always return an edit that will replace the current buffer's content with formatter output. As a result, other options that depend on on_output, such as format, will not have an effect.

make_builtin

make_builtin creates built-in sources, as described in BUILTINS. It optimizes the source to reduce start-up time and allow the built-in library to continue expanding without affecting users.

make_builtin is specifically intended for built-ins included in this plugin. Generally, integrations should opt to create sources with one of the factory methods described above, since they are opt-in by nature.

The method accepts a single argument, opts, which contains the following options. All options are required unless specified otherwise.

local helpers = require("null-ls.helpers")

helpers.make_builtin({
    method, -- internal null-ls method (string)
    filetypes, -- table
    generator_opts, -- table
    factory, -- function (optional)
    generator, -- function (optional, but required if factory is not set)
})

method

Defines the source's null-ls method, as described in MAIN.

filetypes

A list of filetypes for the source, as described in MAIN. A built-in can opt to leave this as nil, meaning that the user will have to define filetypes in with().

generator_opts

A table of arguments passed into factory when the user registers the source, which should conform to the opts object described above in generator_factory.

factory

A function called when the user registers the source. Intended for use with the helper factory functions described above, but any function that returns a valid generator will work.

generator

A simple generator function. Either factory or generator must be a valid function, and setting factory will override generator.

range_formatting_args_factory

Converts the visually-selected range into character offsets and adds the converted range to the spawn arguments. Used for sources that provide both formatting and range formatting.

null_ls.helpers.range_formatting_args_factory(base_args, start_arg, end_rag)

• base_args: the base arguments required to get formatted output. Formatting requests will use base_args as-is, and range formatting requests will append the range arguments.

• start_arg (optional): the name of the argument that indicates the start of the range. Defaults to "--range-start".

• end_arg (optional): the name of the argument that indicates the end of the range. Defaults to "--range-end".

conditional

Used to conditionally register sources. See HELPERS for more information.

diagnostics

Helpers used to convert CLI output into diagnostics. See the source for details and the built-in diagnostics sources for examples.