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.
- 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
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/'));
});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/'));
});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/'));
});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.
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/'));
});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
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); // -> abcYou 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/'));
});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);
}
});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);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);
}
});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');GulpText simple is published under MIT license.