README
¶
shellescape
Escape arbitrary strings for safe use as command line arguments.
Contents of the package
This package provides the shellescape.Quote() function that returns a
shell-escaped copy of a string. This functionality could be helpful
in those cases where it is known that the output of a Go program will
be appended to/used in the context of shell programs' command line arguments.
This work was inspired by the Python original package shellescape.
Usage
The following snippet shows a typical unsafe idiom:
package main
import (
"fmt"
"os"
)
func main() {
fmt.Printf("ls -l %s\n", os.Args[1])
}
Especially when creating pipeline of commands which might end up being executed by a shell interpreter, it is particularly unsafe to not escape arguments.
shellescape.Quote() comes in handy and to safely escape strings:
package main
import (
"fmt"
"os"
"gopkg.in/alessio/shellescape.v1"
)
func main() {
fmt.Printf("ls -l %s\n", shellescape.Quote(os.Args[1]))
}
The escargs utility
escargs reads lines from the standard input and prints shell-escaped versions. Unlinke xargs, blank lines on the standard input are not discarded.
Documentation
¶
Overview ¶
Package shellescape provides the shellescape.Quote to escape arbitrary strings for a safe use as command line arguments in the most common POSIX shells.
The original Python package which this work was inspired by can be found at https://pypi.python.org/pypi/shellescape.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Quote ¶
Quote returns a shell-escaped version of the string s. The returned value is a string that can safely be used as one token in a shell command line.
Example ¶
package main
import (
"fmt"
"strings"
"github.com/alessio/shellescape"
)
func main() {
filename := "myfile; rm -rf /"
prog := "/bin/ls -lh"
unsafe := strings.Join([]string{prog, filename}, " ")
safe := strings.Join([]string{prog, shellescape.Quote(filename)}, " ")
fmt.Println("unsafe:", unsafe)
fmt.Println("safe:", safe)
for i, part := range strings.Split(unsafe, " ") {
fmt.Printf("unsafe[%d] = %s\n", i, part)
}
for i, part := range strings.Split(safe, " ") {
fmt.Printf("safe[%d] = %s\n", i, part)
}
}
Output: unsafe: /bin/ls -lh myfile; rm -rf / safe: /bin/ls -lh 'myfile; rm -rf /' unsafe[0] = /bin/ls unsafe[1] = -lh unsafe[2] = myfile; unsafe[3] = rm unsafe[4] = -rf unsafe[5] = / safe[0] = /bin/ls safe[1] = -lh safe[2] = 'myfile; safe[3] = rm safe[4] = -rf safe[5] = /'
func QuoteCommand ¶ added in v1.3.0
QuoteCommand returns a shell-escaped version of the slice of strings. The returned value is a string that can safely be used as shell command arguments.
Example ¶
package main
import (
"fmt"
"strings"
"github.com/alessio/shellescape"
)
func main() {
filename := "filename with space"
prog := "/usr/bin/ls"
args := "-lh"
unsafe := strings.Join([]string{prog, args, filename}, " ")
safe := strings.Join([]string{prog, shellescape.QuoteCommand([]string{args, filename})}, " ")
fmt.Println("unsafe:", unsafe)
fmt.Println("safe:", safe)
}
Output: unsafe: /usr/bin/ls -lh filename with space safe: /usr/bin/ls -lh 'filename with space'
func StripUnsafe ¶ added in v1.4.0
StripUnsafe remove non-printable runes, e.g. control characters in a string that is meant for consumption by terminals that support control characters.
Example ¶
package main
import (
"fmt"
"github.com/alessio/shellescape"
)
func main() {
safeString := `"printable!" #$%^characters '' 12321312"`
unsafeString := "these runes shall be removed: \u0000\u0081\u001f"
fmt.Println("safe:", shellescape.StripUnsafe(safeString))
fmt.Println("unsafe:", shellescape.StripUnsafe(unsafeString))
}
Output: safe: "printable!" #$%^characters '' 12321312" unsafe: these runes shall be removed:
Types ¶
This section is empty.
Source Files
Directories