# grunt-update-json [![Travis Build Status](http://img.shields.io/travis/AndreasPizsa/grunt-update-json.svg?style=flat-square)](http://travis-ci.org/AndreasPizsa/grunt-update-json) ![npm Release](http://img.shields.io/npm/v/grunt-update-json.svg?style=flat-square "npm Release") ![npm License](http://img.shields.io/npm/l/grunt-update-json.svg?style=flat-square "npm License")
Merge parts from one or more JSON files together. I use `grunt-update-json` to keep my `bower.json` and `component.json` in sync with `package.json`.
[![Endorse on Coderwall](http://api.coderwall.com/andreaspizsa/endorsecount.png)](http://coderwall.com/andreaspizsa)
[![Built with Grunt](https://cdn.gruntjs.com/builtwith.png)](http://gruntjs.com/)
## Upgrading from 1.x
The semantics of [Object Groupings](#object-grouping) have been reversed:
- was `{from: "to"}`
- now``{to: "from"}`
## Getting Started
```shell
npm install grunt-update-json --save-dev
```
I highly favor using the fabulous [`load-grunt-tasks`](https://github.com/sindresorhus/load-grunt-tasks) over the tiring and cumbersome `grunt.loadNpmTasks`. Your grunt tasks are all in your `package.json`, so let's embrace [DRY](http://en.wikipedia.org/wiki/Don't_repeat_yourself):
```shell
npm install load-grunt-tasks --save-dev
```
```js
// Gruntfile.js
module.exports = function (grunt) {
require('load-grunt-tasks')(grunt); // load all grunt tasks. Done!
```
## Using the `update_json` task
In your awesome project's Gruntfile, add a section named `update_json`:
```js
// Gruntfile.js
grunt.initConfig({
update_json: {
// set some task-level options
options: {
src: 'package.json',
indent: '\t'
},
// update bower.json with data from package.json
bower: {
src: 'package.json', // where to read from
dest: 'bower.json', // where to write to
// the fields to update, as a String Grouping
fields: 'name version description repository'
},
// update component.json with data from package.json
// component.json fields are a named a bit differently from
// package.json, so let's tell update_json how to map names
component: {
// reuse the task-level `src`
dest: 'component.json', // where to write to
fields: { // the fields to update
// notice how this time we're passing a hash instead
// of an array; this allows us to map the field names.
// We still specify all the names we want, and additionally
// we also specify the target name in the detination file.
// to from
// ----------- -------------------
'name' : null, // null means 'leave as is'
'description' : 'description',// but feel free to type the field name twice
'repository' : 'repo', // rename 'repository' to 'repo'
'version' : null,
'keywords' : null,
'main' : null,
'dependencies' : null,
'development' : 'devDependencies',
'license' : null,
}
},
// `composer` has the same data as `package`, but has some tricky
// semantics
composer: {
// again, reuse the task-level `src`
dest: 'composer.json',
// the fields in an Array Grouping with some embedded Object Groupings
fields: [
{
name: function(src){
return src.repository.url.match(/([^\/]+\/[^\/]+).git/)[1];
}
},
'description',
'keywords',
'homepage',
{
license: 'licenses/0/type',
authors: [{
name: 'author/name',
homepage: 'author/url'
}]
}
]
}
}
});
```
## API
### `options`
Like most Grunt tasks, options can be specified at the `update_json` level
and/or at the `update_json:<target>` level. Target-level `options` override task-level `options`.
#### `options.indent`
By default, output will not be pretty-printed. Specify a value here to have
indentation applied:
```js
update_json: {options: {indent: "\t"}}
```
or for spaces:
```js
update_json: {options: {indent: " "}}
```
### Source Data
> `src`
>
> An input JSON file. May be a list, which will be [`_.merge`d][_merge] together.
[_merge]: http://lodash.com/docs#merge
### Destination Data
> `dest`
>
> An output JSON file.
### Field Groupings
> `fields`
>
> an ordered collection of [_field specifications_](#field-specifications), which
> can optionally contain additional lists of fields.
#### Object Grouping
> `{fields: {field: null, another: "yetanother"}}`
>
> A list of field specs, pointing at any other kind of field specification.
#### Array Grouping
> `{fields: ["field", "another", "still another > yet another"]}`
>
> Create [field copies](#field-copy), or [field renames](#field-rename), of
> each of the listed fields.
#### String Grouping
> `{fields: "field, another, still another > yetanother"}`
>
> Create [field copies](#field-copy), or [field renames](#field-rename), of
> each of the listed fields.
The most concise way to copy/rename a number of fields of simple JSON documents
##### Limitations
- Can't handle fields with `,` or `>` in their names.
- Can't handle most complex [field paths](#field-path).
### Field Specifications
The canonical Object Grouping format is used here: some specifications are not
compatible with some Groupings.
#### Field Copy
> `{field: null}`
>
> Create or replace `field` in `dest` from the value of `field` in `src`.
#### Field Rename
> `{renamed: "original"}` or
> `"original > renamed"` _[String Grouping](#string-grouping) only_
>
> Create or replace `renamed` in `dest` with the value of `original` from `src`.
#### Field Pointer
> `{field: "/some/deep/field"}`
>
> Create or replace `field` in `dest` from `some/deep/field` in `src`.
A field spec destination which starts with `/` will be interepreted as a
[json-pointer](https://github.com/manuelstofer/json-pointer).
To select a field that begins with a literal `/`, escape with a single `\`
(written `\\`):
`{field: "\\/a"}`
### Field Path
> `{field: "$.some.path[(@.with='filters')]"}`
>
> Create or replace `field` in `dest` with the value of nodes found with a
> JSONPath query
A field spec destination which starts with `$.` will be interpreted as a
[JSONPath](https://github.com/s3u/JSONPath) selector.
To select a field that begins with a literal `$.`, escape with a single `\`
(written `\\`):
`{field: "\\$.a"}`
#### Field Collapse
> `{field: ["first", "second"]}`
>
> Create or replace an array named `field` in `dest` with the values of `first`
> and `second` from `src`.
#### Field Construct
> `{field: {first: "first", second: "second"}}`
>
> Create or merge an object `field` in `dest` with labeled `first` and
> `second` with their respective values from `src`
#### Field Function
> `{field: function(src){ return src.field; }}`
>
> Create a field named `field` that is the output of running a function against
> `src`.
If all else fails, you can supply a function which will called with a copy of
the combined source object.
```js
update_json: {
composer: {
src: "package.json",
dest: "composer.json",
fields: {
name: function(src){
// pull username/repo off a github url
return src.repository.url.match(/([^\/]+\/[^\/]+).git/)[1];
}
}
}
}
```
## Ideas for improvement
- see [enhancements](https://github.com/AndreasPizsa/grunt-update-json/issues?labels=enhancement&page=1&state=open)
## License
MIT
[![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/AndreasPizsa/grunt-update-json/trend.png)](https://bitdeli.com/free "Bitdeli Badge")