gulp-transform
Version:
A Gulp plugin for applying custom transformations to the contents of files
274 lines (230 loc) • 7.76 kB
Markdown
# gulp-transform
[![version][versionBadge]][npm]
[![build][buildBadge]][build]
[![coverage][coverageBadge]][coverage]
[![dependencies][dependenciesBadge]][dependencies]
A [Gulp][gulp] plugin for applying custom transformations to the contents of
files.
## Install
Install via [npm][npm]:
```sh
npm install --save-dev gulp gulp-transform
```
## Usage
### Synchronous usage
This example adds a timestamp to the beginning of each source file. The comment
format is inferred from the file extension. Files with unrecognized extensions
are not modified.
#### gulpfile.js
```js
const gulp = require('gulp');
const transform = require('gulp-transform');
const path = require('path');
const TIMESTAMP = Date();
gulp.task('timestamp', () => {
return gulp.src('src/**/*')
.pipe(transform('utf8', timestamp))
.pipe(gulp.dest('out'));
});
function timestamp(content, file) {
switch (path.extname(file.path)) {
case '.js':
case '.ts':
return `// ${TIMESTAMP}\n\n${content}`;
case '.coffee':
return `# ${TIMESTAMP}\n\n${content}`;
default:
return content;
}
}
```
#### src/hello.js
```js
console.log('Hello, world.');
```
#### out/hello.js
```js
// Thu Jul 27 2017 15:56:14 GMT-0700 (PDT)
console.log('Hello, world.');
```
### Asynchronous usage
This example uses [xml2js][xml2js] to convert XML to JSON. The callback
returns a [Promise][promise] since the operation is asynchronous.
#### gulpfile.js
```js
const gulp = require('gulp');
const transform = require('gulp-transform');
const rename = require('gulp-rename');
const xml2js = require('xml2js');
gulp.task('xml-to-json', () => {
return gulp.src('src/**/*.xml')
.pipe(transform('utf8', xmlToJson))
.pipe(rename({ extname: '.json' }))
.pipe(gulp.dest('out'));
});
function xmlToJson(content) {
return new Promise((resolve, reject) => {
xml2js.parseString(content, (error, data) => {
if (error) {
reject(error);
} else {
resolve(JSON.stringify(data, null, 2));
}
});
});
}
```
#### src/cities.xml
```xml
<cities>
<city>Amsterdam</city>
<city>Rotterdam</city>
<city>The Hague</city>
</cities>
```
#### out/cities.json
```json
{
"cities": {
"city": [
"Amsterdam",
"Rotterdam",
"The Hague"
]
}
}
```
## API
### transform([options], callback)
Creates a stream that transforms the contents of [File][vinylFile] objects.
Files in both streaming and buffer mode are accepted.
To transform contents as a string, a [character encoding][encoding] must be
specified; otherwise, contents will be passed to the callback as a
[Buffer][nodeBuffer].
The contents of each File are replaced with the return value of the callback.
Or, to perform an asynchronous transformation, a [Promise][promise] may be
returned.
<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">
<strong>[options]</strong>
</td>
<td align="center">
<p><code>object</code></p>
<p><code>string</code></p>
<p><code>null</code></p>
</td>
<td align="left">
<p>
An optional options object or a value indicating an encoding. If
passed as an object, the following properties are are accepted as
options:
</p>
<ul>
<li>
<strong>encoding</strong> - <code>string</code> | <code>null</code> - An
<a href="https://nodejs.org/dist/latest/docs/api/buffer.html#buffer_buffers_and_character_encodings">
encoding</a> supported by Node.js or <code>null</code> to indicate
no encoding. Defaults to <code>null</code>.
</li>
<li>
<strong>thisArg</strong> - <code>any</code> - The value of
<code>this</code> within <em>callback</em>. Defaults to
<code>undefined</code>.
</li>
</ul>
<p>
If passed as a string or <code>null</code>, it is interpreted as the
<em>encoding</em> option.
</p>
<p>
If no encoding is given, <em>callback</em> is called with a
<code>Buffer</code> object containing the contents of the file.
Otherwise, it is called with a string created with
<a href="https://nodejs.org/dist/latest/docs/api/buffer.html#buffer_buf_tostring_encoding_start_end">
<code><em>buffer</em>.toString(<em>encoding</em>)</code></a>.
</p>
</td>
</tr>
<tr>
<td align="left">
<strong>callback</strong>
</td>
<td align="center">
<code>function</code>
</td>
<td align="left">
<p>
A function that transforms the contents of each file. It is invoked
with two arguments:
</p>
<ul>
<li>
<strong>contents</strong> - <code>Buffer</code> | <code>string</code> - The
contents of the file. If no encoding is given, <em>contents</em>
will be a <code>Buffer</code>; otherwise, it will be a string.
</li>
<li>
<strong>file</strong> - <code>File</code> - The
<a href="https://github.com/gulpjs/vinyl#instance-methods">
<code>File</code></a> object whose contents are being transformed.
Use this to access metadata about the file, e.g., its filename.
</li>
</ul>
<p>
The contents of the file are replaced with the return value of the
callback. For asynchronous transformations, a
<a href="https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise">
<code>Promise</code></a> may be returned. The return or completion
value must have the same type as <em>contents</em>.
</p>
<p>
The value of <code>this</code> within the callback may be set with the
<em>thisArg</em> option; otherwise, <code>this</code> will be
<code>undefined</code>.
</p>
</td>
</tr>
</tbody>
</table>
## TypeScript
[TypeScript][typescript] declarations are included in the package.
```sh
npm i -D typescript ts-node gulp @types/gulp gulp-transform
```
#### gulpfile.ts
```ts
import gulp = require("gulp");
import transform = require("gulp-transform");
gulp.task("build", () => {
gulp.src("src/**/*")
.pipe(transform("utf8", () => { /* transform contents */ }))
.pipe(gulp.dest("out"));
});
```
## License
Copyright © 2016–2017 Akim McMath. Licensed under the [MIT License][license].
[gulp]: http://gulpjs.com/
[npm]: https://npmjs.org/package/gulp-transform
[versionBadge]: https://img.shields.io/npm/v/gulp-transform.svg?style=flat-square
[license]: LICENSE
[buildBadge]: https://img.shields.io/travis/mcmath/gulp-transform/master.svg?style=flat-square
[build]: https://travis-ci.org/mcmath/gulp-transform
[coverageBadge]: https://img.shields.io/coveralls/mcmath/gulp-transform/master.svg?style=flat-square&service=github
[coverage]: https://coveralls.io/github/mcmath/gulp-transform?branch=master
[dependenciesBadge]: https://img.shields.io/gemnasium/mcmath/gulp-transform.svg?style=flat-square
[dependencies]: https://gemnasium.com/mcmath/gulp-transform
[xml2js]: https://github.com/Leonidas-from-XIV/node-xml2js
[vinylFile]: https://github.com/gulpjs/vinyl#instance-methods
[encoding]: https://nodejs.org/dist/latest/docs/api/buffer.html#buffer_buffers_and_character_encodings
[nodeBuffer]: https://nodejs.org/dist/latest-v8.x/docs/api/buffer.html
[promise]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise
[typescript]: https://www.typescriptlang.org/