grunt-flatten-json v0.0.5
grunt-flatten-json
Flatten one or more JSON files into a single-level file
Getting Started
This plugin requires Grunt >=0.4.0
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-flatten-json --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-flatten-json');
This plugin was designed to work with Grunt 0.4.x. If you're still using grunt v0.3.x it's strongly recommended that you upgrade, but in case you can't please use v0.3.2.
Flatten JSON Task
Run this task with the grunt flatten_json
command.
This task will combine one or more JSON files and flatten them into a single-level key.
Therefore, given the following JSON file:
{
"key1":
{
"subkey1": "sub key 1 value",
"subkey2": "sub key 2 value"
},
"key2":
{
"subkey1": "sub key 1 value",
"subkey2":
{
"subsubkey1": "sub sub key 1 value"
}
}
}
The following flattened JSON file will be created:
{
"key1.subkey1": "sub key 1 value",
"key1.subkey2": "sub key 2 value"
"key2.subkey1": "sub key 1 value",
"key2.subkey2.subsubkey1": "sub sub key 1 value"
}
This task was inspired by the need to make managing JSON-based translation files.
Task targets, files and options may be specified according to the grunt Configuring tasks guide.
Options
encoding
Type: String
Default: grunt.file.defaultEncoding
The file encoding to read and write the JSON files with.
separator
Type: String
Default: .
The flattening key separator to use.
baseKey
Type: String
Default: null
A base key to use as a prefix to all flattened keys.
keyFilter
Type: String
| Array
| function(keyContext, key)
Default: null
Either a specific key name, an array of key names or a function to exclude keys and their children from the flattened JSON results.
valueFilter
Type: function(value)
Default: null
A function that filters all values processed during flattening and allows for re-writing.
Usage Examples
Generate multiple flattened JSON files
The following example demonstrates how to generate multiple flattened JSON files from sets of one or more JSON files.
flatten_json: {
main: {
files: [
// flattens all JSON files directly under path that end in '_en_CA.json'
// to a file under dest called messages_en_CA.json
{expand: true, src: ['path/*_en_CA.json'], dest: 'dest/messages_en_CA.json'},
// flattens all JSON files under path that end in '_fr_CA.json'
// to a file under dest called messages_fr_CA.json
{expand: true, src: ['path/**/*_fr_CA.json'], dest: 'dest/messages_fr_CA.json'}
],
},
},
Specify a different key separator
The following example demonstrates how to generate a single flattened JSON file with a key separator of :
.
flatten_json: {
main: {
options: {
separator: ':'
},
src: ['path/*.json'],
dest: 'dest/messages.json'}
},
},
The results of the might be something like the following:
{
"key1:subkey1": "sub key 1 value",
"key1:subkey2": "sub key 2 value"
}
Specify a base key
The following example demonstrates how to generate a single flattened JSON file with a base key.
flatten_json: {
main: {
options: {
baseKey: 'myBase'
},
src: ['path/*.json'],
dest: 'dest/messages.json'}
},
},
The results of the might be something like the following:
{
"myBase.key1.subkey1": "sub key 1 value",
"myBase.key1.subkey2": "sub key 2 value"
}
Exclude keys
Given the following JSON file:
{
"key1":
{
"key1": "value 1",
"key2": "value 2"
},
"key2":
{
"key1": "value 1",
"key2": "value 2"
},
"key3":
{
"key1": "value 1",
"key2": "value 2"
}
}
The following example demonstrates excluding all keys of a specific string:
flatten_json: {
main: {
options: {
keyFilter: 'key2'
},
src: ['path/*.json'],
dest: 'dest/messages.json'}
},
},
Would produce the following result:
{
"key1.key1": "value 1",
"key3.key1": "value 1",
}
The following example demonstrates excluding all keys of an array of keys:
flatten_json: {
main: {
options: {
keyFilter: ['key2', 'key3']
},
src: ['path/*.json'],
dest: 'dest/messages.json'}
},
},
Would produce the following result:
{
"key1.key1": "value 1"
}
The following example demonstrates using a function to exclude keys:
flatten_json: {
main: {
options: {
keyFilter: function(keyContext, key) {
return /key3$/.test(keyContext) && key == 'key1';
}
},
src: ['path/*.json'],
dest: 'dest/messages.json'}
},
},
Would produce the following result:
{
"key1.key1": "value 1",
"key1.key2": "value 2",
"key2.key1": "value 1",
"key2.key2": "value 2",
"key3.key2": "value 2"
}
Re-write values
The following example demonstrates using a function to re-write the values during flattening:
flatten_json: {
main: {
options: {
valueFilter: function (value) {
return value.replace(/\{([a-zA-Z0-9.]+)\}/gi,
function (match, v) {
return '{{' + v + '}}';
});
}
},
src: ['path/*.json'],
dest: 'dest/messages.json'}
},
},
Which would convert value like This is a {placeholder} value
to This is a {{placeholder}} value
.