README
¶
deep-merge
A pure-Go (CGO_ENABLED=0, standard library only) port of the Ruby
deep_merge gem: recursive
hash/array merge with the gem's full option set.
It operates on Go values that model Ruby data:
| Ruby | Go |
|---|---|
| Hash | map[string]any |
| Array | []any |
| scalar | any other value |
Install
go get github.com/go-ruby-deep-merge/deep-merge
import deepmerge "github.com/go-ruby-deep-merge/deep-merge"
Usage
dest := map[string]any{"property": []any{"2", "4"}}
source := map[string]any{"property": []any{"1", "3"}}
merged := deepmerge.DeepMerge(dest, source, deepmerge.Options{})
// merged == {"property": ["2", "4", "1", "3"]} (dest ∪ source; dest untouched)
source is merged into dest (equivalent to Ruby deep_merge!(source, dest)):
source values take precedence.
DeepMerge(dest, source, opts)— merges into a deep copy ofdest, returns the copy; the caller'sdestis left untouched.DeepMergeInto(dest, source, opts)— merges intodestin place and returns the result. Always use the return value: the top-level value can be replaced (for example whendestisnilor a scalar).
Options
| Field | deep_merge option | Effect |
|---|---|---|
Overwrite / PreserveUnmergeables |
bang vs non-bang | Effective overwrite = Overwrite || !PreserveUnmergeables (default: overwrite, like deep_merge!). Preserve keeps existing dest values on a type mismatch. |
KnockoutPrefix |
:knockout_prefix |
A source string prefixed with it removes the matching element from dest. |
OverwriteArrays |
:overwrite_arrays |
Replace dest arrays instead of merging. |
SortMergedArrays |
:sort_merged_arrays |
Sort every merged array. |
UnpackArrays |
:unpack_arrays |
Join + split arrays on this separator before merging. |
MergeHashArrays |
:merge_hash_arrays |
Merge arrays of hashes element-wise (by index). |
ExtendExistingArrays |
:extend_existing_arrays |
Push a source hash/scalar onto a dest array. |
KeepArrayDuplicates |
:keep_array_duplicates |
Concatenate arrays keeping duplicates instead of taking the union. |
MergeNilValues |
:merge_nil_values |
Merge nil source values instead of skipping them. |
Notes on fidelity
- Ruby truthiness is honoured: a dest key whose value is
nilorfalseis treated as absent, so source creates/overwrites it. - Because Go cannot distinguish an unset string from an empty one, an empty
KnockoutPrefixmeans "no knockout" rather than the gem'sInvalidParametererror. Combining aKnockoutPrefixwith disabled overwrite panics with*InvalidOptionError, matching the gem's refusal of that combination. - Ruby Hashes with non-string keys (e.g. symbols, integers) are out of scope;
keys are
string.
License
BSD-3-Clause. See LICENSE.
Documentation
¶
Overview ¶
Package deepmerge is a pure-Go (no cgo) port of the Ruby deep_merge gem (https://github.com/danielsdeleo/deep_merge). It recursively merges values that model Ruby data: hashes as map[string]any, arrays as []any, and any other Go value as a scalar.
Entry points ¶
- DeepMerge merges source into a deep copy of dest and returns the copy; the caller's dest is left untouched (non-destructive).
- DeepMergeInto merges source into dest in place and returns the result. Because the top-level value may be replaced (for example when dest is nil or a scalar), callers must use the return value.
In both, source values take precedence over dest values, mirroring the Ruby call deep_merge!(source, dest): source is merged into dest.
Merge rules ¶
Two hashes are merged key by key. For a key present in both, the values are merged recursively. A key whose dest value is nil or false is treated as absent (Ruby truthiness), so source creates/overwrites it.
Two arrays are combined. By default the result is the set union of dest then source (dest | source in Ruby: duplicates removed, dest order first). See the Options fields for element-wise hash merging, duplicate keeping, sorting, overwrite, unpacking and knockout behaviour.
A type mismatch (for example a scalar meeting a hash) is unmergeable: source overwrites dest when Overwrite is in effect, otherwise dest is preserved.
Options ¶
Options mirrors the deep_merge gem. Overwrite and PreserveUnmergeables map to the gem's bang / non-bang variants: the effective "overwrite unmergeables" flag is Overwrite || !PreserveUnmergeables, which is true by default (like deep_merge!). Set PreserveUnmergeables to true (and leave Overwrite false) for the non-destructive-of-conflicts deep_merge behaviour.
KnockoutPrefix enables the gem's knockout feature: a source string element prefixed with it removes the matching element from dest. Because Go cannot distinguish an unset string from an empty one, an empty KnockoutPrefix means "no knockout" rather than the gem's InvalidParameter error. Specifying a KnockoutPrefix while overwrite is disabled panics with *InvalidOptionError, matching the gem's refusal to combine knockout with preserve_unmergeables.
The package has no dependency on any Ruby runtime and imports only the standard library. A consumer such as go-embedded-ruby (rbgo) can adapt a Ruby Hash#deep_merge call onto these functions by marshalling Ruby values to the Go value model above.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DeepMerge ¶
DeepMerge merges source into a deep copy of dest and returns the copy. The caller's dest is not modified.
func DeepMergeInto ¶
DeepMergeInto merges source into dest in place and returns the result. The return value must be used because the top-level value may be replaced.
Types ¶
type InvalidOptionError ¶
type InvalidOptionError struct{ Message string }
InvalidOptionError is the value passed to panic when Options combine in a way the deep_merge gem rejects.
func (*InvalidOptionError) Error ¶
func (e *InvalidOptionError) Error() string
type Options ¶
type Options struct {
// Overwrite forces overwriting of unmergeable/conflicting values. Together
// with PreserveUnmergeables it selects the gem's bang vs non-bang variant:
// the effective flag is Overwrite || !PreserveUnmergeables.
Overwrite bool
// PreserveUnmergeables keeps existing dest values when a value cannot be
// merged (type mismatch), matching Ruby's deep_merge (non-bang).
PreserveUnmergeables bool
// KnockoutPrefix, when non-empty, enables knockout: a source string element
// prefixed with it removes the matching element from dest.
KnockoutPrefix string
// OverwriteArrays replaces dest arrays with source arrays instead of merging
// them (the gem's :overwrite_arrays).
OverwriteArrays bool
// SortMergedArrays sorts every array produced by a merge.
SortMergedArrays bool
// UnpackArrays, when non-empty, joins then splits every merged array on this
// separator before merging, unpacking compound string elements.
UnpackArrays string
// MergeHashArrays merges arrays of hashes element-wise (by index) when both
// the source and dest arrays contain only hashes.
MergeHashArrays bool
// ExtendExistingArrays pushes a source hash/scalar onto a dest array rather
// than overwriting the array.
ExtendExistingArrays bool
// KeepArrayDuplicates concatenates arrays keeping duplicate elements instead
// of taking their set union.
KeepArrayDuplicates bool
// MergeNilValues merges nil source values instead of skipping them.
MergeNilValues bool
}
Options mirrors the option set of the Ruby deep_merge gem. The zero value behaves like Ruby's deep_merge! (overwrite unmergeable/conflicting values).
Source Files