toml-merge 1.0.0 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- checksums.yaml.gz.sig +0 -0
- data/CHANGELOG.md +181 -1
- data/LICENSE.txt +1 -1
- data/README.md +294 -144
- data/lib/toml/merge/conflict_resolver.rb +60 -107
- data/lib/toml/merge/emitter.rb +120 -0
- data/lib/toml/merge/file_analysis.rb +122 -39
- data/lib/toml/merge/merge_result.rb +10 -4
- data/lib/toml/merge/node_type_normalizer.rb +256 -0
- data/lib/toml/merge/node_wrapper.rb +342 -177
- data/lib/toml/merge/smart_merger.rb +42 -4
- data/lib/toml/merge/table_match_refiner.rb +4 -2
- data/lib/toml/merge/version.rb +1 -1
- data/lib/toml/merge.rb +8 -33
- data.tar.gz.sig +0 -0
- metadata +22 -22
- metadata.gz.sig +0 -0
data/README.md
CHANGED
|
@@ -1,16 +1,16 @@
|
|
|
1
|
-
| 📍 NOTE
|
|
2
|
-
|
|
3
|
-
| RubyGems (the [GitHub org]
|
|
4
|
-
| Ultimately [4 maintainers]
|
|
5
|
-
| It is a [complicated story]
|
|
6
|
-
| Simply put - there was active policy for adding or removing maintainers/owners of [rubygems]
|
|
7
|
-
| I'm adding notes like this to gems because I [don't condone theft]
|
|
8
|
-
| If a similar theft happened with my repos/gems, I'd hope some would stand up for me.
|
|
9
|
-
| Disenfranchised former-maintainers have started [gem.coop]
|
|
10
|
-
| Once available I will publish there exclusively; unless RubyCentral makes amends with the community.
|
|
11
|
-
| The ["Technology for Humans: Joel Draper"]
|
|
12
|
-
| See [here]
|
|
13
|
-
| What I'm doing: A (WIP) proposal for [bundler/gem scopes]
|
|
1
|
+
| 📍 NOTE |
|
|
2
|
+
| --- |
|
|
3
|
+
| RubyGems (the [GitHub org](https://github.com/rubygems/), not the website) [suffered](https://joel.drapper.me/p/ruby-central-security-measures/) a [hostile takeover](https://pup-e.com/blog/goodbye-rubygems/) in September 2025. |
|
|
4
|
+
| Ultimately [4 maintainers](https://www.reddit.com/r/ruby/s/gOk42POCaV) were [hard removed](https://bsky.app/profile/martinemde.com/post/3m3occezxxs2q) and a reason has been given for only 1 of those, while 2 others resigned in protest. |
|
|
5
|
+
| It is a [complicated story](https://joel.drapper.me/p/ruby-central-takeover/) which is difficult to [parse quickly](https://joel.drapper.me/p/ruby-central-fact-check/). |
|
|
6
|
+
| Simply put - there was active policy for adding or removing maintainers/owners of [rubygems](https://github.com/ruby/rubygems/blob/b1ab33a3d52310a84d16b193991af07f5a6a07c0/doc/rubygems/POLICIES.md?plain=1#L187-L196) and [bundler](https://github.com/ruby/rubygems/blob/b1ab33a3d52310a84d16b193991af07f5a6a07c0/doc/bundler/playbooks/TEAM_CHANGES.md), and those [policies were not followed](https://www.reddit.com/r/ruby/comments/1ove9vp/rubycentral_hates_this_one_fact/). |
|
|
7
|
+
| I'm adding notes like this to gems because I [don't condone theft](https://joel.drapper.me/p/ruby-central/) of repositories or gems from their rightful owners. |
|
|
8
|
+
| If a similar theft happened with my repos/gems, I'd hope some would stand up for me. |
|
|
9
|
+
| Disenfranchised former-maintainers have started [gem.coop](https://gem.coop). |
|
|
10
|
+
| Once available I will publish there exclusively; unless RubyCentral makes amends with the community. |
|
|
11
|
+
| The ["Technology for Humans: Joel Draper"](https://youtu.be/_H4qbtC5qzU?si=BvuBU90R2wAqD2E6) podcast episode by [reinteractive](https://reinteractive.com/ruby-on-rails) is the most cogent summary I'm aware of. |
|
|
12
|
+
| See [here](https://github.com/gem-coop/gem.coop/issues/12), [here](https://gem.coop) and [here](https://martinemde.com/2025/10/05/announcing-gem-coop.html) for more info on what comes next. |
|
|
13
|
+
| What I'm doing: A (WIP) proposal for [bundler/gem scopes](https://github.com/galtzo-floss/bundle-namespace), and a (WIP) proposal for a federated [gem server](https://github.com/galtzo-floss/gem-server). |
|
|
14
14
|
|
|
15
15
|
[rubygems-org]: https://github.com/rubygems/
|
|
16
16
|
[draper-security]: https://joel.drapper.me/p/ruby-central-security-measures/
|
|
@@ -31,7 +31,7 @@
|
|
|
31
31
|
[rubygems-maint-policy]: https://github.com/ruby/rubygems/blob/b1ab33a3d52310a84d16b193991af07f5a6a07c0/doc/rubygems/POLICIES.md?plain=1#L187-L196
|
|
32
32
|
[policy-fail]: https://www.reddit.com/r/ruby/comments/1ove9vp/rubycentral_hates_this_one_fact/
|
|
33
33
|
|
|
34
|
-
[![Galtzo FLOSS Logo by Aboling0, CC BY-SA 4.0]
|
|
34
|
+
[](https://discord.gg/3qme4XHNKN) [](https://www.ruby-lang.org/) [](https://github.com/kettle-rb)
|
|
35
35
|
|
|
36
36
|
[🖼️galtzo-i]: https://logos.galtzo.com/assets/images/galtzo-floss/avatar-192px.svg
|
|
37
37
|
[🖼️galtzo-discord]: https://discord.gg/3qme4XHNKN
|
|
@@ -42,55 +42,78 @@
|
|
|
42
42
|
|
|
43
43
|
# ☯️ Toml::Merge
|
|
44
44
|
|
|
45
|
-
[![Version]
|
|
45
|
+
[](https://bestgems.org/gems/toml-merge) [](http://github.com/kettle-rb/toml-merge/releases) [](https://opensource.org/licenses/MIT) [](https://bestgems.org/gems/toml-merge) [](https://www.codetriage.com/kettle-rb/toml-merge) [](https://codecov.io/gh/kettle-rb/toml-merge) [](https://coveralls.io/github/kettle-rb/toml-merge?branch=main) [](https://qlty.sh/gh/kettle-rb/projects/toml-merge/metrics/code?sort=coverageRating) [](https://qlty.sh/gh/kettle-rb/projects/toml-merge) [](https://github.com/kettle-rb/toml-merge/actions/workflows/heads.yml) [](https://github.com/kettle-rb/toml-merge/actions/workflows/dep-heads.yml) [](https://github.com/kettle-rb/toml-merge/actions/workflows/current.yml) [](https://github.com/kettle-rb/toml-merge/actions/workflows/truffle.yml) [](https://github.com/kettle-rb/toml-merge/actions/workflows/locked_deps.yml) [](https://github.com/kettle-rb/toml-merge/actions/workflows/unlocked_deps.yml) [](https://github.com/kettle-rb/toml-merge/actions/workflows/supported.yml) [](https://github.com/kettle-rb/toml-merge/actions/workflows/coverage.yml) [](https://github.com/kettle-rb/toml-merge/actions/workflows/style.yml) [](https://github.com/kettle-rb/toml-merge/security/code-scanning) [](https://github.com/kettle-rb/toml-merge/actions/workflows/license-eye.yml)
|
|
46
46
|
|
|
47
|
-
`if ci_badges.map(&:color).detect { it != "green"}` ☝️ [let me know]
|
|
48
|
-
|
|
49
|
-
---
|
|
47
|
+
`if ci_badges.map(&:color).detect { it != "green"}` ☝️ [let me know](https://discord.gg/3qme4XHNKN), as I may have missed the [discord notification](https://discord.gg/3qme4XHNKN).
|
|
50
48
|
|
|
49
|
+
-----
|
|
51
50
|
`if ci_badges.map(&:color).all? { it == "green"}` 👇️ send money so I can do more of this. FLOSS maintenance is now my full-time job.
|
|
52
51
|
|
|
53
|
-
[![OpenCollective Backers]
|
|
52
|
+
[](https://opencollective.com/kettle-rb#backer) [](https://opencollective.com/kettle-rb#sponsor) [](https://github.com/sponsors/pboling) [](https://liberapay.com/pboling/donate) [](https://www.paypal.com/paypalme/peterboling) [](https://www.buymeacoffee.com/pboling) [](https://polar.sh/pboling) [](https://ko-fi.com/O5O86SNP4)
|
|
54
53
|
|
|
55
54
|
## 🌻 Synopsis
|
|
56
55
|
|
|
57
56
|
`toml-merge` provides intelligent merging of TOML files by parsing them into
|
|
58
57
|
tree-sitter AST nodes and comparing structural elements. It supports:
|
|
59
58
|
|
|
60
|
-
- **Smart key matching** - Keys and tables are matched by their structural signatures
|
|
61
|
-
- **Table matching** - Tables are matched using a multi-factor scoring algorithm that considers
|
|
62
|
-
|
|
63
|
-
- **Freeze blocks** - Mark sections with comments to preserve them during merges
|
|
64
|
-
- **Configurable merge strategies** - Choose whether template or destination wins for conflicts,
|
|
65
|
-
|
|
66
|
-
- **Full TOML support** - Works with all TOML 1.0 features including inline tables, arrays of tables, and dotted keys
|
|
59
|
+
- **Smart key matching** - Keys and tables are matched by their structural signatures
|
|
60
|
+
- **Table matching** - Tables are matched using a multi-factor scoring algorithm that considers
|
|
61
|
+
key similarity, value overlap, and position
|
|
62
|
+
- **Freeze blocks** - Mark sections with comments to preserve them during merges
|
|
63
|
+
- **Configurable merge strategies** - Choose whether template or destination wins for conflicts,
|
|
64
|
+
or use a Hash for per-node-type preferences with `node_splitter` (see [ast-merge](https://github.com/kettle-rb/ast-merge) docs)
|
|
65
|
+
- **Full TOML support** - Works with all TOML 1.0 features including inline tables, arrays of tables, and dotted keys
|
|
67
66
|
|
|
68
67
|
### The `*-merge` Gem Family
|
|
69
68
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
| Gem
|
|
73
|
-
|
|
74
|
-
| [tree_haver][tree_haver]
|
|
75
|
-
| [ast-merge][ast-merge]
|
|
76
|
-
| [
|
|
77
|
-
| [
|
|
78
|
-
| [
|
|
79
|
-
| [
|
|
80
|
-
| [
|
|
81
|
-
| [
|
|
82
|
-
| [
|
|
83
|
-
| [
|
|
84
|
-
| [
|
|
85
|
-
| [
|
|
86
|
-
| [
|
|
69
|
+
The `*-merge` gem family provides intelligent, AST-based merging for various file formats. At the foundation is [tree_haver][tree_haver], which provides a unified cross-Ruby parsing API that works seamlessly across MRI, JRuby, and TruffleRuby.
|
|
70
|
+
|
|
71
|
+
| Gem | Language<br>/ Format | Parser Backend(s) | Description |
|
|
72
|
+
|------------------------------------------|----------------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
|
|
73
|
+
| [tree_haver][tree_haver] | Multi | MRI C, Rust, FFI, Java, Prism, Psych, Commonmarker, Markly, Citrus | **Foundation**: Cross-Ruby adapter for parsing libraries (like Faraday for HTTP) |
|
|
74
|
+
| [ast-merge][ast-merge] | Text | internal | **Infrastructure**: Shared base classes and merge logic for all `*-merge` gems |
|
|
75
|
+
| [bash-merge][bash-merge] | Bash | [tree-sitter-bash][ts-bash] (via tree_haver) | Smart merge for Bash scripts |
|
|
76
|
+
| [commonmarker-merge][commonmarker-merge] | Markdown | [Commonmarker][commonmarker] (via tree_haver) | Smart merge for Markdown (CommonMark via comrak Rust) |
|
|
77
|
+
| [dotenv-merge][dotenv-merge] | Dotenv | internal | Smart merge for `.env` files |
|
|
78
|
+
| [json-merge][json-merge] | JSON | [tree-sitter-json][ts-json] (via tree_haver) | Smart merge for JSON files |
|
|
79
|
+
| [jsonc-merge][jsonc-merge] | JSONC | [tree-sitter-jsonc][ts-jsonc] (via tree_haver) | ⚠️ Proof of concept; Smart merge for JSON with Comments |
|
|
80
|
+
| [markdown-merge][markdown-merge] | Markdown | [Commonmarker][commonmarker] / [Markly][markly] (via tree_haver) | **Foundation**: Shared base for Markdown mergers with inner code block merging |
|
|
81
|
+
| [markly-merge][markly-merge] | Markdown | [Markly][markly] (via tree_haver) | Smart merge for Markdown (CommonMark via cmark-gfm C) |
|
|
82
|
+
| [prism-merge][prism-merge] | Ruby | [Prism][prism] (`prism` std lib gem) | Smart merge for Ruby source files |
|
|
83
|
+
| [psych-merge][psych-merge] | YAML | [Psych][psych] (`psych` std lib gem) | Smart merge for YAML files |
|
|
84
|
+
| [rbs-merge][rbs-merge] | RBS | [tree-sitter-bash][ts-rbs] (via tree_haver), [RBS][rbs] (`rbs` std lib gem) | Smart merge for Ruby type signatures |
|
|
85
|
+
| [toml-merge][toml-merge] | TOML | [Citrus + toml-rb][toml-rb] (default, via tree_haver), [tree-sitter-toml][ts-toml] (via tree_haver) | Smart merge for TOML files |
|
|
86
|
+
|
|
87
|
+
#### Backend Platform Compatibility
|
|
88
|
+
|
|
89
|
+
tree_haver supports multiple parsing backends, but not all backends work on all Ruby platforms:
|
|
90
|
+
|
|
91
|
+
| Platform 👉️<br> TreeHaver Backend 👇️ | MRI | JRuby | TruffleRuby | Notes |
|
|
92
|
+
|------------------------------------------------|:---:|:-----:|:-----------:|-----------------------------------------------------|
|
|
93
|
+
| **MRI** ([ruby_tree_sitter][ruby_tree_sitter]) | ✅ | ❌ | ❌ | C extension, MRI only |
|
|
94
|
+
| **Rust** ([tree_stump][tree_stump]) | ✅ | ❌ | ❌ | Rust extension via magnus/rb-sys, MRI only |
|
|
95
|
+
| **FFI** | ✅ | ✅ | ❌ | TruffleRuby's FFI doesn't support `STRUCT_BY_VALUE` |
|
|
96
|
+
| **Java** ([jtreesitter][jtreesitter]) | ❌ | ✅ | ❌ | JRuby only, requires grammar JARs |
|
|
97
|
+
| **Prism** | ✅ | ✅ | ✅ | Ruby parsing, stdlib in Ruby 3.4+ |
|
|
98
|
+
| **Psych** | ✅ | ✅ | ✅ | YAML parsing, stdlib |
|
|
99
|
+
| **Citrus** | ✅ | ✅ | ✅ | Pure Ruby, no native dependencies |
|
|
100
|
+
| **Commonmarker** | ✅ | ❌ | ❓ | Rust extension for Markdown |
|
|
101
|
+
| **Markly** | ✅ | ❌ | ❓ | C extension for Markdown |
|
|
102
|
+
|
|
103
|
+
**Legend**: ✅ = Works, ❌ = Does not work, ❓ = Untested
|
|
104
|
+
|
|
105
|
+
**Why some backends don't work on certain platforms**:
|
|
106
|
+
|
|
107
|
+
- **JRuby**: Runs on the JVM; cannot load native C/Rust extensions (`.so` files)
|
|
108
|
+
- **TruffleRuby**: Has C API emulation via Sulong/LLVM, but it doesn't expose all MRI internals that native extensions require (e.g., `RBasic.flags`, `rb_gc_writebarrier`)
|
|
109
|
+
- **FFI on TruffleRuby**: TruffleRuby's FFI implementation doesn't support returning structs by value, which tree-sitter's C API requires
|
|
87
110
|
|
|
88
111
|
**Example implementations** for the gem templating use case:
|
|
89
112
|
|
|
90
|
-
| Gem
|
|
91
|
-
|
|
92
|
-
| [kettle-dev][kettle-dev] | Gem Development | Gem templating tool using `*-merge` gems
|
|
93
|
-
| [kettle-jem][kettle-jem] | Gem Templating
|
|
113
|
+
| Gem | Purpose | Description |
|
|
114
|
+
|--------------------------|-----------------|-----------------------------------------------|
|
|
115
|
+
| [kettle-dev][kettle-dev] | Gem Development | Gem templating tool using `*-merge` gems |
|
|
116
|
+
| [kettle-jem][kettle-jem] | Gem Templating | Gem template library with smart merge support |
|
|
94
117
|
|
|
95
118
|
[tree_haver]: https://github.com/kettle-rb/tree_haver
|
|
96
119
|
[ast-merge]: https://github.com/kettle-rb/ast-merge
|
|
@@ -112,47 +135,92 @@ This gem is part of a family of gems that provide intelligent merging for variou
|
|
|
112
135
|
[ts-json]: https://github.com/tree-sitter/tree-sitter-json
|
|
113
136
|
[ts-jsonc]: https://gitlab.com/WhyNotHugo/tree-sitter-jsonc
|
|
114
137
|
[ts-bash]: https://github.com/tree-sitter/tree-sitter-bash
|
|
138
|
+
[ts-rbs]: https://github.com/joker1007/tree-sitter-rbs
|
|
115
139
|
[ts-toml]: https://github.com/tree-sitter-grammars/tree-sitter-toml
|
|
116
|
-
[rbs]: https://github.com/ruby/rbs
|
|
117
140
|
[dotenv]: https://github.com/bkeepers/dotenv
|
|
141
|
+
[rbs]: https://github.com/ruby/rbs
|
|
142
|
+
[toml-rb]: https://github.com/emancu/toml-rb
|
|
118
143
|
[markly]: https://github.com/ioquatix/markly
|
|
119
144
|
[commonmarker]: https://github.com/gjtorikian/commonmarker
|
|
145
|
+
[ruby_tree_sitter]: https://github.com/Faveod/ruby-tree-sitter
|
|
146
|
+
[tree_stump]: https://github.com/joker1007/tree_stump
|
|
147
|
+
[jtreesitter]: https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter
|
|
148
|
+
|
|
149
|
+
### Configuration
|
|
150
|
+
|
|
151
|
+
The tree-sitter TOML parser requires a shared library. Set the `TREE_SITTER_TOML_PATH` environment variable to point to your compiled `libtree-sitter-toml.so` (or `.dylib` on macOS):
|
|
152
|
+
|
|
153
|
+
``` bash
|
|
154
|
+
export TREE_SITTER_TOML_PATH=/path/to/libtree-sitter-toml.so
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### Basic Usage
|
|
158
|
+
|
|
159
|
+
``` ruby
|
|
160
|
+
require "toml/merge"
|
|
161
|
+
|
|
162
|
+
template = <<~TOML
|
|
163
|
+
[package]
|
|
164
|
+
name = "my-app"
|
|
165
|
+
version = "1.0.0"
|
|
166
|
+
|
|
167
|
+
[dependencies]
|
|
168
|
+
serde = "1.0"
|
|
169
|
+
TOML
|
|
170
|
+
|
|
171
|
+
destination = <<~TOML
|
|
172
|
+
[package]
|
|
173
|
+
name = "my-app"
|
|
174
|
+
version = "2.0.0"
|
|
175
|
+
authors = ["Custom Author"]
|
|
176
|
+
|
|
177
|
+
[dev-dependencies]
|
|
178
|
+
tokio = "1.0"
|
|
179
|
+
TOML
|
|
180
|
+
|
|
181
|
+
merger = Toml::Merge::SmartMerger.new(template, destination)
|
|
182
|
+
result = merger.merge
|
|
120
183
|
|
|
184
|
+
puts result.content if result.success?
|
|
185
|
+
# The [package] section is merged with destination's version and authors preserved,
|
|
186
|
+
# [dependencies] from template is included,
|
|
187
|
+
# [dev-dependencies] from destination is kept
|
|
188
|
+
```
|
|
121
189
|
|
|
122
190
|
## 💡 Info you can shake a stick at
|
|
123
191
|
|
|
124
|
-
| Tokens to Remember
|
|
125
|
-
|
|
126
|
-
| Works with JRuby
|
|
127
|
-
| Works with Truffle Ruby | [![Truffle Ruby 23.1 Compat]
|
|
128
|
-
| Works with MRI Ruby 3
|
|
129
|
-
| Support & Community
|
|
130
|
-
| Source
|
|
131
|
-
| Documentation
|
|
132
|
-
| Compliance
|
|
133
|
-
| Style
|
|
134
|
-
| Maintainer 🎖️
|
|
135
|
-
| `...` 💖
|
|
192
|
+
| Tokens to Remember | [](https://bestgems.org/gems/toml-merge) [](https://github.com/kettle-rb/toml-merge) |
|
|
193
|
+
| --- | --- |
|
|
194
|
+
| Works with JRuby | [](https://github.com/kettle-rb/toml-merge/actions/workflows/current.yml) [](https://github.com/kettle-rb/toml-merge/actions/workflows/heads.yml) |
|
|
195
|
+
| Works with Truffle Ruby | [](https://github.com/kettle-rb/toml-merge/actions/workflows/truffle.yml) [](https://github.com/kettle-rb/toml-merge/actions/workflows/current.yml) |
|
|
196
|
+
| Works with MRI Ruby 3 | [](https://github.com/kettle-rb/toml-merge/actions/workflows/supported.yml) [](https://github.com/kettle-rb/toml-merge/actions/workflows/supported.yml) [](https://github.com/kettle-rb/toml-merge/actions/workflows/current.yml) [](https://github.com/kettle-rb/toml-merge/actions/workflows/heads.yml) |
|
|
197
|
+
| Support & Community | [](https://app.daily.dev/squads/rubyfriends) [](https://discord.gg/3qme4XHNKN) [](https://www.upwork.com/freelancers/~014942e9b056abdf86?mp_source=share) [](https://www.codementor.io/peterboling?utm_source=github&utm_medium=button&utm_term=peterboling&utm_campaign=github) |
|
|
198
|
+
| Source | [](https://gitlab.com/kettle-rb/toml-merge/) [](https://codeberg.org/kettle-rb/toml-merge) [](https://github.com/kettle-rb/toml-merge) [](https://www.youtube.com/watch?v=dQw4w9WgXcQ) |
|
|
199
|
+
| Documentation | [](http://rubydoc.info/gems/toml-merge) [](https://toml-merge.galtzo.com) [](http://www.railsbling.com/tags/toml-merge) [](https://gitlab.com/kettle-rb/toml-merge/-/wikis/home) [](https://github.com/kettle-rb/toml-merge/wiki) |
|
|
200
|
+
| Compliance | [](https://opensource.org/licenses/MIT) [](https://dev.to/galtzo/how-to-check-license-compatibility-41h0) [](https://www.ilo.org/declaration/lang--en/index.htm) [](SECURITY.md) [](CODE_OF_CONDUCT.md) [](https://semver.org/spec/v2.0.0.html) |
|
|
201
|
+
| Style | [](https://github.com/rubocop-lts/rubocop-lts) [](https://keepachangelog.com/en/1.0.0/) [](https://gitmoji.dev) [](https://github.com/appraisal-rb/appraisal2) |
|
|
202
|
+
| Maintainer 🎖️ | [](http://www.linkedin.com/in/peterboling) [](https://ruby.social/@galtzo) [](https://bsky.app/profile/galtzo.com) [](http://www.railsbling.com/contact) [](https://dev.to/galtzo) |
|
|
203
|
+
| `...` 💖 | [](https://wellfound.com/u/peter-boling) [](https://www.crunchbase.com/person/peter-boling) [](https://linktr.ee/galtzo) [](https://about.me/peter.boling) [🧊](https://codeberg.org/pboling) [🐙](https://github.org/pboling) [🛖](https://sr.ht/~galtzo/) [🧪](https://gitlab.com/pboling) |
|
|
136
204
|
|
|
137
205
|
### Compatibility
|
|
138
206
|
|
|
139
207
|
Compatible with MRI Ruby 3.2.0+, and concordant releases of JRuby, and TruffleRuby.
|
|
140
208
|
|
|
141
|
-
| 🚚
|
|
142
|
-
|
|
143
|
-
| 👟 Check it out
|
|
209
|
+
| 🚚 *Amazing* test matrix was brought to you by | 🔎 appraisal2 🔎 and the color 💚 green 💚 |
|
|
210
|
+
| --- | --- |
|
|
211
|
+
| 👟 Check it out\! | ✨ [github.com/appraisal-rb/appraisal2](https://github.com/appraisal-rb/appraisal2) ✨ |
|
|
144
212
|
|
|
145
213
|
### Federated DVCS
|
|
146
214
|
|
|
147
215
|
<details markdown="1">
|
|
148
216
|
<summary>Find this repo on federated forges (Coming soon!)</summary>
|
|
149
217
|
|
|
150
|
-
| Federated [DVCS]
|
|
151
|
-
|
|
152
|
-
| 🧪 [kettle-rb/toml-merge on GitLab]
|
|
153
|
-
| 🧊 [kettle-rb/toml-merge on CodeBerg]
|
|
154
|
-
| 🐙 [kettle-rb/toml-merge on GitHub]
|
|
155
|
-
| 🎮️ [Discord Server]
|
|
218
|
+
| Federated [DVCS](https://railsbling.com/posts/dvcs/put_the_d_in_dvcs/) Repository | Status | Issues | PRs | Wiki | CI | Discussions |
|
|
219
|
+
| --- | --- | --- | --- | --- | --- | --- |
|
|
220
|
+
| 🧪 [kettle-rb/toml-merge on GitLab](https://gitlab.com/kettle-rb/toml-merge/) | The Truth | [💚](https://gitlab.com/kettle-rb/toml-merge/-/issues) | [💚](https://gitlab.com/kettle-rb/toml-merge/-/merge_requests) | [💚](https://gitlab.com/kettle-rb/toml-merge/-/wikis/home) | 🐭 Tiny Matrix | ➖ |
|
|
221
|
+
| 🧊 [kettle-rb/toml-merge on CodeBerg](https://codeberg.org/kettle-rb/toml-merge) | An Ethical Mirror ([Donate](https://donate.codeberg.org/)) | [💚](https://codeberg.org/kettle-rb/toml-merge/issues) | [💚](https://codeberg.org/kettle-rb/toml-merge/pulls) | ➖ | ⭕️ No Matrix | ➖ |
|
|
222
|
+
| 🐙 [kettle-rb/toml-merge on GitHub](https://github.com/kettle-rb/toml-merge) | Another Mirror | [💚](https://github.com/kettle-rb/toml-merge/issues) | [💚](https://github.com/kettle-rb/toml-merge/pulls) | [💚](https://github.com/kettle-rb/toml-merge/wiki) | 💯 Full Matrix | [💚](https://github.com/kettle-rb/toml-merge/discussions) |
|
|
223
|
+
| 🎮️ [Discord Server](https://discord.gg/3qme4XHNKN) | [](https://discord.gg/3qme4XHNKN) | [Let's](https://discord.gg/3qme4XHNKN) | [talk](https://discord.gg/3qme4XHNKN) | [about](https://discord.gg/3qme4XHNKN) | [this](https://discord.gg/3qme4XHNKN) | [library\!](https://discord.gg/3qme4XHNKN) |
|
|
156
224
|
|
|
157
225
|
</details>
|
|
158
226
|
|
|
@@ -167,31 +235,33 @@ Available as part of the Tidelift Subscription.
|
|
|
167
235
|
|
|
168
236
|
The maintainers of this and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.
|
|
169
237
|
|
|
170
|
-
[![Get help from me on Tidelift]
|
|
238
|
+
[](https://tidelift.com/subscription/pkg/rubygems-toml-merge?utm_source=rubygems-toml-merge&utm_medium=referral&utm_campaign=readme)
|
|
171
239
|
|
|
172
|
-
- 💡Subscribe for support guarantees covering
|
|
173
|
-
- 💡Tidelift is part of [Sonar][🏙️entsup-tidelift-sonar]
|
|
174
|
-
- 💡Tidelift pays maintainers to maintain the software you depend on!<br/>📊`@`Pointy Haired Boss: An [enterprise support][🏙️entsup-tidelift] subscription is "[never gonna let you down][🧮kloc]", and *supports* open source maintainers
|
|
240
|
+
- 💡Subscribe for support guarantees covering *all* your FLOSS dependencies
|
|
175
241
|
|
|
176
|
-
|
|
242
|
+
- 💡Tidelift is part of [Sonar](https://blog.tidelift.com/tidelift-joins-sonar)
|
|
177
243
|
|
|
178
|
-
-
|
|
179
|
-
|
|
180
|
-
- [![Get help from me on Codementor][👨🏼🏫expsup-codementor-img]][👨🏼🏫expsup-codementor]
|
|
244
|
+
- 💡Tidelift pays maintainers to maintain the software you depend on\!<br/>📊`@`Pointy Haired Boss: An [enterprise support](https://tidelift.com/subscription/pkg/rubygems-toml-merge?utm_source=rubygems-toml-merge&utm_medium=referral&utm_campaign=readme) subscription is "[never gonna let you down](https://www.youtube.com/watch?v=dQw4w9WgXcQ)", and *supports* open source maintainers
|
|
245
|
+
Alternatively:
|
|
181
246
|
|
|
247
|
+
- [](https://discord.gg/3qme4XHNKN)
|
|
248
|
+
|
|
249
|
+
- [](https://www.upwork.com/freelancers/~014942e9b056abdf86?mp_source=share)
|
|
250
|
+
|
|
251
|
+
- [](https://www.codementor.io/peterboling?utm_source=github&utm_medium=button&utm_term=peterboling&utm_campaign=github)
|
|
182
252
|
</details>
|
|
183
253
|
|
|
184
254
|
## ✨ Installation
|
|
185
255
|
|
|
186
256
|
Install the gem and add to the application's Gemfile by executing:
|
|
187
257
|
|
|
188
|
-
```console
|
|
258
|
+
``` console
|
|
189
259
|
bundle add toml-merge
|
|
190
260
|
```
|
|
191
261
|
|
|
192
262
|
If bundler is not being used to manage dependencies, install the gem by executing:
|
|
193
263
|
|
|
194
|
-
```console
|
|
264
|
+
``` console
|
|
195
265
|
gem install toml-merge
|
|
196
266
|
```
|
|
197
267
|
|
|
@@ -200,19 +270,19 @@ gem install toml-merge
|
|
|
200
270
|
<details markdown="1">
|
|
201
271
|
<summary>For Medium or High Security Installations</summary>
|
|
202
272
|
|
|
203
|
-
This gem is cryptographically signed, and has verifiable [SHA-256 and SHA-512]
|
|
204
|
-
[
|
|
273
|
+
This gem is cryptographically signed, and has verifiable [SHA-256 and SHA-512](https://gitlab.com/kettle-rb/toml-merge/-/tree/main/checksums) checksums by
|
|
274
|
+
[stone\_checksums](https://github.com/galtzo-floss/stone_checksums). Be sure the gem you install hasn’t been tampered with
|
|
205
275
|
by following the instructions below.
|
|
206
276
|
|
|
207
277
|
Add my public key (if you haven’t already, expires 2045-04-29) as a trusted certificate:
|
|
208
278
|
|
|
209
|
-
```console
|
|
279
|
+
``` console
|
|
210
280
|
gem cert --add <(curl -Ls https://raw.github.com/galtzo-floss/certs/main/pboling.pem)
|
|
211
281
|
```
|
|
212
282
|
|
|
213
283
|
You only need to do that once. Then proceed to install with:
|
|
214
284
|
|
|
215
|
-
```console
|
|
285
|
+
``` console
|
|
216
286
|
gem install toml-merge -P HighSecurity
|
|
217
287
|
```
|
|
218
288
|
|
|
@@ -220,7 +290,7 @@ The `HighSecurity` trust profile will verify signed gems, and not allow the inst
|
|
|
220
290
|
|
|
221
291
|
If you want to up your security game full-time:
|
|
222
292
|
|
|
223
|
-
```console
|
|
293
|
+
``` console
|
|
224
294
|
bundle config set --global trust-policy MediumSecurity
|
|
225
295
|
```
|
|
226
296
|
|
|
@@ -234,26 +304,69 @@ NOTE: Be prepared to track down certs for signed gems and add them the same way
|
|
|
234
304
|
|
|
235
305
|
### Parser Backend Options
|
|
236
306
|
|
|
237
|
-
`toml-merge` uses [
|
|
307
|
+
`toml-merge` uses [tree\_haver](https://github.com/kettle-rb/tree_haver) for parsing, which supports multiple backends:
|
|
238
308
|
|
|
239
309
|
**Tree-sitter backend** (default, requires native library):
|
|
240
|
-
- Set the `TREE_SITTER_TOML_PATH` environment variable to point to your compiled `libtree-sitter-toml.so` (or `.dylib` on macOS):
|
|
241
|
-
|
|
242
|
-
```bash
|
|
310
|
+
- Set the `TREE_SITTER_TOML_PATH` environment variable to point to your compiled `libtree-sitter-toml.so` (or `.dylib` on macOS):
|
|
311
|
+
<!-- end list -->
|
|
312
|
+
``` bash
|
|
243
313
|
export TREE_SITTER_TOML_PATH=/path/to/libtree-sitter-toml.so
|
|
244
314
|
```
|
|
245
315
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
-
|
|
249
|
-
-
|
|
250
|
-
|
|
316
|
+
### 💎 Ruby Interface Gems (Tree-sitter Backend)
|
|
317
|
+
|
|
318
|
+
If using the tree-sitter backend, you also need a Ruby gem that provides bindings to
|
|
319
|
+
tree-sitter. Choose **one** of the following based on your Ruby implementation:
|
|
320
|
+
|
|
321
|
+
| Gem | Ruby Support | Description |
|
|
322
|
+
| --- | --- | --- |
|
|
323
|
+
| [ruby\_tree\_sitter](https://github.com/Faveod/ruby_tree_sitter) | MRI only | C extension bindings (recommended for MRI) |
|
|
324
|
+
| [tree\_stump](https://github.com/nickstenning/tree_stump) | MRI (maybe JRuby) | Rust-based bindings via Rutie |
|
|
325
|
+
| [ffi](https://github.com/ffi/ffi) | MRI, JRuby, TruffleRuby | Generic FFI bindings (used by tree\_haver's FFI backend) |
|
|
326
|
+
|
|
327
|
+
[ruby_tree_sitter]: https://github.com/Faveod/ruby_tree_sitter
|
|
328
|
+
[tree_stump]: https://github.com/nickstenning/tree_stump
|
|
329
|
+
[ffi-gem]: https://github.com/ffi/ffi
|
|
330
|
+
|
|
331
|
+
#### For MRI Ruby (Recommended)
|
|
332
|
+
|
|
333
|
+
``` console
|
|
334
|
+
gem install ruby_tree_sitter
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
Or add to your Gemfile:
|
|
251
338
|
|
|
252
|
-
|
|
339
|
+
``` ruby
|
|
340
|
+
gem "ruby_tree_sitter", "~> 2.0"
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
#### For JRuby or TruffleRuby
|
|
344
|
+
|
|
345
|
+
``` console
|
|
346
|
+
gem install ffi
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
Or add to your Gemfile:
|
|
350
|
+
|
|
351
|
+
``` ruby
|
|
352
|
+
gem "ffi"
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
The `tree_haver` gem (a dependency of toml-merge) will automatically detect and use
|
|
356
|
+
the appropriate backend based on which gems are available.
|
|
357
|
+
|
|
358
|
+
**Note:** The `ruby_tree_sitter` gem only compiles on MRI Ruby. For JRuby or TruffleRuby,
|
|
359
|
+
you must use the FFI backend or the Citrus backend (below).
|
|
253
360
|
|
|
361
|
+
**Citrus backend** (pure Ruby, no native dependencies):
|
|
362
|
+
- Alternative option using the [citrus](https://github.com/mjackson/citrus) and [toml-rb](https://github.com/emancu/toml-rb) gems
|
|
363
|
+
- No compilation or system dependencies required
|
|
364
|
+
- Ideal for environments where native extensions are problematic
|
|
365
|
+
- Configure via tree\_haver's backend selection
|
|
366
|
+
For more details on backend configuration, see the [tree\_haver documentation](https://github.com/kettle-rb/tree_haver).
|
|
254
367
|
### Merge Options
|
|
255
368
|
|
|
256
|
-
```ruby
|
|
369
|
+
``` ruby
|
|
257
370
|
merger = Toml::Merge::SmartMerger.new(
|
|
258
371
|
template_content,
|
|
259
372
|
dest_content,
|
|
@@ -282,7 +395,7 @@ merger = Toml::Merge::SmartMerger.new(
|
|
|
282
395
|
|
|
283
396
|
### Simple Merge
|
|
284
397
|
|
|
285
|
-
```ruby
|
|
398
|
+
``` ruby
|
|
286
399
|
require "toml/merge"
|
|
287
400
|
|
|
288
401
|
# Template defines the structure
|
|
@@ -290,7 +403,7 @@ template = <<~TOML
|
|
|
290
403
|
[package]
|
|
291
404
|
name = "my-app"
|
|
292
405
|
version = "1.0.0"
|
|
293
|
-
|
|
406
|
+
|
|
294
407
|
[dependencies]
|
|
295
408
|
serde = "1.0"
|
|
296
409
|
tokio = "1.0"
|
|
@@ -302,7 +415,7 @@ destination = <<~TOML
|
|
|
302
415
|
name = "my-app"
|
|
303
416
|
version = "2.0.0"
|
|
304
417
|
authors = ["Custom Author"]
|
|
305
|
-
|
|
418
|
+
|
|
306
419
|
[dev-dependencies]
|
|
307
420
|
criterion = "0.5"
|
|
308
421
|
TOML
|
|
@@ -316,7 +429,7 @@ puts result.content
|
|
|
316
429
|
|
|
317
430
|
Freeze blocks protect sections from being overwritten during merge:
|
|
318
431
|
|
|
319
|
-
```toml
|
|
432
|
+
``` toml
|
|
320
433
|
[package]
|
|
321
434
|
name = "my-app"
|
|
322
435
|
|
|
@@ -334,7 +447,7 @@ Content between `# toml-merge:freeze` and `# toml-merge:unfreeze` markers is pre
|
|
|
334
447
|
|
|
335
448
|
### Adding Template-Only Tables
|
|
336
449
|
|
|
337
|
-
```ruby
|
|
450
|
+
``` ruby
|
|
338
451
|
merger = Toml::Merge::SmartMerger.new(
|
|
339
452
|
template,
|
|
340
453
|
destination,
|
|
@@ -349,29 +462,29 @@ result = merger.merge
|
|
|
349
462
|
While kettle-rb tools are free software and will always be, the project would benefit immensely from some funding.
|
|
350
463
|
Raising a monthly budget of... "dollars" would make the project more sustainable.
|
|
351
464
|
|
|
352
|
-
We welcome both individual and corporate sponsors
|
|
465
|
+
We welcome both individual and corporate sponsors\! We also offer a
|
|
353
466
|
wide array of funding channels to account for your preferences
|
|
354
|
-
(although currently [Open Collective]
|
|
467
|
+
(although currently [Open Collective](https://opencollective.com/kettle-rb) is our preferred funding platform).
|
|
355
468
|
|
|
356
469
|
**If you're working in a company that's making significant use of kettle-rb tools we'd
|
|
357
470
|
appreciate it if you suggest to your company to become a kettle-rb sponsor.**
|
|
358
471
|
|
|
359
472
|
You can support the development of kettle-rb tools via
|
|
360
|
-
[GitHub Sponsors]
|
|
361
|
-
[Liberapay]
|
|
362
|
-
[PayPal]
|
|
363
|
-
[Open Collective]
|
|
364
|
-
and [Tidelift]
|
|
365
|
-
|
|
366
|
-
| 📍 NOTE
|
|
367
|
-
|
|
473
|
+
[GitHub Sponsors](https://github.com/sponsors/pboling),
|
|
474
|
+
[Liberapay](https://liberapay.com/pboling/donate),
|
|
475
|
+
[PayPal](https://www.paypal.com/paypalme/peterboling),
|
|
476
|
+
[Open Collective](https://opencollective.com/kettle-rb)
|
|
477
|
+
and [Tidelift](https://tidelift.com/subscription/pkg/rubygems-toml-merge?utm_source=rubygems-toml-merge&utm_medium=referral&utm_campaign=readme).
|
|
478
|
+
|
|
479
|
+
| 📍 NOTE |
|
|
480
|
+
| --- |
|
|
368
481
|
| If doing a sponsorship in the form of donation is problematic for your company <br/> from an accounting standpoint, we'd recommend the use of Tidelift, <br/> where you can get a support-like subscription instead. |
|
|
369
482
|
|
|
370
483
|
### Open Collective for Individuals
|
|
371
484
|
|
|
372
|
-
Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/kettle-rb#backer)]
|
|
485
|
+
Support us with a monthly donation and help us continue our activities. \[[Become a backer](https://opencollective.com/kettle-rb#backer)\]
|
|
373
486
|
|
|
374
|
-
NOTE: [kettle-readme-backers]
|
|
487
|
+
NOTE: [kettle-readme-backers](https://github.com/kettle-rb/toml-merge/blob/main/exe/kettle-readme-backers) updates this list every day, automatically.
|
|
375
488
|
|
|
376
489
|
<!-- OPENCOLLECTIVE-INDIVIDUALS:START -->
|
|
377
490
|
No backers yet. Be the first!
|
|
@@ -379,9 +492,9 @@ No backers yet. Be the first!
|
|
|
379
492
|
|
|
380
493
|
### Open Collective for Organizations
|
|
381
494
|
|
|
382
|
-
Become a sponsor and get your logo on our README on GitHub with a link to your site. [[Become a sponsor](https://opencollective.com/kettle-rb#sponsor)]
|
|
495
|
+
Become a sponsor and get your logo on our README on GitHub with a link to your site. \[[Become a sponsor](https://opencollective.com/kettle-rb#sponsor)\]
|
|
383
496
|
|
|
384
|
-
NOTE: [kettle-readme-backers]
|
|
497
|
+
NOTE: [kettle-readme-backers](https://github.com/kettle-rb/toml-merge/blob/main/exe/kettle-readme-backers) updates this list every day, automatically.
|
|
385
498
|
|
|
386
499
|
<!-- OPENCOLLECTIVE-ORGANIZATIONS:START -->
|
|
387
500
|
No sponsors yet. Be the first!
|
|
@@ -395,50 +508,50 @@ I’m driven by a passion to foster a thriving open-source community – a space
|
|
|
395
508
|
|
|
396
509
|
If you work at a company that uses my work, please encourage them to support me as a corporate sponsor. My work on gems you use might show up in `bundle fund`.
|
|
397
510
|
|
|
398
|
-
I’m developing a new library, [
|
|
511
|
+
I’m developing a new library, [floss\_funding](https://github.com/galtzo-floss/floss_funding), designed to empower open-source developers like myself to get paid for the work we do, in a sustainable way. Please give it a look.
|
|
399
512
|
|
|
400
|
-
**[Floss-Funding.dev]
|
|
513
|
+
**[Floss-Funding.dev](https://floss-funding.dev): 👉️ No network calls. 👉️ No tracking. 👉️ No oversight. 👉️ Minimal crypto hashing. 💡 Easily disabled nags**
|
|
401
514
|
|
|
402
|
-
[![OpenCollective Backers]
|
|
515
|
+
[](https://opencollective.com/kettle-rb#backer) [](https://opencollective.com/kettle-rb#sponsor) [](https://github.com/sponsors/pboling) [](https://liberapay.com/pboling/donate) [](https://www.paypal.com/paypalme/peterboling) [](https://www.buymeacoffee.com/pboling) [](https://polar.sh/pboling) [](https://ko-fi.com/O5O86SNP4) [](https://patreon.com/galtzo)
|
|
403
516
|
|
|
404
517
|
## 🔐 Security
|
|
405
518
|
|
|
406
|
-
See [SECURITY.md]
|
|
519
|
+
See [SECURITY.md](SECURITY.md).
|
|
407
520
|
|
|
408
521
|
## 🤝 Contributing
|
|
409
522
|
|
|
410
523
|
If you need some ideas of where to help, you could work on adding more code coverage,
|
|
411
|
-
or if it is already 💯 (see [below](#code-coverage)) check [reek](REEK), [issues]
|
|
524
|
+
or if it is already 💯 (see [below](#code-coverage)) check [reek](REEK), [issues](https://github.com/kettle-rb/toml-merge/issues), or [PRs](https://github.com/kettle-rb/toml-merge/pulls),
|
|
412
525
|
or use the gem and think about how it could be better.
|
|
413
526
|
|
|
414
|
-
We [![Keep A Changelog]
|
|
527
|
+
We [](https://keepachangelog.com/en/1.0.0/) so if you make changes, remember to update it.
|
|
415
528
|
|
|
416
|
-
See [CONTRIBUTING.md]
|
|
529
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for more detailed instructions.
|
|
417
530
|
|
|
418
531
|
### 🚀 Release Instructions
|
|
419
532
|
|
|
420
|
-
See [CONTRIBUTING.md]
|
|
533
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
421
534
|
|
|
422
535
|
### Code Coverage
|
|
423
536
|
|
|
424
|
-
[![Coverage Graph]
|
|
537
|
+
[](https://codecov.io/gh/kettle-rb/toml-merge)
|
|
425
538
|
|
|
426
|
-
[![Coveralls Test Coverage]
|
|
539
|
+
[](https://coveralls.io/github/kettle-rb/toml-merge?branch=main)
|
|
427
540
|
|
|
428
|
-
[![QLTY Test Coverage]
|
|
541
|
+
[](https://qlty.sh/gh/kettle-rb/projects/toml-merge/metrics/code?sort=coverageRating)
|
|
429
542
|
|
|
430
543
|
### 🪇 Code of Conduct
|
|
431
544
|
|
|
432
545
|
Everyone interacting with this project's codebases, issue trackers,
|
|
433
|
-
chat rooms and mailing lists agrees to follow the [![Contributor Covenant 2.1]
|
|
546
|
+
chat rooms and mailing lists agrees to follow the [](CODE_OF_CONDUCT.md).
|
|
434
547
|
|
|
435
548
|
## 🌈 Contributors
|
|
436
549
|
|
|
437
|
-
[![Contributors]
|
|
550
|
+
[](https://github.com/kettle-rb/toml-merge/graphs/contributors)
|
|
438
551
|
|
|
439
|
-
Made with [contributors-img]
|
|
552
|
+
Made with [contributors-img](https://contrib.rocks).
|
|
440
553
|
|
|
441
|
-
Also see GitLab Contributors:
|
|
554
|
+
Also see GitLab Contributors: <https://gitlab.com/kettle-rb/toml-merge/-/graphs/main>
|
|
442
555
|
|
|
443
556
|
<details>
|
|
444
557
|
<summary>⭐️ Star History</summary>
|
|
@@ -455,23 +568,23 @@ Also see GitLab Contributors: [https://gitlab.com/kettle-rb/toml-merge/-/graphs/
|
|
|
455
568
|
|
|
456
569
|
## 📌 Versioning
|
|
457
570
|
|
|
458
|
-
This Library adheres to [![Semantic Versioning 2.0.0]
|
|
571
|
+
This Library adheres to [](https://semver.org/spec/v2.0.0.html).
|
|
459
572
|
Violations of this scheme should be reported as bugs.
|
|
460
573
|
Specifically, if a minor or patch version is released that breaks backward compatibility,
|
|
461
574
|
a new version should be immediately released that restores compatibility.
|
|
462
575
|
Breaking changes to the public API will only be introduced with new major versions.
|
|
463
576
|
|
|
464
577
|
> dropping support for a platform is both obviously and objectively a breaking change <br/>
|
|
465
|
-
|
|
578
|
+
> —Jordan Harband ([@ljharb](https://github.com/ljharb), maintainer of SemVer) [in SemVer issue 716](https://github.com/semver/semver/issues/716#issuecomment-869336139)
|
|
466
579
|
|
|
467
|
-
I understand that policy doesn't work universally ("exceptions to every rule
|
|
580
|
+
I understand that policy doesn't work universally ("exceptions to every rule\!"),
|
|
468
581
|
but it is the policy here.
|
|
469
582
|
As such, in many cases it is good to specify a dependency on this library using
|
|
470
|
-
the [Pessimistic Version Constraint]
|
|
583
|
+
the [Pessimistic Version Constraint](http://guides.rubygems.org/patterns/#pessimistic-version-constraint) with two digits of precision.
|
|
471
584
|
|
|
472
585
|
For example:
|
|
473
586
|
|
|
474
|
-
```ruby
|
|
587
|
+
``` ruby
|
|
475
588
|
spec.add_dependency("toml-merge", "~> 1.0")
|
|
476
589
|
```
|
|
477
590
|
|
|
@@ -484,23 +597,22 @@ is a *breaking change* to an API, and for that reason the bike shedding is endle
|
|
|
484
597
|
To get a better understanding of how SemVer is intended to work over a project's lifetime,
|
|
485
598
|
read this article from the creator of SemVer:
|
|
486
599
|
|
|
487
|
-
- ["Major Version Numbers are Not Sacred"]
|
|
488
|
-
|
|
600
|
+
- ["Major Version Numbers are Not Sacred"](https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html)
|
|
489
601
|
</details>
|
|
490
602
|
|
|
491
|
-
See [CHANGELOG.md]
|
|
603
|
+
See [CHANGELOG.md](CHANGELOG.md) for a list of releases.
|
|
492
604
|
|
|
493
605
|
## 📄 License
|
|
494
606
|
|
|
495
607
|
The gem is available as open source under the terms of
|
|
496
|
-
the [MIT License]
|
|
497
|
-
See [LICENSE.txt]
|
|
608
|
+
the [MIT License](LICENSE.txt) [](https://opensource.org/licenses/MIT).
|
|
609
|
+
See [LICENSE.txt](LICENSE.txt) for the official [Copyright Notice](https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year).
|
|
498
610
|
|
|
499
611
|
### © Copyright
|
|
500
612
|
|
|
501
613
|
<ul>
|
|
502
614
|
<li>
|
|
503
|
-
Copyright (c) 2025 Peter H. Boling, of
|
|
615
|
+
Copyright (c) 2025-2026 Peter H. Boling, of
|
|
504
616
|
<a href="https://discord.gg/3qme4XHNKN">
|
|
505
617
|
Galtzo.com
|
|
506
618
|
<picture>
|
|
@@ -521,11 +633,11 @@ Please consider sponsoring me or the project.
|
|
|
521
633
|
|
|
522
634
|
To join the community or get help 👇️ Join the Discord.
|
|
523
635
|
|
|
524
|
-
[![Live Chat on Discord]
|
|
636
|
+
[](https://discord.gg/3qme4XHNKN)
|
|
525
637
|
|
|
526
|
-
To say "thanks
|
|
638
|
+
To say "thanks\!" ☝️ Join the Discord or 👇️ send money.
|
|
527
639
|
|
|
528
|
-
[![Sponsor kettle-rb/toml-merge on Open Source Collective]
|
|
640
|
+
[](https://opencollective.com/kettle-rb) 💌 [](https://github.com/sponsors/pboling) 💌 [](https://liberapay.com/pboling/donate) 💌 [](https://www.paypal.com/paypalme/peterboling)
|
|
529
641
|
|
|
530
642
|
### Please give the project a star ⭐ ♥.
|
|
531
643
|
|
|
@@ -690,7 +802,7 @@ Thanks for RTFM. ☺️
|
|
|
690
802
|
[📌gitmoji]: https://gitmoji.dev
|
|
691
803
|
[📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
|
|
692
804
|
[🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
|
|
693
|
-
[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.
|
|
805
|
+
[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.637-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
|
|
694
806
|
[🔐security]: SECURITY.md
|
|
695
807
|
[🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
|
|
696
808
|
[📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year
|
|
@@ -710,3 +822,41 @@ Thanks for RTFM. ☺️
|
|
|
710
822
|
[💎appraisal2]: https://github.com/appraisal-rb/appraisal2
|
|
711
823
|
[💎appraisal2-img]: https://img.shields.io/badge/appraised_by-appraisal2-34495e.svg?plastic&logo=ruby&logoColor=white
|
|
712
824
|
[💎d-in-dvcs]: https://railsbling.com/posts/dvcs/put_the_d_in_dvcs/
|
|
825
|
+
|
|
826
|
+
|
|
827
|
+
The `*-merge` gem family provides intelligent, AST-based merging for various file formats. At the foundation is [tree\_haver](https://github.com/kettle-rb/tree_haver), which provides a unified cross-Ruby parsing API that works seamlessly across MRI, JRuby, and TruffleRuby.
|
|
828
|
+
|
|
829
|
+
|
|
830
|
+
|
|
831
|
+
| Gem | Purpose | Description |
|
|
832
|
+
| --- | --- | --- |
|
|
833
|
+
| [kettle-dev](https://github.com/kettle-rb/kettle-dev) | Gem Development | Gem templating tool using `*-merge` gems |
|
|
834
|
+
| [kettle-jem](https://github.com/kettle-rb/kettle-jem) | Gem Templating | Gem template library with smart merge support |
|
|
835
|
+
|
|
836
|
+
[tree_haver]: https://github.com/kettle-rb/tree_haver
|
|
837
|
+
[ast-merge]: https://github.com/kettle-rb/ast-merge
|
|
838
|
+
[prism-merge]: https://github.com/kettle-rb/prism-merge
|
|
839
|
+
[psych-merge]: https://github.com/kettle-rb/psych-merge
|
|
840
|
+
[json-merge]: https://github.com/kettle-rb/json-merge
|
|
841
|
+
[jsonc-merge]: https://github.com/kettle-rb/jsonc-merge
|
|
842
|
+
[bash-merge]: https://github.com/kettle-rb/bash-merge
|
|
843
|
+
[rbs-merge]: https://github.com/kettle-rb/rbs-merge
|
|
844
|
+
[dotenv-merge]: https://github.com/kettle-rb/dotenv-merge
|
|
845
|
+
[toml-merge]: https://github.com/kettle-rb/toml-merge
|
|
846
|
+
[markdown-merge]: https://github.com/kettle-rb/markdown-merge
|
|
847
|
+
[markly-merge]: https://github.com/kettle-rb/markly-merge
|
|
848
|
+
[commonmarker-merge]: https://github.com/kettle-rb/commonmarker-merge
|
|
849
|
+
[kettle-dev]: https://github.com/kettle-rb/kettle-dev
|
|
850
|
+
[kettle-jem]: https://github.com/kettle-rb/kettle-jem
|
|
851
|
+
[prism]: https://github.com/ruby/prism
|
|
852
|
+
[psych]: https://github.com/ruby/psych
|
|
853
|
+
[ts-json]: https://github.com/tree-sitter/tree-sitter-json
|
|
854
|
+
[ts-jsonc]: https://gitlab.com/WhyNotHugo/tree-sitter-jsonc
|
|
855
|
+
[ts-bash]: https://github.com/tree-sitter/tree-sitter-bash
|
|
856
|
+
[ts-toml]: https://github.com/tree-sitter-grammars/tree-sitter-toml
|
|
857
|
+
[dotenv]: https://github.com/bkeepers/dotenv
|
|
858
|
+
[rbs]: https://github.com/ruby/rbs
|
|
859
|
+
[toml-rb]: https://github.com/emancu/toml-rb
|
|
860
|
+
[markly]: https://github.com/ioquatix/markly
|
|
861
|
+
[commonmarker]: https://github.com/gjtorikian/commonmarker
|
|
862
|
+
|