merge

Combine two values. shallow replaces one level of an object; deep recurses into objects.

Naming convention: import the module under its bare name (import "merge"), reach members with a backslash, and call methods in camelCase: merge\someMethod.

Methods

shallow

Return a new value with overlay applied one level deep. When both are objects, overlay's keys replace base's and nested objects are replaced whole, so a sibling key inside a nested object is dropped. Any other overlay replaces base entirely. Neither input is modified.

Signature: merge\shallow(base, overlay) -> any - source

Returns: any

Example:

import "std";
import "encoding/json";
import "merge";

final base = { "name": "api", "port": 8080 };
final overlay = { "port": 9090 };
std\print(json\stringify(merge\shallow(base, overlay: overlay)) catch "");
// -> {"name":"api","port":9090}

deep

Return a new value with overlay applied through every nested object. Objects merge key by key; an array, a scalar, or null in overlay replaces the base value at that key, because a managed list is already the whole list. Neither input is modified.

Signature: merge\deep(base, overlay) -> any - source

Returns: any

Example:

import "std";
import "encoding/json";
import "merge";

// "after" is a sibling of the key overlay patches, so it survives.
// "before" is an array, so overlay replaces it instead of appending.
final base = { "kept": true, "hooks": { "before": ["old"], "after": ["theirs"] } };
final overlay = { "hooks": { "before": ["magus"] } };
std\print(json\stringify(merge\deep(base, overlay: overlay)) catch "");

json

Deep-merge two JSON documents and return the indented text, with a trailing newline. Integers keep the digits that were in the text, which merge\deep cannot promise once a number has been a Buzz value. Objects merge key by key; arrays and other values are replaced by overlay. Object keys are emitted sorted, so the result does not keep base's key order.

Signature: merge\json(base, overlay) -> string - source

Returns: string

Example:

import "std";
import "merge";

// The integer is past 2^53. Merging the text keeps those digits;
// parsing both sides to values first would not.
final base = "\{\"large\": 9007199254740993, \"hooks\": \{\"after\": [\"theirs\"]\}\}";
final overlay = "\{\"hooks\": \{\"before\": [\"magus\"]\}\}";
std\print(merge\json(base, overlay: overlay) catch "");