Unleash awesomeness. Private packages, team management tools, and powerful integrations. Get started with npm Orgs »

gulp-text-simple

0.4.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

555

version

0.4.4

license

MIT

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability