Provide an API to pass parameters which resemble options (#792)

This adds the special option string `--`, which means "no options". This can be
passed if the first parameter looks like an option (starts with a `-` followed
by 1+ letters).

Fixes #778

README.md

@@ -94,6 +94,16 @@ if (shell.exec('git commit -am "Auto-commit"').code !== 0) {
 }
 ```
 
+## Exclude options
+
+If you need to pass a parameter that looks like an option, you can do so like:
+
+```js
+shell.grep('--', '-v', 'path/to/file'); // Search for "-v", no grep options
+
+shell.cp('-R', '-dir', 'outdir'); // If already using an option, you're done
+```
+
 ## Global vs. Local
 
 We no longer recommend using a global-import for ShellJS (i.e.

src/common.js

@@ -171,6 +171,11 @@ function parseOptions(opt, map, errorOptions) {
     throw new Error('parseOptions() internal error: errorOptions must be object');
   }
 
+  if (opt === '--') {
+    // This means there are no options.
+    return {};
+  }
+
   // All options are false by default
   var options = {};
   Object.keys(map).forEach(function (letter) {

test/common.js

@@ -264,6 +264,18 @@ test('common.parseOptions throws when passed a string not starting with "-"', t
   }, Error, "Options string must start with a '-'");
 });
 
+test('common.parseOptions with -- argument', t => {
+  const result = common.parseOptions('--', {
+    R: 'recursive',
+    f: 'force',
+    r: 'reverse',
+  });
+
+  t.falsy(result.recursive);
+  t.falsy(result.force);
+  t.falsy(result.reverse);
+});
+
 test('Some basic tests on the ShellString type', t => {
   const result = shell.ShellString('foo');
   t.is(result.toString(), 'foo');

test/grep.js

@@ -136,3 +136,9 @@ test('-l option', t => {
   t.falsy(result.match(/file2.txt/));
   t.is(result.split('\n').length - 1, 2);
 });
+
+test('the pattern looks like an option', t => {
+  const result = shell.grep('--', '-v', 'test/resources/grep/file2');
+  t.falsy(shell.error());
+  t.is(result.toString(), '-v\n-vv\n');
+});

test/resources/grep/file2

@@ -0,0 +1,3 @@
+-v
+-vv
+-a