nil/docs/features.md

LSP Features

When nil is invoked without arguments, it runs in the LSP mode. Stdin and stdout are used for jsonrpc.

This incomplete list tracks noteble features currently implemented or planned.

• Goto definition. textDocument/definition

  • References to parameters, let and rec {} bindings.
  • Relative paths.
  • Source of flake inputs, when cursor is on keys of inputs or parameters of outputs lambda.

• Find references. textDocument/reference

  • Parameters, let and rec {} bindings.
  • With expression.

• Highlight related. textDocument/documentHighlight.

  • Highlight definitions and references when cursor's on identifiers.
  • Highlight all (attribute) references when cursor's on with.
  • Highlight all effective withs when cursor's on attributes from with.

• Links. textDocument/documentLink

  • Links for relative and absolute paths.
  • Links for search paths like <nixpkgs>.
  • Links for URLs like "https://...", "http://..." and etc.
  • Links for flake references like "github:NixOS/nixpkgs".

• Code actions. textDocument/codeAction See docs/code_actions.md for the list of supported code actions.

• Completion. textDocument/completion

  • Builtin names.
    • With documentations.
  • Local bindings and rec-attrset fields.
  • Keywords.
  • Attrset fields.
    • If it can be inferenced in the local file.
    • Flake schema, including common inputs fields like url and output fields like outPath.
    • Real flake outputs from evaluation.
    • NixOS options. Evaluated from the flake input named nixpkgs.
  • Pat-parameter definition.
    • Flake inputs in the parameter of outputs.

• Diagnostics. textDocument/publishDiagnostics

  • Syntax errors.
  • Hard semantic errors reported as parse errors by Nix, like duplicated keys in attrsets.
  • Undefined names.
  • Warnings of legacy syntax.
  • Warnings of unnecessary syntax.
  • Warnings of unused bindings, with and rec.
  • Warnings of unused parameters for packages, modules and flake output parameters.
  • Client pulled diagnostics.
  • Custom filter on kinds.
  • Exclude files.

  You can disable some diagnostic kinds or for some (generated) files via LSP configuration. See docs/configuration.md for more information.

• Expand selection. textDocument/selectionRange

• Renaming. textDocument/renamme, textDocument/prepareRename

  • Identifiers in parameters and bindings, from let, rec and non-rec attrsets.
  • Static string literal bindings.
  • Merged path-value binding names.
  • Names introduced by inherit.
  • Names used by inherit.
  • Conflict detection.
  • Rename to string literals.

• Semantic highlighting. textDocument/semanticTokens/{range,full}

  • Delta response. textDocument/semanticTokens/full/delta

  ⚠️ There is a known performance issue for semantic highlighting with neovim native LSP. See more details in https://github.com/oxalica/nil/issues/83

  Note: coc.nvim doesn't enable semantic highlighting by default. You need to manually enable it in settings.

  // coc-settings.json
  {
    "semanticTokens": { "filetypes": ["nix"] }
  }
  

• Hover text. textDocument/hover.

  • Show kind of names.
  • Documentation for builtin names.

• File symbols with hierarchy (aka. outline). textDocument/documentSymbol

• File formatting.

  • Whole file formatting.
  • Range formatting.
  • On-type formatting.
  • External formatter.

  External formatter must be manually configured to work. See docs/configuration.md for more information.

  When formatter is configured, you can also enable format-on-save in your editor. Like, for coc.nvim,

  // coc-settings.json
  {
    "coc.preferences.formatOnSaveFiletypes": ["nix"]
  }
  

• Cross-file analysis.

• Multi-threaded.

  • Request cancellation. $/cancelRequest

CLI Features

nil could also be invoked in command line. You can run nil --help for usages of all available commands.

• nil diagnostics <PATH> Check and print diagnostics for a file. Exit with code 1 if there are any errors. ⚠️ WARNING: The output format is for human and should not be relied on.