https://github.com/mcmath/gulp-transform

Gulp plugin for performing arbitrary transformations on the contents of files.
https://github.com/mcmath/gulp-transform

Last synced: 11 months ago
JSON representation

Gulp plugin for performing arbitrary transformations on the contents of files.

Host: GitHub
URL: https://github.com/mcmath/gulp-transform
Owner: mcmath
License: mit
Created: 2016-01-09T07:58:15.000Z (over 10 years ago)
Default Branch: master
Last Pushed: 2022-12-06T17:23:04.000Z (over 3 years ago)
Last Synced: 2025-03-25T12:11:05.105Z (about 1 year ago)
Language: TypeScript
Size: 123 KB
Stars: 9
Watchers: 2
Forks: 6
Open Issues: 3
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

          # 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

  Amsterdam

  Rotterdam

  The Hague

```

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

#### Parameters

  

    

      Name

      Type

      Description

    

  

  

    

      

        [options]

      

      

        
object

        string

        null

      

      

        

          An optional options object or a value indicating an encoding. If

          passed as an object, the following properties are are accepted as

          options:

        

        

          

            encoding - string | null - An

            

            encoding supported by Node.js or null to indicate

            no encoding. Defaults to null.

          

          

            thisArg - any - The value of

            this within callback. Defaults to

            undefined.

          

        

        

          If passed as a string or null, it is interpreted as the

          encoding option.

        

        

          If no encoding is given, callback is called with a

          Buffer object containing the contents of the file.

          Otherwise, it is called with a string created with

          

          buffer.toString(encoding).

        

      

    

    

      

        callback

      

      

        function

      

      

        

          A function that transforms the contents of each file. It is invoked

          with two arguments:

        

        

          

            contents - Buffer | string - The

            contents of the file. If no encoding is given, contents

            will be a Buffer; otherwise, it will be a string.

          

          

            file - File - The

            

            File object whose contents are being transformed.

            Use this to access metadata about the file, e.g., its filename.

          

        

        

          The contents of the file are replaced with the return value of the

          callback. For asynchronous transformations, a

          

          Promise may be returned. The return or completion

          value must have the same type as contents.

        

        

          The value of this within the callback may be set with the

          thisArg option; otherwise, this will be

          undefined.

        

      

    

  

## 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/

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/mcmath/gulp-transform

Awesome Lists containing this project

README