Class: Toml::Merge::SmartMerger

Inherits:
Ast::Merge::SmartMergerBase
  • Object
show all
Defined in:
lib/toml/merge/smart_merger.rb

Overview

High-level merger for TOML content.
Orchestrates parsing, analysis, and conflict resolution.

Extends SmartMergerBase with backend-agnostic parsing via tree_haver.
Supports both tree-sitter and Citrus/toml-rb backends (auto-selected by TreeHaver).

Examples:

Basic usage

merger = SmartMerger.new(template_content, dest_content)
result = merger.merge
File.write("merged.toml", result.output)

Force Citrus backend via environment

# Set TREE_HAVER_BACKEND=citrus before requiring toml/merge
merger = SmartMerger.new(template, dest)
result = merger.merge

Force Citrus backend via TreeHaver

TreeHaver.with_backend(:citrus) do
  merger = SmartMerger.new(template, dest)
  result = merger.merge
end

With options

merger = SmartMerger.new(template, dest,
  preference: :template,
  add_template_only_nodes: true)
result = merger.merge

Enable fuzzy matching

merger = SmartMerger.new(template, dest, match_refiner: TableMatchRefiner.new)

With regions (embedded content)

merger = SmartMerger.new(template, dest,
  regions: [{ detector: SomeDetector.new, merger_class: SomeMerger }])

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(template_content, dest_content, signature_generator: nil, preference: :destination, add_template_only_nodes: false, remove_template_missing_nodes: false, freeze_token: nil, match_refiner: nil, regions: nil, region_placeholder: nil, node_typing: nil, sort_keys: false, **options) ⇒ SmartMerger

Note:

To force a specific backend, use TreeHaver.with_backend or TREE_HAVER_BACKEND env var.
TreeHaver handles backend selection, auto-detection, and fallback.

Creates a new SmartMerger

Parameters:

  • template_content (String) —

    Template TOML content

  • dest_content (String) —

    Destination TOML content

  • signature_generator (Proc, nil) (defaults to: nil) —

    Custom signature generator

  • preference (Symbol, Hash) (defaults to: :destination) —

    :destination, :template, or per-type Hash

  • add_template_only_nodes (Boolean) (defaults to: false) —

    Whether to add nodes only found in template

  • freeze_token (String, nil) (defaults to: nil) —

    Token for freeze block markers

  • match_refiner (#call, nil) (defaults to: nil) —

    Match refiner for fuzzy matching

  • remove_template_missing_nodes (Boolean) (defaults to: false) —

    Whether to remove destination-only
    nodes while preserving their attached comments

  • regions (Array<Hash>, nil) (defaults to: nil) —

    Region configurations for nested merging

  • region_placeholder (String, nil) (defaults to: nil) —

    Custom placeholder for regions

  • node_typing (Hash{Symbol,String => #call}, nil) (defaults to: nil) —

    Node typing configuration
    for per-node-type merge preferences

  • sort_keys (Boolean) (defaults to: false) —

    Whether to alphabetically sort key=value pairs
    within gap-separated blocks after merging

  • options (Hash) —

    Additional options for forward compatibility



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/toml/merge/smart_merger.rb', line 68

def initialize(
  template_content,
  dest_content,
  signature_generator: nil,
  preference: :destination,
  add_template_only_nodes: false,
  remove_template_missing_nodes: false,
  freeze_token: nil,
  match_refiner: nil,
  regions: nil,
  region_placeholder: nil,
  node_typing: nil,
  sort_keys: false,
  **options
)
  @remove_template_missing_nodes = remove_template_missing_nodes
  @sort_keys = sort_keys

  super(
    template_content,
    dest_content,
    signature_generator: signature_generator,
    preference: preference,
    add_template_only_nodes: add_template_only_nodes,
    remove_template_missing_nodes: remove_template_missing_nodes,
    freeze_token: freeze_token,
    match_refiner: match_refiner,
    regions: regions,
    region_placeholder: region_placeholder,
    node_typing: node_typing,
    **options
  )

  # Capture the resolved backend from template analysis (for NodeTypeNormalizer)
  @backend = @template_analysis.backend
end

Instance Attribute Details

#backend ⇒ Symbol (readonly)

Returns The AST format being used (:tree_sitter or :citrus).

Returns:

  • (Symbol) —

    The AST format being used (:tree_sitter or :citrus)



41
42
43
 
# File 'lib/toml/merge/smart_merger.rb', line 41

def backend
  @backend
end

#remove_template_missing_nodes ⇒ Boolean (readonly)

Returns Whether destination-only nodes should be removed while
promoting their attached comments.

Returns:

  • (Boolean) —

    Whether destination-only nodes should be removed while
    promoting their attached comments



45
46
47
 
# File 'lib/toml/merge/smart_merger.rb', line 45

def remove_template_missing_nodes
  @remove_template_missing_nodes
end

Instance Method Details

#options ⇒ Hash

Backward-compatible options hash

Returns:

  • (Hash) —

    The merge options



108
109
110
111
112
113
114
115
 
# File 'lib/toml/merge/smart_merger.rb', line 108

def options
  {
    preference: @preference,
    add_template_only_nodes: @add_template_only_nodes,
    remove_template_missing_nodes: @remove_template_missing_nodes,
    match_refiner: @match_refiner,
  }
end