Skip to content

Latest commit

 

History

History
145 lines (99 loc) · 5.25 KB

README.md

File metadata and controls

145 lines (99 loc) · 5.25 KB
Raw

Salt-mode

License GPL 3 Build Status MELPA Badge MELPA Stable Badge

Salt-mode is a GNU Emacs major mode for editing SaltStack state files.

Salt is a Python-based configuration management and orchestration system built on top of a high-speed remote execution engine. Configuration management is most commonly managed by writing state files ending with .sls; this mode adds emacs support for these files.

Salt-mode requires a minimum emacs version of 24.4.

This uses mmm-mode and mmm-jinja2 to hook up Jinja2 templates into YAML (essentially what SaltStack files are).

Features

  • Syntax highlighting
  • Indentation and alignment of expressions and statements
  • Jinja Templating Support
  • Spell checking of comments with flyspell
  • Open documentation for state functions
  • Navigation by state function

Installation

From MELPA or MELPA Stable with M-x package-install RET salt-mode.

Usage

Just visit Salt state files. The major mode is enabled automatically for Salt states with the extension .sls.

Flyspell

To enable flyspell for comments when using the mode:

(add-hook 'salt-mode-hook
        (lambda ()
            (flyspell-mode 1)))

State documentation

Use salt-mode-browse-doc to browse the documentation of the state module at point.

When run with a prefix argument, prompt for the state module to use.

If you have Python and the Salt Python modules installed, documentation may be viewed within Emacs via C-c C-d (salt-mode-describe-state) or ElDoc. You don't need a Salt minion running for these to work.

Function jumping

Use salt-mode-forward-state-function and salt-mode-backward-state-function, bound by default to C-M-b and C-M-f, to navigate by salt function.

Font locking

Different font lock keywords are used depending on the value of salt-mode--file-type, a variable which represents the 'type' of the SLS file. This either be 'top for top files or 'salt for everything else.

The value of salt-mode--file-type is detected automatically when a file is opened. You can override this by calling the function salt-mode-set-file-type.

Future types are planned for other keywords, e.g. orchestrate and reactor files.

Troubleshooting

salt-mode-describe-state and ElDoc will only work when your system has Python and the Salt Python modules installed.

If you have the dependencies installed and these features aren't working, try running salt-mode-refresh-data without arguments. You may need to set salt-mode-python-program to python2 or python3 depending on your system's configuration.

The mode should work without error if you don't have these dependencies installed. Visible error messages are a bug (e.g. glynnforrest/salt-mode#18), please report them.

Support

Feel free to ask questions or make suggestions in the issue tracker on github.

This package was originally authored by Ben Hayden; the current maintainer is Glynn Forrest.

Development

test/init.el defines a minimal emacs configuration with the local salt-mode file loaded.

Run make dev to load it in a new emacs.

You can also use the .sls files in test/ to test various mode functions.

Example configuration

With use-package:

(use-package salt-mode
  :ensure t
  :config
  (add-hook 'salt-mode-hook
            (lambda ()
              (flyspell-mode 1))))

Contributors

License

Salt-mode is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Salt-mode is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

See COPYING for the complete license.