ansible-language-server v0.1.1-0
Ansible Language Server
This language server adds support for Ansible.
Getting started
Install prerequisites:
- latest Visual Studio Code
- Node.js v12.0.0 or higher
Fork and clone this repository
Install the dependencies
cd ansible-language-server $ yarn install
Build the language server
$ yarn run build
The new built server is now located in ./out/server/src/server.js.
node <Ansible Language Server Location>/out/server/src/server.js --stdio
Features
Syntax highlighting
Ansible keywords, module names and module options, as well as
standard YAML elements are recognized and highlighted distinctly. Jinja
expressions are supported too, also those in Ansible conditionals (when
,
failed_when
, changed_when
, check_mode
), which are not placed in double
curly braces.
The screenshots and animations presented in this README have been taken using the One Dark Pro theme. The default VS Code theme will not show the syntax elements as distinctly, unless customized. Virtually any theme other than default will do better.
Validation
While you type, the syntax of your Ansible scripts is verified and any feedback is provided instantaneously.
Integration with ansible-lint
On opening and saving a document, ansible-lint
is executed in the background
and any findings are presented as errors. You might find it useful that
rules/tags added to warn_list
(see Ansible Lint Documentation)
are shown as warnings instead.
Smart autocompletion
The extension tries to detect whether the cursor is on a play, block or task etc. and provides suggestions accordingly. There are also a few other rules that improve user experience:
- the
name
property is always suggested first - on module options, the required properties are shown first, and aliases are shown last, otherwise ordering from the documentation is preserved
- FQCNs (fully qualified collection names) are inserted only when necessary;
collections configured with the
collections
keyword are honored. This behavior can be disabled in extension settings.
Auto-closing Jinja expressions
When writing a Jinja expression, you only need to type "{{
, and it will be
mirrored behind the cursor (including the space). You can also select the whole
expression and press space
to put spaces on both sides of the expression.
Documentation reference
Documentation is available on hover for Ansible keywords, modules and module
options. The extension works on the same principle as ansible-doc
, providing
the documentation straight from the Python implementation of the modules.
Jump to module code
You may also open the implementation of any module using the standard Go to
Definition operation, for instance, by clicking on the module name while
holding ctrl
/cmd
.
Requirements
- Ansible 2.9+
- Ansible Lint (required,
unless you disable linter support; install without
yamllint
)
For Windows users, this extension works perfectly well with extensions such as
Remote - WSL
and Remote - Containers
.
If you have any other extension providing language support for Ansible, you might need to uninstall it first.
Configuration
This extension supports multi-root workspaces, and as such, can be configured on any level (User, Remote, Workspace and/or Folder).
ansible.ansible.path
: Path to theansible
executable.ansible.ansible.useFullyQualifiedCollectionNames
: Toggles use of fully qualified collection names (FQCN) when inserting a module name. Disabling it will only use FQCNs when necessary, that is when the collection isn't configured for the task.ansible.ansibleLint.enabled
: Enables/disables use ofansible-lint
.ansible.ansibleLint.path
: Path to theansible-lint
executable.ansible.ansibleLint.arguments
: Optional command line arguments to be appended toansible-lint
invocation. Seeansible-lint
documentation.ansible.python.interpreterPath
: Path to thepython
/python3
executable. This setting may be used to make the extension work withansible
andansible-lint
installations in a Python virtual environment.ansible.python.activationScript
: Path to a customactivate
script, which will be used instead of the setting above to run in a Python virtual environment.
Known limitations
- The shorthand syntax for module options (key=value pairs) is not supported.
- Nested module options are not supported yet.
- Only Jinja expressions inside Ansible YAML files are supported. In order to have syntax highlighting of Jinja template files, you'll need to install other extension.
- Jinja blocks (inside Ansible YAML files) are not supported yet.
Credit
Based on the good work done by Tomasz Maciążek