Format nushell with Topiary

• Topiary: tree-sitter based uniform formatter
• This repo contains:
  • languages.ncl: configuration that enables nushell
  • nu.scm: tree-sitter query DSL that defines the behavior of the formatter for nushell
  • stand-alone tests written in nushell

Status

• Supposed to work well with all language features of latest nushell (0.103)

Note

• There're corner cases where tree-sitter-nu would fail with parsing errors, if you encounter them, please open an issue there.
• If you encounter any style/format issue, please report in this repo, any feedback is appreciated.

Setup

1. Install topiary-cli using whatever package-manager on your system (0.6.0+ suggested)

# e.g. installing with cargo
cargo install --git https://github.com/tweag/topiary topiary-cli

2. Clone this repo somewhere

# e.g. to `$env.XDG_CONFIG_HOME/topiary`
git clone https://github.com/blindFS/topiary-nushell ($env.XDG_CONFIG_HOME | path join topiary)

3. Setup environment variables (Optional)

Warning

This is required if you want to do the formatting via vanilla topiary-cli, like in the neovim/helix settings below.

While the format.nu script in this repo just wraps that for you.

# Set environment variables according to the path of the clone
$env.TOPIARY_CONFIG_FILE = ($env.XDG_CONFIG_HOME | path join topiary languages.ncl)
$env.TOPIARY_LANGUAGE_DIR = ($env.XDG_CONFIG_HOME | path join topiary languages)

Usage

Using the format.nu wrapper

Helper to run topiary with the correct environment variables for topiary-nushell

Usage:
  > format.nu {flags} ...(files)

Flags:
  -c, --config_dir <path>: Root of the topiary-nushell repo, defaults to the parent directory of this script
  -h, --help: Display the help message for this command

Parameters:
  ...files <path>: Files to format

Input/output types:
  ╭───┬─────────┬─────────╮
  │ # │  input  │ output  │
  ├───┼─────────┼─────────┤
  │ 0 │ nothing │ nothing │
  │ 1 │ string  │ string  │
  ╰───┴─────────┴─────────╯

Examples:
  Read from stdin
  > bat foo.nu | format.nu

  Format files (in-place replacement)
  > format.nu foo.nu bar.nu

  Path overriding
  > format.nu -c /path/to/topiary-nushell foo.nu bar.nu

Using topiary-cli

# in-place formatting
topiary format script.nu
# stdin -> stdout
cat foo.nu | topiary format --language nu

Editor Integration

Neovim

Format on save with conform.nvim:

-- lazy.nvim setup
{
  "stevearc/conform.nvim",
  dependencies = { "mason.nvim" },
  event = "VeryLazy",
  opts = {
    formatters_by_ft = {
      nu = { "topiary_nu" },
    },
    formatters = {
      topiary_nu = {
        command = "topiary",
        args = { "format", "--language", "nu" },
      },
    },
  },
},

Helix

To format on save in Helix, add this configuration to your helix/languages.toml.

[[language]]
name = "nu"
auto-format = true
formatter = { command = "topiary", args = ["format", "--language", "nu"] }

Zed

"languages": {
  "Nu": {
    "formatter": {
      "external": {
        "command": "/path-to-the-clone/format.nu"
      }
    },
    "format_on_save": "on"
  }
}

Contribute

Important

Help to find format issues with following method (dry-run, detects parsing/idempotence/semantic breaking):

source toolkit.nu
test_format <root-path-of-your-nushell-scripts>