GulpText simple

simple creation of Gulp transformations for text files

A lot of Gulp tasks are dealing with text files. And often you want to just create a simple task for transforming the text content of a file in your project. E.g. replace some placeholders with a regular expression. But if you want to write a custom Gulp task for it, you have to deal with buffers, encoding, streams, different vinyl objects, ....

GulpText simple makes it really simple to create first class Gulp transformations with a simple API, and an extra benefit of helper functions for dealing with files directly.

Minimal NodeJS version is currently version 16. For older NodeJS versions use gulp-text-simple v0.5.x.

Features

• support for buffer file objects
• support for stream file objects
• supports passing additional options to the transformation function
• passing the source path of the vinyl file as an option into the transformation function
• control the input and output encoding
• the transformation factory behaves like the transformation function, if the first argument is a string
• read and transform the content of a text file synchronously and asynchronously
• transform a text file synchronously and asynchronously
• automatic JSON conversion of non-string results from the transformation function

Introduction

All examples are based on the following preamble.

var gulp = require('gulp');
var textTransformation = require('gulp-text-simple');

With GulpText simple you can just implement a function, taking a string and returning a string. It will create a Gulp transformation factory for you, which you can use with .pipe().

var transformString = function (s) {
    // do whatever you want with the text content of a file
    return s.toLowerCase();
};

// create the factory with GulpText simple
var myTransformation = textTransformation(transformString);

gulp.task('default', function () {
    return gulp.src('src/*.txt')
        .pipe(myTransformation()) // create the Gulp transformation and insert it into the Gulp stream
        .pipe(gulp.dest('out/'));
});

Options

If you need to pass options, you can give them as a map to the factory.

var transformString = function (s, options) {
    // do whatever you want with the text content of a file
    if (options.mode === 'lower') {
        return s.toLowerCase();
    } else if (options.mode === 'upper') {
        return s.toUpperCase();
    } else {
        return s;
    }
};

// create the Gulp transformation factory with GulpText simple
var myTransformation = textTransformation(transformString);

gulp.task('default', function () {
    return gulp.src('src/*.txt')
        .pipe(myTransformation({ mode: 'upper' })) // create the transformation with options
        .pipe(gulp.dest('out/'));
});

Default Options

If you want to pepare default options for a transformation, you can pass them to GulpText simple as second argument.

var transformString = function (s, options) {
    assert.equal(options.myOption, 'abc');
    return s;
};

// create the Gulp transformation factory with default options
var myTransformation = textTransformation(transformString, { myOption: 'abc' });

gulp.task('default', function () {
    return gulp.src('src/*.txt')
        .pipe(myTransformation()) // create the transformation without options
        .pipe(gulp.dest('out/'));
});

Encoding

You can control the encoding of reading and writing files and buffers with the options sourceEncoding and targetEncoding.

var myTransformation = textTransformation(function (s) { 
    return s.toLowerCase(); 
});

gulp.task('default', function () {
    return gulp.src('src/*.txt')
        .pipe(myTransformation({ // create the transformation with explicit encoding
            sourceEncoding: 'utf16le',
            targetEncoding: 'utf8'
        }))
        .pipe(gulp.dest('out/'));
});

The default encoding for input is UTF-8. The default encoding for output is the encoding of the input. Allowed are all encodings, supported by Buffer.

Source Path

The source path of a file is allways passed as option sourcePath to the transformation function. If the custom options allready have an attribute sourcePath it is not overridden.

var os = require('os');

var transformString = function (text, options) {
    // putting the source path as a prefix at the top of the text
    var prefix = options.prefix; // custom options are preserved
    var pathOfFile = options.sourcePath; // the sourcePath is merged into the custom options
    return prefix + pathOfFile + os.EOL + text;
};

// create the Gulp transformation factory
var myTransformation = textTransformation(transformString);

gulp.task('default', function () {
    return gulp.src('src/*.txt')
        .pipe(myTransformation({ prefix: '# ' })) // create the transformation and pass it to Gulp
        .pipe(gulp.dest('out/'));
});

API

Calling GulpText simple creates a factory which can be used in a number of different ways:

• call t("text"[, options]) like the original transformation function
• call t([options]), to create a Gulp transformation
• call t.readFile(filePath[, options], callback) to read and transform a file asynchronously
• call t.readFileSync(filePath[, options]) to read and transform a file synchronously
• call t.transformFile(sourcePath, targetPath[, options], callback) to read, transform, and write a file asynchronously
• call t.transformFileSync(sourcePath, targetPath[, options]) to read, transform, and write a file synchronously

Usa as a Function

You can call the factory like the original transformation function. If the first argument passed to the factory is a string, it behaves like the transformation function.

var transformString = function (s, options) {
    // do whatever you want with the text content of a file
    return s.toLowerCase();
};

// create the factory with GulpText simple
var transformation = textTransformation(transformString);

// call the factory as if it where the original transformation function
var result = transformation("ABC");
console.log(result); // -> abc

Use with Gulp

You can use the factory to create a Gulp transformation.

var transformString = function (s) {
    // do whatever you want with the text content of a file
    return s.toLowerCase();
};

// create the factory with GulpText simple
var myTransformation = textTransformation(transformString);

gulp.task('default', function () {
    return gulp.src('src/*.txt')
        .pipe(myTransformation()) // create the Gulp transformation and insert it into the Gulp stream
        .pipe(gulp.dest('out/'));
});

Read and transform asynchronously

You can call .readFile(filePath[, options], callback) on the factory, to read and transform the content of a file asynchronously.

var myTransformation = textTransformation(function (s) {
    return s.toLowerCase();
});

myTransformation.readFile('my/text_file.txt', function (err, result) {
    if (err) {
        console.log(err);
    } else {
        console.log(result);
    }
});

Read and transform synchronously

You can call .readFileSync(filePath[, options]) on the factory, to read and transform the content of a file synchronously.

var myTransformation = textTransformation(function (s) {
    return s.toLowerCase();
});

var result = myTransformation.readFileSync('my/text_file.txt');
console.log(result);

Read, transform, and write asynchronously

You can call .transformFile(sourcePath, targetPath[, options], callback) on the factory, to read, transform, and write the content of a file asynchronously.

var myTransformation = textTransformation(function (s) {
    return s.toLowerCase();
});

myTransformation.transformFile('my/text_file.txt', 'my/result.txt', function (err) {
    if (err) {
        console.log(err);
    }
});

Read, transform, and write synchronously

You can call .transformFileSync(sourcePath, targetPath[, options]) on the factory, to read, transform, and write the content of a file synchronously.

var myTransformation = textTransformation(function (s) {
    return s.toLowerCase();
});

myTransformation.transformFileSync('my/text_file.txt', 'my/result.txt');

License

GulpText simple is published under MIT license.