Overview

Meziantou.Framework.Language.Shell parses sh, bash, zsh, PowerShell and cmd scripts into a tree that keeps every character, comments, blank lines and line continuations included. Use it to analyze the commands of a script, check a CI step before running it, or rename a command without touching the rest.

It is a parser: it does not run anything, and does not expand variables.

dotnet package add Meziantou.Framework.Language.Shell

Parse a script

ShellSyntaxTree.ParseText takes the script and its dialect. Invalid scripts give diagnostics, not exceptions:

const string Script = """
    # deploy the app
    set -euo pipefail

    for target in web api; do
      if [[ -d "src/$target" ]]; then
        dotnet publish "src/$target" -c Release | tee "logs/$target.log"
      fi
    done
    """;

var tree = ShellSyntaxTree.ParseText(Script, ShellDialect.Bash);

// Nothing is lost: the tree reproduces the input byte for byte.
Assert.Equal(Script, tree.GetRoot().ToFullString());
Assert.Empty(tree.GetDiagnostics());

// Invalid input produces diagnostics instead of exceptions.
var invalid = ShellSyntaxTree.ParseText("echo 'unterminated", ShellDialect.Bash);
var diagnostic = Assert.Single(invalid.GetDiagnostics());
Assert.Equal("SHELL0003 at (0,5)-(0,6): Unterminated single-quoted string.", $"{diagnostic.Id} at {diagnostic.Location}: {diagnostic.Message}");

To read a single command, such as the value of a run: field, use ParseCommand. It returns the statement rather than a tree, and reports content after the first statement:

var command = (ShellCommandSyntax)ShellSyntaxTree.ParseCommand("git commit -m 'wip'", ShellDialect.Bash);

Assert.Equal("git", command.NameValue);
Assert.Equal("wip", command.Arguments[2].Value);

Limit the nesting

ShellParseOptions.MaxRecursionDepth, 128 by default, bounds how deeply the parser goes into nested constructs, so deeply nested input cannot overflow the stack. What nests deeper is reported as SHELL0100 and kept as skipped text:

var script = "echo $(echo $(echo nested))";
var options = new ShellParseOptions(ShellDialect.Bash) { MaxRecursionDepth = 64 };
var tree = ShellSyntaxTree.ParseText(script, options);

Assert.Empty(tree.GetDiagnostics());

The limit bounds nesting, not length. A chain of operators or members, such as $x.a.b.c…, is accepted at any length; building, walking and editing its tree do not recurse either.

Diagnostics

A syntax error is reported, and parsing goes on at the next statement or at the keyword that closes the construct it is in, so one mistake does not hide the rest of the script. The identifiers are shared by every dialect; the message says what was found.