shell

package
v3.8.0 Latest Latest
Warning

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

Go to latest
Published: Feb 11, 2024 License: BSD-3-Clause Imports: 4 Imported by: 25

Documentation

Overview

Package shell contains high-level features that use the syntax, expand, and interp packages under the hood.

Please note that this package uses POSIX Shell syntax. As such, path names on Windows need to use double backslashes or be within single quotes when given to functions like Fields. For example:

shell.Fields("echo /foo/bar")     // on Unix-like
shell.Fields("echo C:\\foo\\bar") // on Windows
shell.Fields("echo 'C:\foo\bar'") // on Windows, with quotes

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Expand

func Expand(s string, env func(string) string) (string, error)

Expand performs shell expansion on s as if it were within double quotes, using env to resolve variables. This includes parameter expansion, arithmetic expansion, and quote removal.

If env is nil, the current environment variables are used. Empty variables are treated as unset; to support variables which are set but empty, use the expand package directly.

Command substitutions like $(echo foo) aren't supported to avoid running arbitrary code. To support those, use an interpreter with the expand package.

An error will be reported if the input string had invalid syntax.

Example
package main

import (
	"fmt"

	"mvdan.cc/sh/v3/shell"
)

func main() {
	env := func(name string) string {
		switch name {
		case "HOME":
			return "/home/user"
		}
		return "" // leave the rest unset
	}
	out, _ := shell.Expand("No place like $HOME", env)
	fmt.Println(out)

	out, _ = shell.Expand("Some vars are ${missing:-awesome}", env)
	fmt.Println(out)

	out, _ = shell.Expand("Math is fun! $((12 * 34))", nil)
	fmt.Println(out)
}
Output:

No place like /home/user
Some vars are awesome
Math is fun! 408

func Fields

func Fields(s string, env func(string) string) ([]string, error)

Fields performs shell expansion on s as if it were a command's arguments, using env to resolve variables. It is similar to Expand, but includes brace expansion, tilde expansion, and globbing.

If env is nil, the current environment variables are used. Empty variables are treated as unset; to support variables which are set but empty, use the expand package directly.

An error will be reported if the input string had invalid syntax.

Example
package main

import (
	"fmt"

	"mvdan.cc/sh/v3/shell"
)

func main() {
	env := func(name string) string {
		switch name {
		case "foo":
			return "bar baz"
		}
		return "" // leave the rest unset
	}
	out, _ := shell.Fields(`"many quoted" ' strings '`, env)
	fmt.Printf("%#v\n", out)

	out, _ = shell.Fields("unquoted $foo", env)
	fmt.Printf("%#v\n", out)

	out, _ = shell.Fields(`quoted "$foo"`, env)
	fmt.Printf("%#v\n", out)
}
Output:

[]string{"many quoted", " strings "}
[]string{"unquoted", "bar", "baz"}
[]string{"quoted", "bar baz"}

Types

This section is empty.

Jump to

Keyboard shortcuts

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