grunt-xmlpoke

Updates values in XML files based on XPath queries

npm install grunt-xmlpoke
10 downloads in the last day
41 downloads in the last week
395 downloads in the last month

grunt-xmlpoke

Updates values in XML files based on XPath queries. Similar to the xmlpoke task in NAnt.

Getting Started

This plugin requires Grunt ~0.4.2

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-xmlpoke --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-xmlpoke');

The "xmlpoke" task

Overview

In your project's Gruntfile, add a section named xmlpoke to the data object passed into grunt.initConfig().

grunt.initConfig({
  xmlpoke: {
    options: {
      xpath: '//title',
      value: 'The Good Parts'
    },
    files: {
      'dest.xml': 'src.xml'
    },
  },
})

Options

options.xpath

Type: String Default value: ''

An xpath query to select one or more nodes in the source document.

options.value

Type: String or Function Default value: ''

A string value to which the value of any matched node is set.

You can also supply a function that returns the replacement value. The first argument supplied to the function will be the node on which the replacement is being made.

options.replacements

Type: Array Default value: undefined

An array of replacement options (i.e. objects with xpath and value properties)

Usage Examples

Basic Usage

In this example, the text content of an element is set to a static value. So if the testing.xml file has the content <abc></abd>, the generated result would be <abc>123</abc>.

grunt.initConfig({
  xmlpoke: {
    options: {
      xpath: '/abc',
      value: '123'
    },
    files: {
      'dest/basic_usage.xml': 'src/testing.xml',
    },
  },
})

Attribute Example

In this example, the value of an attribute is cleared. So if the testing.xml file has the content <x y="999" />, the generated result in this case would be <x y="" />.

grunt.initConfig({
  xmlpoke: {
    options: {
      xpath: '/x/@y',
      value: ''
    },
    files: {
      'dest/attribute_example.xml': 'src/testing.xml',
    },
  },
})

Function Example

In this example, the value of an attribute is modified. So if the testing.xml file has the content <x y="abc" />, the generated result in this case would be <x y="ABC" />.

grunt.initConfig({
  xmlpoke: {
    options: {
      xpath: '/x/@y',
      value: function (node) { return node.value.toUpperCase(); }
    },
    files: {
      'dest/function_example.xml': 'src/testing.xml',
    },
  },
})

Multiple XPath Queries

In this example, the same value is put intp multiple locations. So if the testing.xml file has the content <x y="999" />, the generated result in this case would be <x y="111">111</x>.

grunt.initConfig({
  xmlpoke: {
    options: {
      xpath: ['/x/@y','/x'],
      value: '111'
    },
    files: {
      'dest/multiple_xpath_queries.xml': 'src/testing.xml',
    },
  },
})

Multiple Replacements

In this example, multiple replacements take place at once. So if the testing.xml file has the content <x y="999" />, the generated result in this case would be <x y="111">M</x>.

grunt.initConfig({
  xmlpoke: {
    options: {
      replacements: [{
        xpath: '/x/@y',
        value: '111'
      }, {
        xpath: '/x',
        value: 'M'
      }]
    },
    files: {
      'dest/multiple_replacements.xml': 'src/testing.xml',
    },
  },
})

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

  • 0.1.0 — Initial release
  • 0.2.0 — Multiple replacements at once
  • 0.2.1 — Color filename when logged
  • 0.3.0 — Allow specifying replacement value as a function
npm loves you