Table of Contents:

• .fromFile('file.json')
• .fromObject(object)
• config
  • asText
  • javascript
  • scope
  • variables
• @extends
• Indicators
  • @extends
  • @override
  • @append, @prepend, @insert
  • @match
  • @move
  • @value
  • @comment
  • @id
• .merge(objA, objB)
• Command line interface json_merger
• Expiremental usage
• Root indicators
• License

Apply indicators such as @insert, @match and @override to tell the processor how to merge the files.

.fromFile('file.json')

var json_merger = require('json_merger');
var result = json_merger.fromFile('fileA.json');

fileA.json:

{
	"@extends": "fileB.json",
	"prop1": {
		"@override": true,
		"prop_a": "this will override fileB.json's property prop1"
	},
	"prop2": {
		"prop_a": "some value"
	}
}

fileB.json:

{
	"prop1": {
		"prop_b": "never gonna be seen"
	},
	"prop2": {
		"prop_b": "some other value"
	}
}

Result:

{
	"prop1": {
		"prop_a": "this will override fileB.json's property prop1"
	},
	"prop2": {
		"prop_a": "some value",
		"prop_b": "some other value"
	}
}

.fromObject(object)

var json_merger = require('json_merger');

var objA = {
	"@extends": "fileB.json",
		"prop1": {
			"@override": true,
			"prop_a": "this will override fileB.json's property prop1"
	},
		"prop2": {
		"prop_a": "some value"
	}
};

var result = json_merger.fromObject(objA);

fileB.json:

{
	"prop1": {
		"prop_b": "never gonna be seen"
	},
	"prop2": {
		"prop_b": "some other value"
	}
}

Result:

{
	"prop1": {
		"prop_a": "this will override fileB.json's property prop1"
	},
	"prop2": {
		"prop_a": "some value",
		"prop_b": "some other value"
	}
}

config

{
    asText: false, // true, false, 'pretty'
    javascript: false, // true, false
    scope: '', // directory to look for initial file
    variables: {
        // contains a key->value object with variables to @extends
    }
}

config.asText

default: false (in command line interface it will default to true)

Values are true, false, pretty where pretty will indent the JSON with \t for each block.

config.javascript

Expiremental

default: false

Preserve JavaScript functions, regexp, etc see Expiremental usage

config.scope

default: process.cwd()

The initial directory which the inputFile is relative too, will be overridden for each @extends file and is set to dirname of current inputFile.

config.variables

default: {}

Variables is used in @extends like the following:

json_merger.fromFile('fileA.json', {
    "project_root": "/var/www/project123"
});

fileA.json

{
    "@extends": ["${project_root}/fileB.json"]
}

Indicators:

@extends

An array / string indicating which files a given object extends, this is a root indicator

{
    "@extends": ["main_file.json", "project_file.js", "mixin_file.json"]
}

@override

An array or true indicating that the given property will be overridden. When used with true the whole property will be overridden. When used with an array the listed properties will be overridden:

Usage of true

{
	"@extends": ["b.json"],
	"a": {
		"@override": true,
		"prop_1": {"a":1},
		"prop_2": {"a":2}
	}
}

b.json

{
	"a": {
		"prop_1": {"b":1},
		"prop_2": {"b":2},
		"prop_3": {"b":3},
		"prop_4": {"b":4}
	}
}

Result

{
	"a": {
		"prop_1": {"a":1},
		"prop_2": {"a":2}
	}
}

Usage of array

{
	"@extends": ["b.json"],
	"a": {
		"@override": ["prop_1"],
		"prop_1": {"a":1},
		"prop_2": {"a":2}
	}
}

b.json

{
	"a": {
		"prop_1": {"b":1},
		"prop_2": {"b":2},
		"prop_3": {"b":3},
		"prop_4": {"b":4}
	}
}

Result

{
	"a": {
		"prop_1": {"a":1},
		"prop_2": {"a":2, "b":2},
		"prop_3": {"b":3},
		"prop_4": {"b":4}
	}
}

@append, @prepend, @insert

When working with array the default behaviour will be to merge on indexes, eg first item in the arrays will be merged together etc.

• @append: true is alias for @insert: -1
• @prepend: true is alias for @insert: 0

Using @insert:

{
	"@extends": ["b.json"],
	"a": [
		{
			"@insert": 1,
			"a": 1
		}
	]
}

b.json

{
	"a": [
		{
			"b": 1
		},
		{
			"b": 2
		},
		{
			"b": 3
		}
	]
}

Result

{
	"a": [
		{
			"b": 1
		},
		{
			"a": 1
		},
		{
			"b": 2
		},
		{
			"b": 3
		}
	]
}

@match

Match can be used to match a given item in an array; Supported syntax:

[prop1=val1][prop2='val2']

You can ether use prop1, prop2 for matching regular properties @value which will match the value of primitives in the array:

Quoting is optional but required if you want strict comparison, eg [prop='2'] will match {"prop": "2"} and not {"prop": 2}

Usage

{
	"@extends": ["b.json"],
	"columns": [
		{
			"@match": "[name=token]",
			"type": "float"
		}
	]
}

b.json

{
	"columns": [
		{
			"name": "firstname",
			"type": "varchar(64)"
		},
		{
			"name": "lastname",
			"type": "varchar(64)"
		},
		{
			"name": "token",
			"type": "integer"
		}
	]
}

Result

{
	"columns": [
		{
			"name": "firstname",
			"type": "varchar(64)"
		},
		{
			"name": "lastname",
			"type": "varchar(64)"
		},
		{
			"name": "token",
			"type": "float"
		}
	]
}

Advanced usage

{
    "@extends": ["b.json"],
    "outer_array": [
        {
            "@match": "[key=value]/inner_array/[inner_key=inner_value]",
            "type": "float"
        }
    ]
}

b.json

{
    "outer_array": [
        {
            "key": "value",
            "inner_array": [
                {
                    "inner_key": "inner_value"
                }
            ]
        }
    ]
}

Result

{
    "outer_array": [
        {
            "key": "value",
            "inner_array": [
                {
                    "inner_key": "inner_value",
                    "type": "float"
                }
            ]
        }
    ]
}

Advanced Usage 2 (@value)

{
	"@extends": ["b.json"],
	"seq": [
		{
			"@match": "[@value=b]",
			"@delete": true
		}
	]
}

b.json

{
	"seq": [
		"a",
		"b",
		"c",
		"d"
	]
}

Result

{
	"columns": [
		"a",
		"c",
		"d"
	]
}

@move

This indicator is the same as @insert but is used together with @match.

@value

Used when merging arrays containing primitives or other arrays

{
    "@extends": ["fileB.json"],
	"sequence": [
		{
			"@insert": 1,
			"@value": "insertedField"
		}
	]
}

fileB.json

{
	"sequence": [
		"fieldA",
		"fieldB",
		"fieldC"
	]
}

Output

{
	"sequence": [
		"fieldA",
		"insertedField",
		"fieldB",
		"fieldC"
	]
}

@comment

These will be removed in the merging process and is intented to be used for internal comments about overrides etc.

{
    "@comment": "I did this because...."
}

@id

This can be matches in @match using the following syntax:

{
	"@extends": ["b.json"],
    "array": [
		{ "a": 2, "@match": "[@id=my_id]" }
    ]
}

b.json

{
    "array": [
		{ "a": 1 },
		{ "a": 2, "@id": "my_id" }
    ]
}

.merge(objA, objB)

You can use json_merger without having to use JSON stored in files, you can use it directly with JavaScript objects:

var json_merger = require('json_merger');

var a = {
    a: {
        "@override": true,
        "my_value": 1234
    }
};
var b = {
    a: {
        "my_b_value": 1234
    }
}

var result = json_merger.merge(a, b);

console.log(result.a.my_value); // 1234
console.log(result.a.my_b_value); // undefined

Command line interface json_merger

You can use json_merger as a command line tool:

Usage: json_merger <file> [OPTIONS]

Mandatory arguments to long options are mandatory for short options too.

  -p, --pretty            Prettify the output json
  -j, --javascript        Perserve JavaScript functions, regex, etc...
  -v, --variables         Send key=value list of variables
                            Usage -v key1=value1 -v key2=value2

  -h, --help              Show this help
  -v, --version           Show the version

Usage:

json_merger input.json > out.json
json_merger input.json --pretty > out.json
json_merger input.json --javascript > out.json
json_merger input.json -p -j -v "root=/var/www/" > out.json

Make sure that add json_merger to the $PATH variable.

npm install -g json_merger

Experimental Usage:

Working with JavaScript code in JSON Use at own risk :-)

var json_merger = require('json_merger');

var output = json_merger.fromFile('file.jsonx', {
    asText: 'pretty',
    javascript: true
});

file.jsonx

{
    "@extends": ["fileB.jsonx"],
    "my_function": function(a, b) { return doStuff(a, b) },
    "obj": {
        "a": (function(a, b) { /* code here */ })(1, 2)
    }
}

fileB.jsonx

{
    "@extends": ["fileB.jsonx"],
    "obj": {
        "b": (function(a, b) { /* another code here */ })(1, 2)
    }
}

Result:

{
    "my_function": function(a, b) { return doStuff(a, b) },
    "obj": {
        "a": (function(a, b) { /* code here */ })(1, 2),
        "b": (function(a, b) { /* another code here */ })(1, 2)
    }
}

Root indicators

Root indicators is properties that are only supported on the outer most level of the JSON tree.

Current supported root indicators:

• @extends

License:

The MIT License (MIT)

Copyright (c) 2015 Andreas Louv

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

+++++ +++++ +[>+++++ +++++<-]>----.+++++++++.----.-.---------------.++++++++++++++.--------.+++++++++++++.-----------.--.+++++++++++++.