shell-escape-tag
v2.0.2
Published
An ES6 template tag which escapes parameters for interpolation into shell commands
Downloads
1,784
Maintainers
Readme
shell-escape-tag
An ES6 template tag which escapes parameters for interpolation into shell commands
- INSTALL
- SYNOPSIS
- DESCRIPTION
- EXPORTS
- FUNCTIONS
- DEVELOPMENT
- COMPATIBILITY
- SEE ALSO
- VERSION
- AUTHOR
- COPYRIGHT AND LICENSE
INSTALL
$ npm install shell-escape-tag
SYNOPSIS
import shell from 'shell-escape-tag'
let filenames = glob('Holiday Snaps/*.jpg')
let title = 'Holiday Snaps'
let command = shell`compress --title ${title} ${filenames}`
console.log(command) // compress --title 'Holiday Snaps' 'Holiday Snaps/Pic 1.jpg' 'Holiday Snaps/Pic 2.jpg'
DESCRIPTION
This module exports an ES6 tagged-template function which escapes (i.e. quotes) its parameters for safe inclusion in shell commands. Parameters can be strings, arrays of strings, or nested arrays of strings, arrays and already-processed parameters.
The exported function also provides two helper functions which respectively escape and preserve their parameters and protect them from further processing.
EXPORTS
shell (default)
Signature: (template: string) ⇒ string
import shell from 'shell-escape-tag'
let filenames = ['foo bar', "baz's quux"]
let title = 'My Title'
let command = shell`command --title ${title} ${filenames}`
console.log(command) // command --title 'My Title' 'foo bar' 'baz'"'"'s quux'
Takes a template literal
and escapes any interpolated parameters. null
and undefined
values are
ignored. Arrays are flattened and their elements are escaped and joined with a
space. All other values are stringified i.e. false
is mapped to "false"
etc. Parameters that have been escaped with shell.escape
or
preserved with shell.preserve
are passed through verbatim.
FUNCTIONS
shell.escape
Signature: (...args: any[]) ⇒ object
import shell from 'shell-escape-tag'
let escaped = shell.escape("foo's bar")
let command1 = `command ${escaped}`
let command2 = shell`command ${escaped}`
console.log(command1) // command 'foo'"'"'s bar'
console.log(command2) // command 'foo'"'"'s bar'
Flattens, compacts and escapes any parameters which haven't already been
escaped or preserved, joins the resulting elements with a space, and wraps the
resulting string in an object which remains escaped when embedded in a template
or passed as a direct or nested parameter to shell
,
shell.escape
, or shell.preserve
.
shell.preserve
Aliases: protect, verbatim
Signature: (...args: any[]) → object
import shell from 'shell-escape-tag'
let preserved = shell.preserve("baz's quux")
let command1 = `command "${preserved}"`
let command2 = shell`command "${preserved}"`
console.log(command1) // command "baz's quux"
console.log(command2) // command "baz's quux"
Flattens, compacts and preserves any parameters which haven't already been
escaped or preserved, joins the resulting elements with a space, and wraps the
resulting string in an object which is passed through verbatim when embedded in
a template or passed as a direct or nested parameter to
shell
, shell.escape
, or
shell.preserve
.
DEVELOPMENT
NPM Scripts
The following NPM scripts are available:
- build - compile the code and save it to the
dist
directory - clean - remove the
dist
directory and other build artifacts - rebuild - clean the build artifacts and recompile the code
- test - clean and rebuild and run the test suite
- test:run - run the test suite
COMPATIBILITY
- Maintained Node.js versions (and compatible browsers)
SEE ALSO
- any-shell-escape - Escape and stringify an array of arguments to be executed on the shell
- execa - A better
child_process
- @perl/qw - A template tag for quoted word literals like Perl's
qw(...)
- @perl/qx - A template tag to run a command and capture its output like Perl's
qx(...)
VERSION
2.0.2
AUTHOR
COPYRIGHT AND LICENSE
Copyright © 2015-2019 by chocolateboy.
This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.