grunt-update-json  !npm Release !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.


Upgrading from 1.x

The semantics of Object Groupings 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 over the tiring and cumbersome grunt.loadNpmTasks. Your grunt tasks are all in your package.json, so let's embrace DRY:

`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

$3

Like most Grunt tasks, options can be specified at the update_json level
and/or at the update_json: 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: " "}}
`

$3


> src
>
> An input JSON file. May be a list, which will be [_.merged][_merge] together.
[_merge]: http://lodash.com/docs#merge

$3

> dest
>
> An output JSON file.

$3

> fields
>
> an ordered collection of _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, or field renames, of
> each of the listed fields.


#### String Grouping
> {fields: "field, another, still another > yetanother"}
>
> Create field copies, or field renames, 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.




$3

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

To select a field that begins with a literal /, escape with a single \
(written \\):

{field: "\\/a"}




$3


> {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 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

License

MIT