gulp-subtask

Getting started

npm install gulp-subtask

---

Usage

• Case1 : Basic usage.
• Case2 : pipe after sub task
• Case3 : Run with options.
• Case4 : Using between gulp pipes.
• Case5 : Watch the task.
• Case6 : Do something after run task by watch().
• Case7 : Using with non stream return plugins.

At first.

Initialize gulp-subtask with gulp.

var g       = require('gulp');
var SubTask = require('gulp-subtask')( g );

Case1 : Basic usage.

Create task likes gulp tasks.

var task = new SubTask()
    .src( 'test/js/*.js' )
    .pipe( concat, 'all.js' )
    .on('end',function(){
        console.log('Concat ended.');
    })
    .pipe( g.dest, 'test/dest/js' );
 
task.run();

Case2 : pipe after sub task

gulp-subtask returns pipe stream.

var task = new SubTask('task')
    .src( 'test/js/*.js' )
    .pipe( concat, 'all.js' );
 
task.run()
    .pipe( g.dest('test/dest/js') );

Case3 : Run with options.

For example. If you want to change flexibly input src, output, and more.

var task = new SubTask('task')
    .src( '{{src}}' )
    .pipe( concat, '{{concat}}' )
    .pipe( g.dest, 'test/dest/js' );
 
task.run({
    src    : 'test/js/*.js',
    concat : 'all_a.js'
});
task.run({
    src    : 'test/js/*.js',
    concat : 'all_b.js'
});

You can get 'test/dest/js/all_a.js' and 'test/dest/js/all_b.js'.

Options is powerful solution of gulp-subtasks.
You can replace all '{{key}}' markers recursivly.

For example...

var tsc = new subtask('tsc')
    .src(['{{srcDir}}/*.ts','!**/*.d.ts'])
    .pipe( plumber )
    .pipe( tsc, { declaration : true, out:'{{out}}' })
    .pipe( g.dest, '{{srcDir}}' )
    .pipe( filter, '{{filter}}' )
    .pipe( g.dest, '{{dest}}' );
 
tsc.run({
    'srcDir' : 'path/to/ts',
    'out'    : 'output.js',
    'filter' : ['*','!*.d.ts'],
    'dest'   : 'path/to/dest/js'
});

This code is same as below.

var tsc = new subtask('tsc')
    .src(['path/to/ts/*.ts','!**/*.d.ts'])
    .pipe( plumber )
    .pipe( tsc, { declaration : true, out:'output.js' })
    .pipe( g.dest, 'path/to/ts' )
    .pipe( filter, ['*','!*.d.ts'] )
    .pipe( g.dest, 'path/to/dest/js' );
 
tsc.run();

If you would like to know replace rules.
Check out the Replace Rules term.

Case4 : Using between gulp pipes.

gulp-subtask is be able to using between gulp pipes. In that case. You have to make a task without src method.

var task = new SubTask('task')
    // Don't call src() method!!
    .pipe( concat, 'all.js' );
 
g.src( 'test/js/*.js' )
 .pipe( task.run() )
 .pipe( g.dest('test/dest/js') );

Ofcourse you can use options during pipe.

var task = new SubTask('task')
    .pipe( concat, '{{name}}' );
 
g.src( 'test/js/*.js' )
 .pipe( task.run({name:'all.js'}) )
 .pipe( g.dest('test/dest/js') );

Case5 : Watch the task.

If you want to watch subTask.src and run. Simply call watch.

var task = new SubTask()
    .src( 'test/js/*.js' )
    .pipe( concat, 'all.js' )
    .pipe( g.dest, 'test/dest/js' );
 
task.watch();

Ofcourse you can use options with watch method.

task.watch( options );

If you watch with another src.
Call watchWith method.

task.watchWith( 'another/path/to/*js', options );

If you watch as another src.
Call watchAs method.

task.watchAs( 'another/path/to/*js', options );

Case6 : Do something after run task by watch().

gulp-subtask can piping other task when watched task run.

task.watch( options )
    .on('run',function(subtask){
        subtask.pipe( gulp.dest, '/another/path/to/dest' );
    })

Case 7 : Using with non stream return plugins.

For exsample gulp-typescript pipes not return stream.

gulp.src("*.ts")
    .pipe(typescript())
    .js
    .pipe( gulp.dest("outDir") );

In that case. Use done method.

var task = new SubTask()
    .src( "" )
    .pipe( typescript )
    .done(
        function(result,options){
            // This return used after pipe.
            return result.js
        }
    )
    .pipe( g.dest, 'test/dest/js' );
 
tast.run();

var task = new SubTask()
    .src( "{{srcDir}}/*.ts" )
    .pipe( typescript )
    .done(
        function(result,options){
            return result.js.pipe(g.dest(options.srcDir))
        }
    );
 
task.run({srcDir:"path/to/src"});

---

Replace Rules

This term is talking about options replace rules.

Case 1 : Replace string.

If you want to replace from string to object or array.
Use only one marker in target string.

target

'{{object}}'

options

{
    'object' : {key:'value'}
}

result

{key:'value'}

If target string has charactor other than marker or multiple markers. Not string values are automatically replace toString() value.

target

'{{string}} {{object}} {{array}}.'

options

{
    'string' : 'This is string.',
    'object' : {'text':'This is object'},
    'array'  : ['This','is','array']
}

result

'This is string. [object Object] This,is,array'

Case2 : Replace makers in object or array

Options can replace markers in object or array recursivly.

target

{
    'obj' : {
        'arr' : [
            '{{src}}',
            'dest is {{dest}}'
        ],
        'str' : 'src is {{src}}',
        'mix' : [
            '{{src}}',
            [
                '{{obj}}',
                {'str':'{{src}}'}
            ]
        ]
    }
}

options

{
    'src'  : 'path/to/js',
    'dest' : 'path/to/dest',
    'obj'  : {
        'key' : 'value'
    }
}

result

{
    'obj' : {
        'arr' : [
            'path/to/js',
            'dest is path/to/dest'
        ],
        'str' : 'src is path/to/js',
        'mix' : [
            'path/to/js',
            [
                {'key':'value'},
                {'str':'path/to/js'}
            ]
        ]
    }
}

---

API

SubTask.src( src );

example

task.src(['path/to/js/*.js','!**/*.map'])

src

Type: String or Array

SubTask.pipe( fnc, ...args );

example

task.pipe( concat, 'all.js' );

task.pipe( someTask, arg1, arg2, arg3 );

fnc

Type: Function

What plugins want to use. Don't call. Set function's reference only.

...args

Type: Any

SubTask.run( fnc );

example

task.pipe( gulp_typescript )
    .done(function(result){
        result.js.pipe( gulp.dest("out") );
    });

fnc

Type: Function

Call with before pipes result.

SubTask.run( options );

example

task.run();

task.run({name:'test.js'});

options

Type: Object

Key-Value Object.

SubTask.watch( options );

example

task.watch();

task.watch({name:'test.js'});

options

Type: Object

Key-Value Object.

---

---

Update history

0.3.3 Add done method.