Emacs major mode for Puppet using Tree-sitter

This is a major mode for GNU Emacs 29.1 or later which adds support for the Puppet domain-specific language. It uses a Tree-sitter parser for Puppet to be able to parse the code and provide fontification, indentation, navigation and more.

It is a rewrite of the original Puppet mode for Emacs.

Features

The mode provides the following features and enhancements to make writing Puppet manifests easier.

Syntax highlighting

Syntax highlighting for the following elements is fully implemented:

• comments
• strings (including interpolated variables and escape sequences)
• numbers
• variables
• constants (true, false, default, undef)
• keywords (if, unless, case, and, or, in, ...)
• resource types and metaparameters (ensure, require, notify, ...)
• definitions (classes, defined types, type aliases, functions, nodes, plans)
• built-in functions
• custom functions
• operators
• syntax errors

Indentation and alignment

The alignment of resource attributes, function parameter lists and hashes is fully implemented. If point is within such a block, the function puppet-ts-align-block (bound to C-c C-a by default) will align the attributes and parameters with respect to the => symbols.

Example: Consider the following badly written file resource:

file { '/var/www':
  ensure    => directory,
  owner =>     'root',
  group   =>'www-data',
  mode=>'0644',
}

Type C-c C-a when point is somewhere in this resource to neatly align all the attributes and fat arrows. The result will be like this:

file { '/var/www':
  ensure => directory,
  owner  => 'root',
  group  => 'www-data',
  mode   => '0644',
}

Completion

Completion of local variable names is implemented using the completion-at-point function (normally bound to C-M-i). Tree-sitter is used to extract all local variable names from the current manifest. Additional variables like the global $facts variable can be customized in puppet-ts-completion-variables.

Completion of variable names also works for interpolated variables in a string.

Navigation

The keybindings C-M-a and C-M-e jump to preceding or following resource declaration respectively. This seems to be more useful than jumping to the beginning or end of a definition since a Puppet manifest normally only has a single definition.

Imenu

Navigation to the resource types and variable assignments used in a manifest is implemented using Imenu.

Cross-reference navigation

Navigation from a referenced class, defined type, data type or function to the file where this corresponding type is defined (aka xref) is fully implemented.

Example: Let's say you are editing the following acme class:

# a class managing everything
class acme (
  Stdlib::Absolutepath $www_root,
  Boolean              $enable,
) inherits acme::params {

  include nginx

  nginx::resource::server { 'test2.local':
    ensure   => stdlib::ensure($enable),
    www_root => $www_root,
    require  => Class['postgresql::server'],
  }
}

The following navigation options are available:

1. Point is on the Stdlib::Absolutepath data type: M-. opens the data type definition
2. Point is on the acme::params subclass: M-. opens the class definition
3. Point is on the nginx class: M-. opens the class definition
4. Point is on the nginx::resource::server defined type: M-. opens the type definition
5. Point is on the stdlib::ensure function: M-. opens the function definition
6. Point is on the postgresql::server string: M-. opens the class definition

Navigation to foreign classes only needs a list of directories to search (see the customization option puppet-ts-module-path). After jumping to a definition you can return back using M-,. These keybindings are defined by the xref package.

Skeletons for many standard Puppet statements and resource declarations

If you are not using yasnipet or another template package, you can use the implemented skeletons to insert often used types and keywords.

Example: Typing C-c C-t p will insert the following snippet leaving point just before the colon:

package { :
  ensure => present,
}

Skeletons for types

Key	Skeleton
C-c C-t a	type anchor
C-c C-t c	type class
C-c C-t e	type exec
C-c C-t f	type file
C-c C-t g	type group
C-c C-t h	type host
C-c C-t n	type notify
C-c C-t p	type package
C-c C-t s	type service
C-c C-t u	type user

Skeletons for keywords

Key	Skeleton
C-c C-k c	keyword class
C-c C-k d	keyword define
C-c C-k n	keyword node

Installation

Emacs 29.1 or above with Tree-sitter support is required.

Also the appropriate parser for the Puppet language needs to be installed. Note that there are different parsers available and only the referenced parser will work with this code.

The following Elisp code should be used to install the Puppet language parser. This requires some tools -- notably a compiler toolchain -- to be available on your machine.

(require 'puppet-ts-mode)
(puppet-ts-mode-install-grammar)

Using the function provided by the package ensures that a version of the parser matching the package will be installed. These commands should also be used to update the parser to the correct version when the package is updated.

License

Puppet Tree-sitter 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.

Puppet Tree-sitter 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.