README
¶
shellescape
A drop-in replacement for alessio/shellescape / "gopkg.in/alessio/shellescape.v1".
It's a tiny bit faster and allocates a tiny bit less. It's quite unlikely that anyone will notice any difference in a real-world application, the is here just to reduce dependencies of the rig package.
To use, replace alessio/shellescape with github.com/k0sproject/rig/v2/sh/shellescape in your imports.
In addition to the original package, this package also includes Unquote, Split and Expand (which supports ${var}, $var, $(cmd) and ${var:-word} and some other expansions).
Benchmarks
Just out of curiosity.
Quote
BenchmarkQuote/#00-12 382379658 3.037 ns/op 0 B/op 0 allocs/op
BenchmarkQuote/"double_quoted"-12 14906526 79.10 ns/op 24 B/op 1 allocs/op
BenchmarkQuote/with_spaces-12 16851456 71.15 ns/op 16 B/op 1 allocs/op
BenchmarkQuote/'single_quoted'-12 8453859 154.4 ns/op 72 B/op 2 allocs/op
BenchmarkQuote/;-12 25321892 45.73 ns/op 3 B/op 1 allocs/op
BenchmarkQuote/;${}-12 22446418 54.00 ns/op 8 B/op 1 allocs/op
BenchmarkQuote/foo.example.com-12 39565838 29.85 ns/op 0 B/op 0 allocs/op
BenchmarkQuoteAlessio/#00-12 678336361 1.773 ns/op 0 B/op 0 allocs/op
BenchmarkQuoteAlessio/"double_quoted"-12 10867801 129.4 ns/op 24 B/op 1 allocs/op
BenchmarkQuoteAlessio/with_spaces-12 6283456 187.8 ns/op 16 B/op 1 allocs/op
BenchmarkQuoteAlessio/'single_quoted'-12 6507007 180.3 ns/op 56 B/op 2 allocs/op
BenchmarkQuoteAlessio/;-12 11453983 163.8 ns/op 3 B/op 1 allocs/op
BenchmarkQuoteAlessio/;${}-12 10179727 123.2 ns/op 8 B/op 1 allocs/op
BenchmarkQuoteAlessio/foo.example.com-12 3416793 357.8 ns/op 0 B/op 0 allocs/op
QuoteCommand
BenchmarkQuoteCommand/Basic_Command-12 7548391 159.4 ns/op 88 B/op 2 allocs/op
BenchmarkQuoteCommandAlessio/Basic_Command-12 2256212 572.1 ns/op 96 B/op 3 allocs/op
StripUnsafe
Looks like there isn't much difference between the two.
BenchmarkStripUnsafe/Hello,_World!-12 33246037 34.29 ns/op 0 B/op 0 allocs/op
BenchmarkStripUnsafe/\x00\x01\x02Test\x03\x04\x05-12 16221404 71.40 ns/op 16 B/op 1 allocs/op
BenchmarkStripUnsafe/SpecialChars\x1f\x7f-12 10196348 113.1 ns/op 24 B/op 1 allocs/op
BenchmarkStripUnsafe/中文测试-12 14912823 79.82 ns/op 0 B/op 0 allocs/op
BenchmarkStripUnsafe/#00-12 673622737 1.777 ns/op 0 B/op 0 allocs/op
BenchmarkStripUnsafeAlessio/Hello,_World!-12 24444872 48.44 ns/op 0 B/op 0 allocs/op
BenchmarkStripUnsafeAlessio/\x00\x01\x02Test\x03\x04\x05-12 17340309 68.57 ns/op 16 B/op 1 allocs/op
BenchmarkStripUnsafeAlessio/SpecialChars\x1f\x7f-12 13657556 80.99 ns/op 24 B/op 1 allocs/op
BenchmarkStripUnsafeAlessio/中文测试-12 13895878 85.13 ns/op 0 B/op 0 allocs/op
BenchmarkStripUnsafeAlessio/#00-12 473620983 2.509 ns/op 0 B/op 0 allocs/op
Documentation
¶
Overview ¶
Package shellescape provides functions to escape strings for use in posix shell commands.
It is a drop-in replacement for gopkg.in/alessio/shellescape.v1.
Additionally an Unquote function is provided.
Index ¶
- Variables
- func Expand(input string, opts ...ExpandOption) (string, error)
- func Join(args ...string) string
- func Quote(str string) string
- func QuoteCommand(args []string) string
- func QuoteForLoginShell(str string) string
- func Split(input string) ([]string, error)
- func StripUnsafe(s string) string
- func Unquote(input string) (string, error)
- type ExpandOption
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrMismatchedQuotes is returned when the input string has mismatched quotes when unquoting. ErrMismatchedQuotes = errors.New("mismatched quotes") // ErrTrailingBackslash is returned when the input string ends with a trailing backslash. ErrTrailingBackslash = errors.New("trailing backslash") )
Functions ¶
func Expand ¶
func Expand(input string, opts ...ExpandOption) (string, error)
Expand expands the input string according to the rules of a posix shell. It supports parameter expansion, command substitution and simple $envvar expansion. It does not support arithmetic expansion, tilde expansion, or any of the other expansions and it doesn't support backticks.
func Quote ¶
Quote safely encloses a string in single quotes for shell usage.
Example ¶
This example demonstrates how to use shellescape.Quote to escape a string for use as an argument to a shell command.
package main
import (
"fmt"
"github.com/k0sproject/rig/v2/sh/shellescape"
)
func main() {
quoted := shellescape.Quote("value with spaces")
fmt.Println(quoted)
}
Output: 'value with spaces'
func QuoteCommand ¶
QuoteCommand safely quotes and joins a list of strings for use as a shell command.
Example ¶
This example demonstrates how to use shellescape.QuoteCommand to escape a command and its arguments for use in a shell command.
package main
import (
"fmt"
"github.com/k0sproject/rig/v2/sh/shellescape"
)
func main() {
quoted := shellescape.QuoteCommand([]string{"ls", "-l", "file with space"})
fmt.Println(quoted)
}
Output: ls -l 'file with space'
func QuoteForLoginShell ¶ added in v2.2.0
QuoteForLoginShell safely encloses a string in single quotes for a shell that the program did not choose: in practice the remote user's login shell, which sshd hands the command line to before anything else sees it.
Use it for that boundary and nothing else. Quote is correct, shorter and easier to read for every layer inside it, because those are parsed by the POSIX shell that rig imposes on the command (see cmd.Executor.SetShell) rather than by whatever the remote user's shell happens to be.
The difference is backslashes. fish reads \\ and \' as escapes inside single quotes, where POSIX shells pass them through verbatim, so a POSIX-quoted 'a\\b' reaches the imposed shell as a\b. Wrapping a command in a shell invocation is therefore not by itself enough to protect it: the darwin OS release detection sends a sed expression carrying consecutive backslashes, and under a fish login shell that expression silently changed meaning. This function escapes single quotes and backslashes outside the quoted runs instead, where both shells agree that \\ means one backslash.
The csh family is not covered: it expands ! before it considers quoting, and takes no embedded newline inside quotes at all. Both fail loudly rather than changing the command.
func StripUnsafe ¶
StripUnsafe removes non-printable runes from a string.
Types ¶
type ExpandOption ¶
type ExpandOption func(*expandOptions)
ExpandOption is a functional option for Expand.
func ExpandErrorIfUnset ¶
func ExpandErrorIfUnset() ExpandOption
ExpandErrorIfUnset causes Expand to return an error if a variable is not set. By default, unset variables are replaced with an empty string. This only applies when ExpandParam is not set.
func ExpandExec ¶
func ExpandExec() ExpandOption
ExpandExec enables command substitution, as in $(command).
func ExpandNoDollarVars ¶
func ExpandNoDollarVars() ExpandOption
ExpandNoDollarVars disables $var expansion.
func ExpandParam ¶
func ExpandParam() ExpandOption
ExpandParam enables parameter expansion, as in ${parameter:...} and some other patterns. If this is not set, only simple ${VAR} expansion is performed.
Source Files