Loosen restrictions on run task wording

README.md

@@ -1,15 +1,14 @@
-
 # maid
 
-[![NPM version](https://img.shields.io/npm/v/maid.svg?style=flat)](https://npmjs.com/package/maid) [![NPM downloads](https://img.shields.io/npm/dm/maid.svg?style=flat)](https://npmjs.com/package/maid) [![CircleCI](https://circleci.com/gh/egoist/maid/tree/master.svg?style=shield)](https://circleci.com/gh/egoist/maid/tree/master)  [![donate](https://img.shields.io/badge/$-donate-ff69b4.svg?maxAge=2592000&style=flat)](https://github.com/egoist/donate) [![chat](https://img.shields.io/badge/chat-on%20discord-7289DA.svg?style=flat)](https://chat.egoist.moe)
+[![NPM version](https://img.shields.io/npm/v/maid.svg?style=flat)](https://npmjs.com/package/maid) [![NPM downloads](https://img.shields.io/npm/dm/maid.svg?style=flat)](https://npmjs.com/package/maid) [![CircleCI](https://circleci.com/gh/egoist/maid/tree/master.svg?style=shield)](https://circleci.com/gh/egoist/maid/tree/master) [![donate](https://img.shields.io/badge/$-donate-ff69b4.svg?maxAge=2592000&style=flat)](https://github.com/egoist/donate) [![chat](https://img.shields.io/badge/chat-on%20discord-7289DA.svg?style=flat)](https://chat.egoist.moe)
 
 > Markdown driven task runner.
 
 ## Table of Contents
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
 - [Install](#install)
 - [What is a maidfile?](#what-is-a-maidfile)
@@ -52,13 +51,13 @@ npm i -D maid
 yarn add maid --dev
 ```
 
-<small>__PRO TIP__: you can use `npx` or `yarn` command to run any locally installed executable that is inside `node_modules/.bin/`, e.g. use `yarn maid` to run the locally installed maid command.</small>
+<small>**PRO TIP**: you can use `npx` or `yarn` command to run any locally installed executable that is inside `node_modules/.bin/`, e.g. use `yarn maid` to run the locally installed maid command.</small>
 
 ## What is a maidfile?
 
 A maidfile is where you define tasks, in Markdown!
 
-📝 __maidfile.md__:
+📝 **maidfile.md**:
 
 ````markdown
 ## lint
@@ -74,6 +73,7 @@ eslint --fix
 Build our main app
 
 <!-- Following line is a maid command for running task -->
+
 Run task `build:demo` after this
 
 ```bash
@@ -90,20 +90,21 @@ You can use JavaScript to write to task script too!
 const webpack = require('webpack')
 
 // Async task should return a Promise
-module.exports = () => new Promise((resolve, reject) => {
-  const compiler = webpack(require('./webpack.config'))
-  compiler.run((err, stats) => {
-    if (err) return reject(err)
-    console.log(stats.toString('minimal'))
-    resolve()
+module.exports = () =>
+  new Promise((resolve, reject) => {
+    const compiler = webpack(require('./webpack.config'))
+    compiler.run((err, stats) => {
+      if (err) return reject(err)
+      console.log(stats.toString('minimal'))
+      resolve()
+    })
   })
-})
 ```
 ````
 
-Each task is defined using `h2` header and its child contents, the value of `h2` header will be used as task name, its following paragraphs (optional) will be used as task description, and following code block (optional) will be used as task script. 
+Each task is defined using `h2` header and its child contents, the value of `h2` header will be used as task name, its following paragraphs (optional) will be used as task description, and following code block (optional) will be used as task script.
 
-Currently the code block languages are `sh` `bash` `js` `javascript` [and more](#code-block-languages)!. 
+Currently the code block languages are `sh` `bash` `js` `javascript` [and more](#code-block-languages)!.
 
 Now run `maid help` to display the help for this maidfile:
 
@@ -157,21 +158,25 @@ gh-pages -d dist
 ```
 ````
 
-Basically expressions like ``Run task `deploy` after this`` is treated specially, in this case if you run `maid build`, it will also run `deploy` task when `build` task is finished.
+Expressions that start with `Run(s)? task(s)?` are treated specially. In this case if you run `maid build` it will also run the `deploy` task after `build` has finished.
+
+The syntax is simple: `Runs? tasks? <taskNames> (before|after) this (in parallel)?` where each task name is surrounded by a pair of backticks: <code>`</code>.
 
-The syntax is simple: `Run tasks? <taskNames> (before|after) this (in parallel)?` where each task name is surrounded by a pair of backticks: <code>`</code>.
+By default a task will run before the current task. So `` Run task `build` `` would run `build` before the task it was described in. The presence of `after` anywhere in the setence (after `Run task`) will cause it to be ran after. Commands run synchronously by default. The presence of `in parallel` in the scentence will cause it to be run in parallel.
 
 Examples:
 
-- ``Run task `build` after this.``
-- ``Run tasks `build:app` `start:server` before this.``
-- ``Run tasks `build:server` `build:client` before this in parallel.``
+- `` Run task `build`. ``
+- `` Run task `build` after this. ``
+- `` Run tasks `clean`, `build`, and `lint`. ``
+- `` Run tasks `build:app` `start:server` before this. ``
+- `` Run tasks `build:server` `build:client` before this in parallel. ``
 
 ### Task hooks
 
 Like npm scripts, when you run a command called `build`, when it's finished we will also run `postbuild` task.
 
-Hook syntax: 
+Hook syntax:
 
 - `pre<taskName>`: Run before a specific task.
 - `post<taskName>`: Run after a specific task.
@@ -289,24 +294,23 @@ Similar to the `lint` task, you can append any flags for `ava` command directly
 
 ### toc
 
-Generate a __table of contents__ section in the README.md file.
+Generate a **table of contents** section in the README.md file.
 
 ```bash
 yarn doctoc README.md
 ```
 
 ## Contributing
 
-1. Fork it!
-2. Create your feature branch: `git checkout -b my-new-feature`
-3. Commit your changes: `git commit -am 'Add some feature'`
-4. Push to the branch: `git push origin my-new-feature`
-5. Submit a pull request :D
-
+1.  Fork it!
+2.  Create your feature branch: `git checkout -b my-new-feature`
+3.  Commit your changes: `git commit -am 'Add some feature'`
+4.  Push to the branch: `git push origin my-new-feature`
+5.  Submit a pull request :D
 
 ## Author
 
 **maid** © [egoist](https://github.com/egoist), Released under the [MIT](./LICENSE) License.<br>
 Authored and maintained by egoist with help from contributors ([list](https://github.com/egoist/maid/contributors)).
 
-> [github.com/egoist](https://github.com/egoist) · GitHub [@egoist](https://github.com/egoist) · Twitter [@_egoistlily](https://twitter.com/_egoistlily)
+> [github.com/egoist](https://github.com/egoist) · GitHub [@egoist](https://github.com/egoist) · Twitter [@\_egoistlily](https://twitter.com/_egoistlily)

lib/parseMarkdown.js

@@ -9,36 +9,27 @@ const md = new MarkdownIt({
 
 const {
   wildcard,
-  capture,
   extra,
-  or,
   and,
-  matchers: { ANY, WHITE_SPACE: SPACE, START, LAZY },
+  matchers: { WHITE_SPACE: SPACE, START, LAZY },
   flags
 } = require('rexrex')
 
 const space = extra(SPACE)
 const isCommandReTemplate = and(
   START, // ^
   wildcard(SPACE),
-  [
-    'Run',
-    'tasks' + LAZY,
-    capture(extra(ANY)),
-    capture(or('after', 'before')),
-    'this'
-  ].join(space),
-  capture(and(space, 'in', space, 'parallel')),
-  LAZY,
-  wildcard(SPACE)
+  ['Runs' + LAZY, 'tasks' + LAZY].join(space)
 )
 
 const isCommandRe = new RegExp(isCommandReTemplate, flags.INSENSITIVE)
+const commandsRe = new RegExp(/`([^`]+)`/g)
 const isCommand = v =>
-  isCommandRe.test(v) && isCommandRe.exec(v)[1].includes('`')
+  Boolean(v.match(isCommandRe)) && Boolean(v.match(commandsRe))
 const parseCommand = v => {
-  const [, command, when, inParallel] = isCommandRe.exec(v)
-  const taskNames = command.match(/`([^`]+)`/g).map(v => /`(.+)`/.exec(v)[1])
+  const inParallel = Boolean(v.match(/in\s+parallel/i))
+  const when = (v.match(/before|after/i) || ['before'])[0]
+  const taskNames = v.match(commandsRe).map(v => /`(.+)`/.exec(v)[1])
 
   return {
     taskNames,
@@ -169,3 +160,6 @@ module.exports = (content, { section, filepath } = {}) => {
     tasks
   }
 }
+
+module.exports.isCommand = isCommand
+module.exports.parseCommand = parseCommand

test/parseMarkdown.test.js

@@ -1,5 +1,6 @@
 const test = require('ava')
 const parseMarkdown = require('../lib/parseMarkdown')
+const { isCommand, parseCommand } = parseMarkdown
 
 test('simple', t => {
   const res = parseMarkdown(`
@@ -30,6 +31,44 @@ echo goodbye
   t.snapshot(res)
 })
 
+test('parseCommand', t => {
+  t.deepEqual(parseCommand('run task `blah`'), {
+    taskNames: ['blah'],
+    when: 'before',
+    inParallel: false
+  })
+
+  t.deepEqual(
+    parseCommand('Runs task `blah` in parallel after this task has completed'),
+    {
+      taskNames: ['blah'],
+      when: 'after',
+      inParallel: true
+    }
+  )
+
+  t.deepEqual(parseCommand('run task `blah` in parallel'), {
+    taskNames: ['blah'],
+    when: 'before',
+    inParallel: true
+  })
+
+  t.deepEqual(parseCommand('run tasks `blah`, `bleh`, and `blu`'), {
+    taskNames: ['blah', 'bleh', 'blu'],
+    when: 'before',
+    inParallel: false
+  })
+
+  t.deepEqual(
+    parseCommand('run tasks `blah`, `bleh`, and `blu` after this in parallel'),
+    {
+      taskNames: ['blah', 'bleh', 'blu'],
+      when: 'after',
+      inParallel: true
+    }
+  )
+})
+
 test('selected section', t => {
   const section = `
 ## hey
@@ -84,3 +123,14 @@ MIT
 
   t.snapshot(res)
 })
+
+test('isCommand', t => {
+  t.false(isCommand('Run task'))
+  t.true(isCommand('Run task `blah`'))
+  t.true(isCommand('run Task `blah`'))
+  t.true(isCommand('Runs task `blah`'))
+  t.true(isCommand('Run tasks `blah` and `blah`'))
+  t.true(isCommand('Runs tasks `blah` and `blah`'))
+  t.true(isCommand('Run tasks `blah` and `blah` in parallel'))
+  t.true(isCommand('Run task `blah` after this in parallel'))
+})