echo(), to()

shell.js

@@ -27,10 +27,21 @@ var state = {
 
 
 //@
-//@ #### echo('message' [,'message' ...])
-exports.echo = wrap('echo', function() {
-  console.log.apply(this, arguments);
-});
+//@ #### echo(string [,string ...])
+//@
+//@ Examples:
+//@
+//@ + `echo('hello world')`
+//@ + `var str = echo('hello world');`
+//@
+//@ Prints string to stdout, and returns augmented `String()` object with additional utility methods
+//@ like `.to()`.
+function _echo(options) {
+  var messages = [].slice.call(arguments, 1);
+  log.apply(this, messages);
+  return new ShellString(messages.join(' '));
+};
+exports.echo = wrap('echo', _echo);
 
 //@
 //@ #### ls([options] [,path] [,path ...])
@@ -150,7 +161,8 @@ exports.cd = wrap('cd', _cd);
 //@ #### shell.pwd()
 //@ Returns the current directory.
 function _pwd(options) {
-  return path.resolve(process.cwd());
+  var pwd = path.resolve(process.cwd());
+  return new ShellString(pwd);
 };
 exports.pwd = wrap('pwd', _pwd);
 
@@ -429,14 +441,18 @@ function _cat(options, files) {
   if (cat[cat.length-1] === '\n')
     cat = cat.substring(0, cat.length-1);
 
-  return cat;
+  return new ShellString(cat);
 };
 exports.cat = wrap('cat', _cat);
 
 //@
-//@ #### 'any string'.to('file')
-//@ Analogous to the redirection operator `>` in Unix, but works with JavaScript strings. 
-//@ For example, to redirect the output of `cat()` to a file, use: `cat('input.txt').to('output.txt')`. 
+//@ #### 'shell string'.to(file)
+//@
+//@ Examples:
+//@
+//@ + `cat('input.txt').to('output.txt')`
+//@
+//@ Analogous to the redirection operator `>` in Unix, but works with strings returned by a shell command. 
 //@ _Like Unix redirections, `to()` will overwrite any existing file!_
 function _to(options, file) {
   if (!file)
@@ -447,14 +463,23 @@ function _to(options, file) {
 
   fs.writeFileSync(file, this.toString(), 'utf8');
 };
-String.prototype.to = wrap('to', _to);
+// Augmented String() object, to mimick Unix redirection operators
+function ShellString(str) {
+  var s = new String(str);
+  s.to = wrap('to', _to);
+  return s;
+}
 
 //@
-//@ #### sed([options ,] search_regex, 'replace_str', 'file')
+//@ #### sed([options ,] search_regex, replace_str, file)
 //@ Available options:
 //@
-//@ + `inplace`: (Default is `false`) If `true` will replace contents of 'file' with 
-//@ the modified string. _Note that no backups will be created!_
+//@ + `-i`: Replace contents of 'file' in-place. _Note that no backups will be created!_
+//@
+//@ Examples:
+//@
+//@ + `sed('-i', 'PROGRAM_VERSION', 'v0.1.3', 'source.js')`
+//@ + `sed(/.*DELETE_THIS_LINE.*\n/, '', 'source.js')`
 //@
 //@ Reads an input string from `file` and performs a JavaScript `replace()` on the input
 //@ using the given search regex and replacement string. Returns the modified string.
@@ -480,7 +505,7 @@ function _sed(options, regex, replacement, file) {
   if (options.inplace)
     result.to(file);
 
-  return result;
+  return new ShellString(result);
 };
 exports.sed = wrap('sed', _sed);
 
@@ -510,7 +535,7 @@ function _grep(options, regex, filesStr) {
     });
   });
 
-  return grep;
+  return new ShellString(grep);
 };
 exports.grep = wrap('grep', _grep);
 
@@ -718,9 +743,9 @@ exports.silent = function() {
 // Auxiliary functions (internal use only)
 //
 
-function log(msg) {
+function log() {
   if (!state.silent)
-    console.log(msg);
+    console.log.apply(this, arguments);
 }
 
 function write(msg) {

test/echo.js

@@ -0,0 +1,26 @@
+var shell = require('..');
+
+var assert = require('assert'),
+    path = require('path'),
+    fs = require('fs');
+
+// Node shims for < v0.7
+fs.existsSync = fs.existsSync || path.existsSync;
+
+shell.silent();
+
+function numLines(str) {
+  return typeof str === 'string' ? str.match(/\n/g).length : 0;
+}
+
+shell.rm('-rf', 'tmp');
+shell.mkdir('tmp')
+
+//
+// Valids
+//
+
+assert.equal(shell.echo('hello world'), 'hello world');
+assert.equal(shell.error(), null);
+
+shell.exit(123);

test/targets.js

@@ -1,40 +0,0 @@
-require('../maker');
-
-var assert = require('assert'),
-    path = require('path');
-
-var callStack = [];
-
-callStack.push('__bare__');
-
-target.all = function() {
-  callStack.push('all');
-
-  target.test1();
-  target.test3(); // already executed by test2 - shouldn't get called again
-}
-
-target.test1 = function() {
-  callStack.push('test1');
-  target.test2();
-}
-
-target.test2 = function() {
-  callStack.push('test2');
-  target.test3();
-}
-
-target.test3 = function() {
-  callStack.push('test3');
-}
-
-setTimeout(function() {
-  assert.equal(callStack.length, 5);
-  assert.equal(callStack[0], '__bare__');
-  assert.equal(callStack[1], 'all');
-  assert.equal(callStack[2], 'test1');
-  assert.equal(callStack[3], 'test2');
-  assert.equal(callStack[4], 'test3');
-
-  exit(123);
-}, 0);

test/to.js

@@ -1,4 +1,4 @@
-require('../maker');
+var shell = require('..');
 
 var assert = require('assert'),
     path = require('path'),
@@ -7,7 +7,7 @@ var assert = require('assert'),
 // Node shims for < v0.7
 fs.existsSync = fs.existsSync || path.existsSync;
 
-silent();
+shell.silent();
 
 function numLines(str) {
   return typeof str === 'string' ? str.match(/\n/g).length : 0;
@@ -20,20 +20,20 @@ shell.mkdir('tmp')
 // Invalids
 //
 
-'hello world'.to();
-assert.ok(error());
+shell.echo('hello world').to();
+assert.ok(shell.error());
 
 assert.equal(fs.existsSync('/asdfasdf'), false); // sanity check
-'hello world'.to('/asdfasdf/file');
-assert.ok(error());
+shell.echo('hello world').to('/asdfasdf/file');
+assert.ok(shell.error());
 
 //
 // Valids
 //
 
-'hello world'.to('tmp/to1')
-var result = cat('tmp/to1');
-assert.equal(error(), null);
+shell.echo('hello world').to('tmp/to1');
+var result = shell.cat('tmp/to1');
+assert.equal(shell.error(), null);
 assert.equal(result, 'hello world');
 
-exit(123);
+shell.exit(123);