powershell-ts-mode

[[https://github.com/dmille56/powershell-ts-mode/actions/workflows/main.yml/badge.svg]]

• About
  :PROPERTIES:
  :CUSTOM_ID: about
  :END:
  Powershell-ts-mode is an Emacs mode for editing Powershell files using Treesitter.

[[https://i.imgur.com/LHOyls2.png]]

• Table of Contents
  :PROPERTIES:
  :TOC: :include all :ignore (this)
  :CUSTOM_ID: table-of-contents
  :END:
  :CONTENTS:

• [[#about][About]]
• [[#installation][Installation]]
  • [[#dependencies][Dependencies]]
  • [[#config][Config]]
  • [[#grammar-installation-instructions][Grammar installation instructions]]
• [[#why][Why]]
• [[#development-cycle][Development cycle]]
  :END:

• Installation
  :PROPERTIES:
  :CUSTOM_ID: installation
  :END:
  ** Dependencies
  :PROPERTIES:
  :CUSTOM_ID: dependencies
  :END:

1. Emacs compiled with treesit support (version 29+)
2. Installed powershell treesitter grammar

** Config :PROPERTIES: :CUSTOM_ID: config :END: #+BEGIN_SRC emacs-lisp (use-package powershell-ts-mode :straight (:host github :repo "dmille56/powershell-ts-mode") :config ;; Optional: if you want to disable top-level vars from being shown in imenu (setq powershell-ts-enable-imenu-top-level-vars nil)) #+END_SRC

For other customizable variables see: powershell-ts-mode customize group

** Grammar installation instructions :PROPERTIES: :CUSTOM_ID: grammar-installation-instructions :END: Requires: Emacs 29+, git, C compiler, C++ compiler

1. M-x treesit-install-language-grammar
2. Enter in powershell as your language
3. Enter yes to build recipe for powershell interactively
4. Enter in the url of the grammar: https://github.com/airbus-cert/tree-sitter-powershell (NOTE: tested with commit: 9d95502e730fb403bdf56279d84630c8178b10be)
5. Stick to the defaults for git branch, "src" directory, C compiler, and C++ compilers

NOTE: for Windows I had to install GCC in order to compile the grammar.

The pre-built binaries (including tree-sitter-powershell) can be found here https://github.com/kiennq/treesit-langs/releases

• Why :PROPERTIES: :CUSTOM_ID: why :END: Powershell-mode has some bugs when dealing with strings (ex: "\home\user") and multi-line comments (ex: "<#/n###>") that made it unusable for me. By using treesitter we're able to get more accurate parsing and syntax highlighting rather then relying on regular expressions to do this which reduces errors.

• Development cycle :PROPERTIES: :CUSTOM_ID: development-cycle :END:

1. Spot missing syntax highlighting/indent rule
2. View AST with treesit-explore-mode
3. Locate the part that isn't working
4. Add new pattern
5. Reload code in powershell-ts-mode.el
6. =M-x revert-buffer= in your file.ps1

NOTE: there are test PowerShell files under ./test-ps-scripts/*.ps1 that can be used to ensure that the new highlighting and indent rules do not break the current expected format.