lycwed-gulp-xml-transformer

Transform xml documents gulp plugin

Install

$ npm install --save-dev lycwed-gulp-xml-transformer

Supports node >= 0.10

Usage

var xmlTransformer = require("lycwed-gulp-xml-transformer");

/*
 * edit XML document by using user specific object
 */
gulp.src("./manifest.xml")
  .pipe(xmlTransformer([
    { path: '//name', text: 'new names' },
    { path: '//version', attr: { 'major': '2' } }
  ]))
  .pipe(gulp.dest("./dest"));

/*
 * attributes can be functions too
 */
gulp.src("./manifest.xml")
  .pipe(xmlTransformer([
    { path: '//version', attr: { 'major': val => parseInt(val, 10) + 1 } }
  ])
  .pipe(gulp.dest("./dest"));

/*
 * edit XML document by using user specific object using a namespace
 */
gulp.src("./manifest.xml")
  .pipe(xmlTransformer([
    { path: '//xmlns:name', text: 'new names' },
    { path: '//xmlns:version', attr: { 'major': '2' } }
  ], 'http://www.w3.org/ns/widgets'))
  .pipe(gulp.dest("./dest"));

/*
 * edit XML document by using user specific object using a custom namespace
 */
gulp.src("./manifest.xml")
  .pipe(xmlTransformer([
    { path: '//a:name', text: 'new names' },
    { path: '//a:version', attr: { 'major': '2' } }
  ], { a: 'http://www.w3.org/ns/widgets' }))
  .pipe(gulp.dest("./dest"));

/*
 * edit XML document by target same paths' name
 * 
    ...
    <preference name="webviewbounce" value=""/> // edit only this one
    <preference name="UIWebViewBounce" value="false"/>
    <preference name="DisallowOverscroll" value=""/> // and this one !
    ...
 */
gulp.src("./manifest.xml")
  .pipe(xmlTransformer([
    { path: '//xmlns:preference', index: 0, attr: { 'value': false } },
    { path: '//xmlns:preference', index: 2, attr: { 'value': true } }
  ], 'http://www.w3.org/ns/widgets'))
  .pipe(gulp.dest("./dest"));

/*
 * edit XML document by using user specific function
 */
gulp.src("./manifest.xml")
  .pipe(xmlTransformer((xml, libxmljs) => {
    // 'xml' is libxmljs Document object.
    xml.get('//key[./text()="Version"]').nextElement().text('2.0.0');

    // 'libxmljs' is libxmljs object. you can call any libxmljs function.
    var child = new libxmljs.Element(xml, 'note');
    child.text('some text');
    xml.get('//description').addChild(child);

    // must return libxmljs Document object.
    return xml;
  }))
  .pipe(gulp.dest("./dest"));

Note

Please see libxmljs wiki page to get more information about libxmljs API.

Based on gulp-xml-editor.

API

xmlTransformer(transformations, nsUri)

transformations

Type: Object | Array<Object> | Function

The objects must be one of following.

// to modify(or add) the text of the element
{ path: 'xpath to the element', text: 'new text value' }

// to modify(or add) a attribute of the element
{ path: 'xpath to the element', attr: { 'attrName': 'attrValue' } }

// to modify(or add) some attributes of the element
{
  path: 'xpath to the element',
  attrs: [
    { 'attrName1': 'attrValue1' },
    { 'attrName2': 'attrValue2' }
  ]
}

// alternatively
{
  path: 'xpath to the element',
  attrs: {
    'attrName1': 'attrValue1',
    'attrName2': 'attrValue2',
  }
}

// if the new value of the attribute depends on the old value, pass in a function
{
  path: 'xpath to the element',
  attrs: {
    'foo': oldVal => oldVal.replace('bar', 'baz'),
  }
}

The if a function is supplied, it must have the following signature: function (doc, [libxmljs]) {}, and must return a libxmljs Document object. The doc argument is a libxmljs Document object, and the libxmljs argument is libxmljs object.

nsUri

Type: Object | string

A string representing the Namespace URI of the elements to transform, or an object literal with namespaces.

License

See the LICENSE file for license rights and limitations (MIT).