sh

module
v0.0.0-...-34eb8de Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 14, 2024 License: BSD-3-Clause

README

sh

Go Reference

A shell parser, formatter, and interpreter. Supports POSIX Shell, Bash, and mksh. Requires Go 1.21 or later.

Quick start

To parse shell scripts, inspect them, and print them out, see the syntax examples.

For high-level operations like performing shell expansions on strings, see the shell examples.

shfmt
go install mvdan.cc/sh/v3/cmd/shfmt@latest

shfmt formats shell programs. See canonical.sh for a quick look at its default style. For example:

shfmt -l -w script.sh

For more information, see its manpage, which can be viewed directly as Markdown or rendered with scdoc.

Packages are available on Alpine, Arch, Debian, Docker, Fedora, FreeBSD, Homebrew, MacPorts, NixOS, OpenSUSE, Scoop, Snapcraft, Void and webi.

gosh
go install mvdan.cc/sh/v3/cmd/gosh@latest

Proof of concept shell that uses interp. Note that it's not meant to replace a POSIX shell at the moment, and its options are intentionally minimalistic.

Fuzzing

We use Go's native fuzzing support. For instance:

cd syntax
go test -run=- -fuzz=ParsePrint
Caveats
  • When indexing Bash associative arrays, always use quotes. The static parser will otherwise have to assume that the index is an arithmetic expression.
$ echo '${array[spaced string]}' | shfmt
1:16: not a valid arithmetic operator: string
$ echo '${array[dash-string]}' | shfmt
${array[dash - string]}
  • $(( and (( ambiguity is not supported. Backtracking would complicate the parser and make streaming support via io.Reader impossible. The POSIX spec recommends to space the operands if $( ( is meant.
$ echo '$((foo); (bar))' | shfmt
1:1: reached ) without matching $(( with ))
  • Some builtins like export and let are parsed as keywords. This allows statically building their syntax tree, as opposed to keeping the arguments as a slice of words. It is also required to support declare foo=(bar). Note that this means expansions like declare {a,b}=c are not supported.
JavaScript

A subset of the Go packages are available as an npm package called mvdan-sh. See the _js directory for more information.

Docker

All release tags are published via Docker, such as v3.5.1. The latest stable release is currently published as v3, and the latest development version as latest. The images only include shfmt; -alpine variants exist on Alpine Linux.

To build a Docker image, run:

docker build -t my:tag -f cmd/shfmt/Dockerfile .

To use a Docker image, run:

docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/mnt" -w /mnt my:tag <shfmt arguments>

The following editor integrations wrap shfmt:

Other noteworthy integrations include:

Directories

Path Synopsis
cmd
gosh
gosh is a proof of concept shell built on top of [interp].
gosh is a proof of concept shell built on top of [interp].
shfmt
shfmt formats shell programs.
shfmt formats shell programs.
Package expand contains code to perform various shell expansions.
Package expand contains code to perform various shell expansions.
Package fileutil allows inspecting shell files, such as detecting whether a file may be shell or extracting its shebang.
Package fileutil allows inspecting shell files, such as detecting whether a file may be shell or extracting its shebang.
Package interp implements an interpreter that executes shell programs.
Package interp implements an interpreter that executes shell programs.
Package pattern allows working with shell pattern matching notation, also known as wildcards or globbing.
Package pattern allows working with shell pattern matching notation, also known as wildcards or globbing.
Package shell contains high-level features that use the syntax, expand, and interp packages under the hood.
Package shell contains high-level features that use the syntax, expand, and interp packages under the hood.
Package syntax implements parsing and formatting of shell programs.
Package syntax implements parsing and formatting of shell programs.
typedjson
Package typedjson allows encoding and decoding shell syntax trees as JSON.
Package typedjson allows encoding and decoding shell syntax trees as JSON.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL