glupost v4.1.0

glupost

Build your gulp tasks from a configuration object.

Usage

Running

gulp start

with a gulpfile.js

// Transforms/plugins.
let toc = require("gulp-markdown-toc")()
let marked = (contents, file) => require("marked")(contents)


// Build tasks.
let tasks = {
   "md-to-html": {
      src: "src/docs/*.md",
      rename: {extname: ".html"},
      transforms: [toc, marked],
      watch: true
   },
   "start": {
      series: ["md-to-html", "watch"]
   }
}

let options = {
   template = {
      base: "src/",
      dest: "dist/"
   }
}

// Build the actual tasks.
let glupost = require("glupost")
module.exports = glupost(tasks, options)

and a file structure

├── src/
│   ├── docs/
│   │   ├── Getting started.md
│   │   ├── API.md
│   │   ├── Guidelines.md
│   │   └── Examples.md

would run start, that is, md-to-html and watch in series, producing

├── dist/
│   ├── docs/
│   │   ├── Getting started.html
│   │   ├── API.html
│   │   ├── Guidelines.html
│   │   └── Examples.html

once initially, and again on every file change.

API

glupost(tasks[, options])

Return an object containing gulp tasks ready for registration.

tasks » object declaring the tasks, invoked by gulp <task>.

options.template » object serving as a base for tasks with .src.

options.beep » boolean controlling if a beep sound is played once all watch-triggered tasks execute. false by default.

options.register » boolean controlling if tasks are registered to gulp or not. false by default.

Declaration of a task takes one of the following forms:

{
   // Name of another task.
   "alias": "another task",

   // Function.
   "sync callback": () => {},
   "async callback": (done) => done(),
   "async promise": async () => {},

   // Task object.
   "vinyl stream task": {
      src: "path",
      dest: "."
   },
   "wrapped": {
      task: () => {}
   },
   "tasks in series": {
      series: [...]
   },
   "tasks in parallel": {
      parallel: [...]
   }
}

A composition task object accepts one of:

.task » wrapper around a task, useful for {watch: "path", task: () => {}}.

.series » passed to gulp.series(), but also accepts task objects.

.parallel » passed to gulp.parallel(), but also accepts task objects.

A Vinyl stream task object (and options.template) accepts:

.src » string passed to gulp.src() to start the stream or a Vinyl file.

.dest » passed to gulp.dest() to output the files. Defaults to gulp's working directory.

.base » passed as base option to gulp.src().

.rename » passed to gulp-rename prior to writing.

.transforms » array of transform functions that receive file.contents and file parameters and must return a Vinyl file or its contents directly (as string or buffer), or a promise that resolves with one of those.

// Return string directly.
function copyright(contents) {
  return contents + "\nCopyright © 2017"
}

// Return Vinyl file.
function copyright(contents, file) {
  let suffix = Buffer.from("\nCopyright © 2017")
  file.contents = Buffer.concat(contents, suffix)
  return file
}

// Return promise.
async function copyright(contents) {
  return contents + "\nCopyright © 2017"
}

All task objects accept:

.watch » paths used by gulp.watch() to trigger the task. If set to true, the task's .src will be watched. All watchers are invoked by the generated watch task.