shell

README

shell

import "github.com/gechr/x/shell"

Package shell provides shell detection, path expansion, argument quoting, and splitting.

Index

• Constants
• func CacheDir() (string, error)
• func CompletionFile(command, sh string) (string, error)
• func ConfigDir() (string, error)
• func ConfigDirs() []string
• func DataDir() (string, error)
• func DataDirs() []string
• func Detect() string
• func DetectFromEnv(env string) string
• func DetectFromProcess() string
• func IsKnown(name string) bool
• func Known() []string
• func Quote(s string) string
• func Split(s string) ([]string, error)
• func StateDir() (string, error)

Constants

Recognized shell names, as returned by Known.

const (
    Ash    = "ash"
    Bash   = "bash"
    Dash   = "dash"
    Elvish = "elvish"
    Fish   = "fish"
    Ksh    = "ksh"
    Nu     = "nu"
    Pwsh   = "pwsh"
    Sh     = "sh"
    Tcsh   = "tcsh"
    Zsh    = "zsh"
)

EnvShell is the environment variable consulted by DetectFromEnv.

const EnvShell = "SHELL"

func CacheDir

func CacheDir() (string, error)

CacheDir returns the user cache directory: $XDG_CACHE_HOME when set to an absolute path, otherwise an OS-specific default.

func CompletionFile

func CompletionFile(command, sh string) (string, error)

CompletionFile returns the standard completion file path for the given command and shell.

func ConfigDir

func ConfigDir() (string, error)

ConfigDir returns the user config directory: $XDG_CONFIG_HOME when set to an absolute path, otherwise an OS-specific default.

func ConfigDirs

func ConfigDirs() []string

ConfigDirs returns the ordered, read-only config search directories: $XDG_CONFIG_DIRS when it has absolute entries, otherwise OS-specific defaults. These are searched after ConfigDir, so a user's config overrides the system defaults.

func DataDir

func DataDir() (string, error)

DataDir returns the user data directory: $XDG_DATA_HOME when set to an absolute path, otherwise an OS-specific default.

func DataDirs

func DataDirs() []string

DataDirs returns the ordered, read-only data search directories: $XDG_DATA_DIRS when it has absolute entries, otherwise OS-specific defaults. These are searched after DataDir, so a user's data overrides the system defaults.

func Detect

func Detect() string

Detect returns the shell to use for completions. Priority: COMPLETE_SHELL env var, parent process name, SHELL env var.

func DetectFromEnv

func DetectFromEnv(env string) string

DetectFromEnv returns the base name of env if it names a recognized shell.

func DetectFromProcess

func DetectFromProcess() string

DetectFromProcess returns the parent process name if it is a known shell, or empty if unavailable or not recognized.

func IsKnown

func IsKnown(name string) bool

IsKnown reports whether name matches a known shell.

Example

fmt.Println(shell.IsKnown("zsh"))
fmt.Println(shell.IsKnown("cmd.exe"))

Output:

true
false

func Known

func Known() []string

Known returns the set of recognized shell names.

Example

fmt.Println(shell.Known())

Output:

[ash bash dash elvish fish ksh nu pwsh sh tcsh zsh]

func Quote

func Quote(s string) string

Quote returns a shell-escaped version of s. The returned value can safely be used as one token in a POSIX shell command line.

Example

fmt.Println(shell.Quote("safe-token_1.txt"))
fmt.Println(shell.Quote("has spaces"))
fmt.Println(shell.Quote("$HOME"))
fmt.Println(shell.Quote(""))

Output:

safe-token_1.txt
'has spaces'
'$HOME'
''

Example (SingleQuotes)

Single quotes inside the input are escaped so the result stays one token.

fmt.Println(shell.Quote("it's fine"))

Output:

'it'"'"'s fine'

func Split

func Split(s string) ([]string, error)

Split partitions s into shell-style words. Whitespace separates words, quotes preserve whitespace, backslashes escape the following rune, a backslash-newline pair is removed as a line continuation, and a "#" starts a comment when it appears where a new word could start. Inside double quotes, a backslash is special only before '$', '`', '"', '\', or a newline; before any other rune it is kept literally, following POSIX.

Example

words, err := shell.Split(`cp "my file.txt" backup/ # keep a copy`)
if err != nil {
    panic(err)
}
fmt.Printf("%q\n", words)

Output:

["cp" "my file.txt" "backup/"]

Example (LineContinuation)

A backslash-newline pair is removed as a line continuation.

words, err := shell.Split("echo one \\\ntwo")
if err != nil {
    panic(err)
}
fmt.Printf("%q\n", words)

Output:

["echo" "one" "two"]

Example (UnclosedQuote)

_, err := shell.Split(`echo "unterminated`)
fmt.Println(err)

Output:

EOF found when expecting closing quote

func StateDir

func StateDir() (string, error)

StateDir returns the user state directory: $XDG_STATE_HOME when set to an absolute path, otherwise an OS-specific default.

Documentation

Overview

Package shell provides shell detection, path expansion, argument quoting, and splitting.

Index

• Constants
• func CacheDir() (string, error)
• func CompletionFile(command, sh string) (string, error)
• func ConfigDir() (string, error)
• func ConfigDirs() []string
• func DataDir() (string, error)
• func DataDirs() []string
• func Detect() string
• func DetectFromEnv(env string) string
• func DetectFromProcess() string
• func IsKnown(name string) bool
• func Known() []string
• func Quote(s string) string
• func Split(s string) ([]string, error)
• func StateDir() (string, error)

Examples

• IsKnown
• Known
• Quote
• Quote (SingleQuotes)
• Split
• Split (LineContinuation)
• Split (UnclosedQuote)

Constants

const (
	Ash    = "ash"
	Bash   = "bash"
	Dash   = "dash"
	Elvish = "elvish"
	Fish   = "fish"
	Ksh    = "ksh"
	Nu     = "nu"
	Pwsh   = "pwsh"
	Sh     = "sh"
	Tcsh   = "tcsh"
	Zsh    = "zsh"
)

Recognized shell names, as returned by Known.

const EnvShell = "SHELL"

EnvShell is the environment variable consulted by DetectFromEnv.

Functions

func CacheDir

func CacheDir() (string, error)

CacheDir returns the user cache directory: `$XDG_CACHE_HOME` when set to an absolute path, otherwise an OS-specific default.

func CompletionFile

func CompletionFile(command, sh string) (string, error)

CompletionFile returns the standard completion file path for the given `command` and shell.

func ConfigDir

func ConfigDir() (string, error)

ConfigDir returns the user config directory: `$XDG_CONFIG_HOME` when set to an absolute path, otherwise an OS-specific default.

func ConfigDirs

func ConfigDirs() []string

ConfigDirs returns the ordered, read-only config search directories: `$XDG_CONFIG_DIRS` when it has absolute entries, otherwise OS-specific defaults. These are searched after ConfigDir, so a user's config overrides the system defaults.

func DataDir

func DataDir() (string, error)

DataDir returns the user data directory: `$XDG_DATA_HOME` when set to an absolute path, otherwise an OS-specific default.

func DataDirs

func DataDirs() []string

DataDirs returns the ordered, read-only data search directories: `$XDG_DATA_DIRS` when it has absolute entries, otherwise OS-specific defaults. These are searched after DataDir, so a user's data overrides the system defaults.

func Detect

func Detect() string

Detect returns the shell to use for completions. Priority: `COMPLETE_SHELL` env var, parent process name, `SHELL` env var.

func DetectFromEnv

func DetectFromEnv(env string) string

DetectFromEnv returns the base name of `env` if it names a recognized shell.

func DetectFromProcess

func DetectFromProcess() string

DetectFromProcess returns the parent process name if it is a known shell, or empty if unavailable or not recognized.

func IsKnown

func IsKnown(name string) bool

IsKnown reports whether `name` matches a known shell.

Example

package main

import (
	"fmt"

	"github.com/gechr/x/shell"
)

func main() {
	fmt.Println(shell.IsKnown("zsh"))
	fmt.Println(shell.IsKnown("cmd.exe"))
}

Output:
true
false

func Known

func Known() []string

Known returns the set of recognized shell names.

Example

package main

import (
	"fmt"

	"github.com/gechr/x/shell"
)

func main() {
	fmt.Println(shell.Known())
}

Output:
[ash bash dash elvish fish ksh nu pwsh sh tcsh zsh]

func Quote

func Quote(s string) string

Quote returns a shell-escaped version of `s`. The returned value can safely be used as one token in a POSIX shell command line.

Example

package main

import (
	"fmt"

	"github.com/gechr/x/shell"
)

func main() {
	fmt.Println(shell.Quote("safe-token_1.txt"))
	fmt.Println(shell.Quote("has spaces"))
	fmt.Println(shell.Quote("$HOME"))
	fmt.Println(shell.Quote(""))
}

Output:
safe-token_1.txt
'has spaces'
'$HOME'
''

Example (SingleQuotes)

Single quotes inside the input are escaped so the result stays one token.

package main

import (
	"fmt"

	"github.com/gechr/x/shell"
)

func main() {
	fmt.Println(shell.Quote("it's fine"))
}

Output:
'it'"'"'s fine'

func Split

func Split(s string) ([]string, error)

Split partitions `s` into shell-style words. Whitespace separates words, quotes preserve whitespace, backslashes escape the following rune, a backslash-newline pair is removed as a line continuation, and a "#" starts a comment when it appears where a new word could start. Inside double quotes, a backslash is special only before '$', '`', '"', '\', or a newline; before any other rune it is kept literally, following POSIX.

Example

package main

import (
	"fmt"

	"github.com/gechr/x/shell"
)

func main() {
	words, err := shell.Split(`cp "my file.txt" backup/ # keep a copy`)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%q\n", words)
}

Output:
["cp" "my file.txt" "backup/"]

Example (LineContinuation)

A backslash-newline pair is removed as a line continuation.

package main

import (
	"fmt"

	"github.com/gechr/x/shell"
)

func main() {
	words, err := shell.Split("echo one \\\ntwo")
	if err != nil {
		panic(err)
	}
	fmt.Printf("%q\n", words)
}

Output:
["echo" "one" "two"]

Example (UnclosedQuote)

package main

import (
	"fmt"

	"github.com/gechr/x/shell"
)

func main() {
	_, err := shell.Split(`echo "unterminated`)
	fmt.Println(err)
}

Output:
EOF found when expecting closing quote

func StateDir

func StateDir() (string, error)

StateDir returns the user state directory: `$XDG_STATE_HOME` when set to an absolute path, otherwise an OS-specific default.