# snang
version: 0.2.7
tacit JS ⨉ CLI
Manipulate things in the command-line with tacit JS in a sandbox
## Globals
-
The literal "x" refers to the current e.g. echo "snang" | snang buffer contents "x.toUpperCase() + '!'"
-
Both "ramda and "entrust" have been e.g. echo "snang" | snang "tail(x)" injected into the sandbox, so any methodecho "snang" | snang "e1('split')('',x)" of theirs will work.
-
"fluture" has also been injected into e.g. echo "snang" | snang "keys(F)" -o the sandbox, but it is aliased to the literal "F".
-
The literal "exec" allows you to run e.g. echo "package.json" | snang child_process.execSync on the given "exec('cat ' + x)" string. This effectively allows you to construct meta commands.
## Flags
--debug, -d Pass integers in to get specific debug information
--help, -h See this help text
--color, -C Display output with color. Use --no-color to turn color off.
--shell, -P Specify pipe commands with "|" delimiters, like in *nix
--pipe, -p Wrap passed expression in pipe
--compose, -c Wrap passed expression in compose
--json, -i Read JSON values in
--jsonOut, -o Pass JSON values out
--prettyPrint, -L Print the commands you've passed into snang, but pretty
--print, -l Print the commands you've passed into snang
--exportFile, -x Print the commands you've passed into snang, but as a file
--exportES6, -X Print the commands you've passed into snang, but as an ES6 file
--readStdinOnExport, -t Used in concert with -X / -x, this makes the resulting file deal with stdin as an input
--readFileOnExport, -u Used in concert with -X / -x, this makes the resulting file deal with a file as an input
--readDirOnExport, -v Used in concert with -X / -x, this makes the resulting file deal with a directory as an input
--read, -r Read from a file. If this is not passed, snang reads from stdin.
--write, -w Write from a file. If this is not passed, snang writes to stdout.
--require, -q Add a commonjs file to be used within snang's vm.
--import, -Q Add an ES6 style file to be used within snang's vm. Impacts performance, as this transpiles sources on the fly.
--future, -f If the resulting output of the expression is a Future, fork it to (stderr, stdout).
--trim, -m Trim the trailing \n of the input. Default: false
--source, -s Add a source file which takes the form --source ref:path/to/file.js. Adds a source object to the VM which has sources as Futures.
--config, -k Pass a config file to snang. Uses cosmiconfig, so any of the following is valid: '.snangrc' '.snangrc.json' '.snangrc.js' '.snangrc.yaml' '.snangrc.config.js' or a "snang" property in package.json.
--commands, -z Ignore all inputs and list all valid commands.
## Examples
-
read name from package.json
snang --read package.json --json snang --read package.json --json --pipe "x.name" "prop('name')"
cat package.json | snang -i "x.name" cat package.json | snang -ip "prop('name')"
-
list devDependencies in package.json which have eslint in the key, return as string
snang --read package.json --json --shell "prop('devDependencies') | keys | filter(matches('eslint')) | join(' ')"
cat package.json | snang -iP "prop('devDependencies') | keys | filter(matches('eslint')) | join(' ')"
- read package.json, filter devDependencies and then pass to yarn and execute
cat package.json | snang --json "exec( 'yarn add ' + Object.keys(x.devDependencies).filter(z => z.includes('eslint')).join(' ') + ' -D' )"
cat package.json | snang -iP "prop('devDependencies') | keys | filter(includes('eslint')) | join(' ') | z => 'yarn add ' + z + ' -D') | exec"
cat package.json | snang -iP "prop('devDependencies') | keys | filter(includes('eslint')) | join(' ')" | xargs yarn add -D
- read package.json, require local node-module (with optional alias)
snang --read package.json --json --require camel-case -P "prop('devDependencies') | keys | map(camelCase)" -o
snang --read package.json --json --require kool:camel-case -P "prop('devDependencies') | keys | map(kool))" -o
- read package.json, import es6 module (with optional alias)
snang --read package.json --json --import ./require-test-simple.mjs -P "prop('devDependencies') | keys | map(requireTestSimple)" -o
snang --read package.json --json --import kool:./require-test-simple.mjs-P "prop('devDependencies') | keys | map(kool))" -o
API
Table of Contents
- colorize
- yargsParserOptions
- errors
- handleErrors
- onError
- getExpression
- createComposedExpression
- runInContext
- runner
- makeSandboxWithRequireHook
- makeSandbox
- createStreamFromSource
- toString
- concatConditionally
- tackOn
colorize
colorize a string conditionally
Parameters
Returns string
yargsParserOptions
Options hash to be passed to yargs-parser.
Type: Object
Properties
errors
Errors object, used both for filtering and constant definition.
Type: Object
Properties
-
chunkArgument
string A chunk argument error. -
useObjectFlag
string A replacement error for the chunk argument error.
handleErrors
Pure error handler which attempts to address known common errors.
Parameters
-
warn
Function Function to receive errors.
Examples
handleErrors(console.warn)
Returns Function onError handler.
onError
The inner error handler.
Parameters
-
e
Error Error.
getExpression
Convert a list of expressions into a string to be evaluated in a virtual machine context.
Parameters
-
config
Object Config from yargs-parser. -
expressions
Array<string> Input expressions. -
sandbox
Object Sandbox object for evaluating the eventual expression against.
Returns string The expression to evaluate.
createComposedExpression
Parameters
-
pretty
boolean Pretty print the expression? -
expressions
Array<string> An array of expressions. -
name
string Name of the function to compose.
Returns string Composed / piped string.
runInContext
Given an array of [sandbox, expression] Objects, process commands.
Parameters
Returns string Out string or json.
runner
Core chunk => evaluated expression function.
Parameters
-
config
Object Config from yargs. -
expressions
Array<string> List of expression strings. -
chunk
(Buffer | string) Chunk from stream.
Returns (Object | string) Converted chunk.
makeSandboxWithRequireHook
A closured form of makeSandbox designed for 100% coverage.
Parameters
Examples
const makeSandbox = makeSandboxWithRequireHook(es6hook, require)
Returns Function makeSandbox - a function
makeSandbox
Create a sandbox object to be used within the vm container.
Parameters
-
nodeModulesPath
string path to node_modules -
source
Object from cosmiconfig -
requirements
Array<string> imports -
x
string String which represents stdin | file stream.
Examples
makeSandbox('cool')
Returns Object Sandbox
createStreamFromSource
createStreamFromSource allows you to read or write from any string source or if not provided, stdin / stdout
Parameters
Returns Object a stream
toString
Returns string
concatConditionally
Binary concat method which is used to define both prepend and append methods.
Parameters
-
order
boolean Prepend or append? -
circumstance
boolean Condition? -
str
string The string to append or prepend. -
x
string The string to be appended or prepended to.
Returns string
tackOn
tackOn(y => y * 5, 10) === [10, 50].
Parameters
-
fn
Function A function to effect change. -
x
any Something else.
Returns Array X followed by a transformed x.