gulp-text-simple
v0.6.0
Published
simple creation of Gulp transformations for text files
Downloads
1,918
Readme
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.