grunt-jsonfile

use objects or json files as template, to create, modify and distribute jsonfiles.


When running a complex make for various environments, types like [test|production]
and/or os targets, json configuration files might be required, which differ in
specific properties.

grunt-jsonfile offers the opportunity to:

* provide json templates
* customize templates by merging in values
* customize templates by removing values
* customize templates by updating values
* write modified templates to json files into custom (build) directories
* use project package.json files as templates

content ##

* Usage (see further down this page)
* Getting started guide
* Usage and examples

* Developers
* Testing grunt-jsonfile
* Code coverage of tests for grunt-jsonfile
* Build grunt-jsonfile from scratch
* NPM integration of grunt-jsonfile
* Frameworks used for testing, building, etc.
* API of package grunt-jsonfile

Changelog

getting started ##

This guide assumes, that you are familiar with the use of npm and grunt.
The plugin can be installed by the following command:

npm install grunt-jsonfiles --save-dev

Do note forget to install the peer dependencies.
Once installed, the plugin may be loaded from within your gruntfile:

grunt.loadNpmTasks( "jsonfiles" );

Setup the task configuration as described below (see usage) and run the task:

grunt jsonfiles

Of cause, the task can be integrated into any complex build process.

usage ##

$3

If option.EOF is truthy, jsonfiles will close with an operating system specifc
EOL (end of line)

``javascript

const jsonfile = {
options: {
EOF: true
}
};
`

$3

The following example defines two templates in the options section of 'jsonfile'.

`javascript
// Templates are identified by name. This example defines two templates, which
// can be referenced by "tmpl1" and "tmpl2"

const jsonfile = {
options:{
templates: {
tmpl1: "config/template.json", // strings will be interpreted as path to
// json files, which will be required and
// used as template.
tmpl2: { // objects will directly be used as
pname1: 5, // template
pname2: true,
pname3: "value",
aproperty: "a aproperty will be deleted"
}
}
}
};
`

The following examples define templates directly within their targets.

`javascript
const BUILD = "...some path";
const jsonfile = {
target1: {
template: "config/template.json", // template is a string value, and does not
// reference a template in options.templates.
// Therefor it will be interpreted as path to
// a json file, which will be required.
dest: ${ BUILD }/file.json, // write the result to this file.
}
};
`

`javascript
const BUILD = "...some path";
const jsonfile = {
target1: {
template: { // a template object
pname1: 5,
pname2: true,
pname3: "value",
aproperty: "a aproperty will be deleted"
},
dest: ${ BUILD }/file.json, // write the result to this file.
}
};
`

$3

`javascript
// Target 'target1' references a template in options.templates

const BUILD = "...some path";
const jsonfile = {
options:{
templates: {
tmpl1: "config/template.json" // read the json file and use the resulting
// object as template.
}
},
target1: {
template: "tmpl1", // template is a string value, and references
// a template in options.templates which will
// be used.
dest: [ // write the result to all files in this array
${ BUILD }/1/file.json,
${ BUILD }/2/file.json,
${ BUILD }/3/file.json
]
}
};
`

$3

Setting a value to a property of a template can mean:
* creating a template property if it did not yet exist
* overwriting the value of an existing template property

`javascript
const BUILD = "...some path";
const jsonfile = {
target1: {
template: { // a template object
pname1: 5,
pname2: true,
pname3: { key: "value" },
aproperty: "a aproperty will be deleted"
},
dest: ${ BUILD }/file.json, // write the result to this file.
set: {
pname1: "value 5 replaced", // this will set template.pname1 to
// "value 5 replaced"
pname2: undefined, // this will set template.pname2 to
// undefined
pname3: { other: "instance" }, // this will set template.pname3 to
// another instance.
aproperty: null // this will set template.aproperty to
// null
}
};
`

$3

Merging properties into templates means
* inserting properties which did not yet exist
* setting values to properties that do exist
* deleting templates properties if value to merge is null
* mering will iterate into object trees

`javascript
const BUILD = "...some path";
const jsonfile = {
target1: {
template: { // a template object
pname1: 5,
pname2: true,
pname3: { key: "value" },
aproperty: "a aproperty will be deleted"
},
dest: ${ BUILD }/file.json, // write the result to this file.
merge: {
pname3: { key: { test: "fun" }}, // this will replace value by { test: "fun" }
aproperty: undefined // this will remove aproperty from template
}
}
}

`

$3

Updating template properties means
* setting a value to a template property that exists
* ignoring properties that do not exist in the template

`javascript
const BUILD = "...some path";
const jsonfile = {
target1: {
template: { // a template object
pname1: 5,
pname2: true,
pname3: { key: "value" },
aproperty: "a aproperty will be deleted"
},
dest: ${ BUILD }/file.json, // write the result to this file.
update: {
pname1: "fun", // will set template.pname1 to "fun"
xproperty: "uups" // will change nothing, because there is
// no xproperty in template.
}
}
}
``