Extended getting stared example with some syntax optimizations

README.md

@@ -1 +1 @@
-nss-run=======nss-run (not so simple run) is a very simplistic build tool.Instead of something like `gulp` or `grunt` where you arerequired to execute all your build steps thru plugins `nss-run`just gives you a easy way to call any external tool withouthaving to find a special plugin first.> In version >=0.2 the style of this plugin got changed from being sync to async (thru Promise) only.> This change allows way more complex tasks. In most cases it should be very simply to migrate.> Please take a look at the UPGRADE documentation!Get started-----------Install globally (for a command line script):    npm install nss-run -gInstall in your project (to use nss-run api inside your `nss-runfile.js`):    npm install nss-run --save-devIf you want to use Babel (6.x)    npm install babel-core babel-preset-es2015 babel-register --save-devCreate a `nss-runfile.js` (if you don't wanna use babel) / `nss-runfile.babel.js` (if you wanna use babel)```javascriptimport { task, taskGroup, runTask, run } from "nss-run";task("create:component", function (name) {    console.log("Component with name " + name + " created");});task("lint", function () {    return runTask("lint:test")        .then(function () {            return runTask("lint:source");        });});taskGroup("lint:test", ["lint:test:unit", "lint:test:integration"]);task("lint:test:unit", function () {    return run("eslint ./test/unit");});task("lint:test:integration", function () {    return run("eslint ./test/integration");});task("lint:source", function () {    return run("eslint ./src");});```Run:```nss-run create:component testnss-run lintnss-run lint:testnss-run lint:test:unit```Tips:* `./node_modules/.bin/` is included into PATH when running commands by `nss-run` api method* Executing `nss-run` command without arguments displays list of all available tasks (+ description if available)* `nss-run` will automatic require `babel-register` if it can not find a `nss-runfile.js` but   a `nss-runfile.babel.js` before including the runfile.Why nss-run?------------Is there really a need for a new build tool? We already have Grunt, Gulp,npm scripts, Makefile, runjs and many more.Gulp and Grunt are very complex and require special plugins to run the toolsthat make our nodejs development environment.Makefiles require you to install a tool outside of the nodejs ecosystem whichmakes getting started with a project harder then it needs to be.npm scripts in my opinion are creating to much clutter within your package.jsonYour dependency file should not need to know how to build your project.runjs is already going into the right direction (and this tool is heavily inspiredby runjs). But some of the design decisions (it is to simple) makes it hard to beused for bigger projects where you just need a bit more flexibility in terms ofhow you wanna organize your tasks. In addition the design to make it all synchronizecan cause a lot conflicts with existing nodejs libraries that might not supportsynchronized execution (e.g. some file parsers).nss-run provides you with an very simple way to execute command line tools, npminstalled tools as well as writing custom Javascript and using any npm libraryto create your own simple processing. No need to wait until a plugin makes yourfavorite tool available thru your build tool. I tried to combine my favorite partof gulp (the task definition system) and the simplicity of runjs to create a simpel(but not so simple ;)) build tool for any project size.API---```javascriptimport { task, taskGroup, runTask, run } from "nss-run";```**task(name, cb[, options])**Register a new task with the given name (do not use spaces in your name). If the task is going to be called the provided callback will be executed. A task might return a `Promise`to wait for async code to complete. Otherwise the task will be finished as soon as thecallback returns.Options:```javascript{    description: ..., // provide a description for this task for the task list output (String)    hidden: ..., // Hide this task from the task list output (true/false) - default: false}```Examples:```javascripttask("test", function () {    // my task logic here});task("test", function () {    // my task logic here}, {    description: "My test description"});```**taskGroup(name, tasksToExecute[, options])**Registers a new task (do not use spaces in your task name) that when called automatic calls all provided task names in a sequence (`tasksToExecute` has to be a string array). Ifyou provide within the `tasksToExecute` array a array of strings the tasks in that sub arrayare going to be executed in parallel before proceeding with the next sequence item.The options are the same as the options for `task`.Options:```javascript{    description: ..., // provide a description for this task for the task list output (String)    hidden: ..., // Hide this task from the task list output (true/false) - default: false}```Examples:```javascripttaskGroup("test", ["task1", "task2", "task3"]);taskGroup("test", ["task1", "task2", "task3"], {    description: "This task will call first task1, then task2 and last task3"});taskGroup("test", [["task1", "task2"], "task3"]);```**runTask(name[, arg1[, ...]])**This will execute a registered task with the given name. All arguments you passafter the name will be directly passed thru to the tasks function callback. This methodwill always return a Promise that you should use to find out if the tasks has finished.Examples:```javascriptrunTask("lint");runTask("lint", true, "my-second-argument");```**run(cmd[, options])**Run given command as a child process and log the call in the output. It will always returna promise.Options:```javascript{    cwd: .., // current working directory (String)    canFail: ... // should promise be failed if program execution failed/returned error (true/false) - default: false    stream: ... // directly log the process output (true/false) - default: true}```Examples:```javascriptrun("rm -rf ./lib");run("http-server .").then((stdout) => {    log(stdout);}).catch((error) => {    throw error;});run("http-server .", { stream: false }).then((stdout) => {    log(stdout);}).catch((error) => {    throw error;});```
+nss-run=======nss-run (not so simple run) is a very simplistic build tool.Instead of something like `gulp` or `grunt` where you arerequired to execute all your build steps thru plugins `nss-run`just gives you a easy way to call any external tool withouthaving to find a special plugin first.> In version >=0.2 the style of this plugin got changed from being sync to async (thru Promise) only.> This change allows way more complex tasks. In most cases it should be very simply to migrate.> Please take a look at the UPGRADE documentation!Get started-----------Install globally (for a command line script):    npm install nss-run -gInstall in your project (to use nss-run api inside your `nss-runfile.js`):    npm install nss-run --save-devIf you want to use Babel (6.x)    npm install babel-core babel-preset-es2015 babel-register --save-devCreate a `nss-runfile.js` (if you don't wanna use babel) / `nss-runfile.babel.js` (if you wanna use babel)```javascriptimport { task, taskGroup, runTask, run } from "nss-run";task("create:component", function (name) {    console.log("Component with name " + name + " created");});task("lint", function () {    return runTask("lint:test")        .then(function () {            return runTask("lint:source");        });});taskGroup("lint:test", ["lint:test:unit", "lint:test:integration"]);task("lint:test:unit", function () {    return run("eslint ./test/unit");});// With ES6 Arrow functions you can do thistask("lint:test:integration", () => run("eslint ./test/integration"));// And with babel (enabling async/await) you can also do thistask("lint:source", async () => {    await run("eslint ./src");    // Do something else here});```Run:```nss-run create:component testnss-run lintnss-run lint:testnss-run lint:test:unit```Tips:* `./node_modules/.bin/` is included into PATH when running commands by `nss-run` api method* Executing `nss-run` command without arguments displays list of all available tasks (+ description if available)* `nss-run` will automatic require `babel-register` if it can not find a `nss-runfile.js` but   a `nss-runfile.babel.js` before including the runfile.Why nss-run?------------Is there really a need for a new build tool? We already have Grunt, Gulp,npm scripts, Makefile, runjs and many more.Gulp and Grunt are very complex and require special plugins to run the toolsthat make our nodejs development environment.Makefiles require you to install a tool outside of the nodejs ecosystem whichmakes getting started with a project harder then it needs to be.npm scripts in my opinion are creating to much clutter within your package.jsonYour dependency file should not need to know how to build your project.runjs is already going into the right direction (and this tool is heavily inspiredby runjs). But some of the design decisions (it is to simple) makes it hard to beused for bigger projects where you just need a bit more flexibility in terms ofhow you wanna organize your tasks. In addition the design to make it all synchronizecan cause a lot conflicts with existing nodejs libraries that might not supportsynchronized execution (e.g. some file parsers).nss-run provides you with an very simple way to execute command line tools, npminstalled tools as well as writing custom Javascript and using any npm libraryto create your own simple processing. No need to wait until a plugin makes yourfavorite tool available thru your build tool. I tried to combine my favorite partof gulp (the task definition system) and the simplicity of runjs to create a simpel(but not so simple ;)) build tool for any project size.API---```javascriptimport { task, taskGroup, runTask, run } from "nss-run";```**task(name, cb[, options])**Register a new task with the given name (do not use spaces in your name). If the task is going to be called the provided callback will be executed. A task might return a `Promise`to wait for async code to complete. Otherwise the task will be finished as soon as thecallback returns.Options:```javascript{    description: ..., // provide a description for this task for the task list output (String)    hidden: ..., // Hide this task from the task list output (true/false) - default: false}```Examples:```javascripttask("test", function () {    // my task logic here});task("test", function () {    // my task logic here}, {    description: "My test description"});```**taskGroup(name, tasksToExecute[, options])**Registers a new task (do not use spaces in your task name) that when called automatic calls all provided task names in a sequence (`tasksToExecute` has to be a string array). Ifyou provide within the `tasksToExecute` array a array of strings the tasks in that sub arrayare going to be executed in parallel before proceeding with the next sequence item.The options are the same as the options for `task`.Options:```javascript{    description: ..., // provide a description for this task for the task list output (String)    hidden: ..., // Hide this task from the task list output (true/false) - default: false}```Examples:```javascripttaskGroup("test", ["task1", "task2", "task3"]);taskGroup("test", ["task1", "task2", "task3"], {    description: "This task will call first task1, then task2 and last task3"});taskGroup("test", [["task1", "task2"], "task3"]);```**runTask(name[, arg1[, ...]])**This will execute a registered task with the given name. All arguments you passafter the name will be directly passed thru to the tasks function callback. This methodwill always return a Promise that you should use to find out if the tasks has finished.Examples:```javascriptrunTask("lint");runTask("lint", true, "my-second-argument");```**run(cmd[, options])**Run given command as a child process and log the call in the output. It will always returna promise.Options:```javascript{    cwd: .., // current working directory (String)    canFail: ... // should promise be failed if program execution failed/returned error (true/false) - default: false    stream: ... // directly log the process output (true/false) - default: true}```Examples:```javascriptrun("rm -rf ./lib");run("http-server .").then((stdout) => {    log(stdout);}).catch((error) => {    throw error;});run("http-server .", { stream: false }).then((stdout) => {    log(stdout);}).catch((error) => {    throw error;});```