Have ideas to improve npm?Join in the discussion! »

    gulp-text-simple

    0.5.4 • Public • Published

    GulpText simple

    npm package dependency status build status

    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.

    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.

    Install

    npm i gulp-text-simple

    DownloadsWeekly Downloads

    544

    Version

    0.5.4

    License

    MIT

    Unpacked Size

    20.4 kB

    Total Files

    6

    Last publish

    Collaborators

    • avatar