Class: Commonmarker::Merge::SmartMerger

Inherits:
Markdown::Merge::SmartMerger
  • Object
show all
Defined in:
lib/commonmarker/merge/smart_merger.rb

Overview

Orchestrates the smart merge process for Markdown files using CommonMarker.

This is a thin wrapper around Markdown::Merge::SmartMerger that:

  • Forces the :commonmarker backend
  • Sets commonmarker-specific defaults (freeze token, inner_merge_code_blocks)
  • Exposes commonmarker-specific options (options hash)

Examples:

Basic merge (destination customizations preserved)

merger = SmartMerger.new(template_content, dest_content)
result = merger.merge
if result.success?
  File.write("output.md", result.content)
end

Template updates win

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

Custom signature matching

sig_gen = ->(node) {
  canonical_type = Ast::Merge::NodeTyping.merge_type_for(node) || node.type
  if canonical_type == :heading
    [:heading, node.header_level]  # Match by level only, not content
  else
    node  # Fall through to default
  end
}
merger = SmartMerger.new(
  template_content,
  dest_content,
  signature_generator: sig_gen
)

See Also:

  • Underlying implementation

Instance Method Summary collapse

Constructor Details

#initialize(template_content, dest_content, signature_generator: nil, preference: :destination, add_template_only_nodes: false, freeze_token: DEFAULT_FREEZE_TOKEN, options: {}, match_refiner: nil, node_typing: nil, **extra_options) ⇒ SmartMerger

Creates a new SmartMerger for intelligent Markdown file merging.

Parameters:

  • template_content (String) —

    Template Markdown source code

  • dest_content (String) —

    Destination Markdown source code

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

    Optional proc to generate custom node signatures.
    The proc receives a node (wrapped with canonical merge_type) and should return one of:

    • An array representing the node’s signature
    • nil to indicate the node should have no signature
    • The original node to fall through to default signature computation
  • preference (Symbol) (defaults to: :destination) —

    Controls which version to use when nodes
    have matching signatures but different content:

    • :destination (default) - Use destination version (preserves customizations)
    • :template - Use template version (applies updates)
  • add_template_only_nodes (Boolean) (defaults to: false) —

    Controls whether to add nodes that only
    exist in template:

    • false (default) - Skip template-only nodes
    • true - Add template-only nodes to result
  • freeze_token (String) (defaults to: DEFAULT_FREEZE_TOKEN) —

    Token to use for freeze block markers.
    Default: “commonmarker-merge”
    Looks for: /

  • options (Hash) (defaults to: {}) —

    CommonMarker parse options

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

    Optional match refiner for fuzzy matching of
    unmatched nodes. Default: nil (fuzzy matching disabled).
    Set to TableMatchRefiner.new to enable fuzzy table matching.

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

    Node typing configuration
    for per-node-type merge preferences.

  • extra_options (Hash) —

    Additional options for forward compatibility

Raises:



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/commonmarker/merge/smart_merger.rb', line 82

def initialize(
  template_content,
  dest_content,
  signature_generator: nil,
  preference: :destination,
  add_template_only_nodes: false,
  freeze_token: DEFAULT_FREEZE_TOKEN,
  options: {},
  match_refiner: nil,
  node_typing: nil,
  **extra_options
)
  super(
    template_content,
    dest_content,
    backend: :commonmarker,
    signature_generator: signature_generator,
    preference: preference,
    add_template_only_nodes: add_template_only_nodes,
    inner_merge_code_blocks: DEFAULT_INNER_MERGE_CODE_BLOCKS,
    freeze_token: freeze_token,
    match_refiner: match_refiner,
    node_typing: node_typing,
    options: options,
    **extra_options
  )
end

Instance Method Details

#create_file_analysis(content, **opts) ⇒ Commonmarker::Merge::FileAnalysis

Create a FileAnalysis instance for parsing.

Parameters:

  • content (String) —

    Markdown content to analyze

  • options (Hash) —

    Analysis options

Returns:



129
130
131
132
133
134
135
136
 
# File 'lib/commonmarker/merge/smart_merger.rb', line 129

def create_file_analysis(content, **opts)
  FileAnalysis.new(
    content,
    freeze_token: opts[:freeze_token],
    signature_generator: opts[:signature_generator],
    options: opts[:options] || {},
  )
end

#destination_parse_error_class ⇒ Class

Returns the DestinationParseError class to use.

Returns:

  • (Class) —

    Commonmarker::Merge::DestinationParseError



120
121
122
 
# File 'lib/commonmarker/merge/smart_merger.rb', line 120

def destination_parse_error_class
  DestinationParseError
end

#template_parse_error_class ⇒ Class

Returns the TemplateParseError class to use.

Returns:

  • (Class) —

    Commonmarker::Merge::TemplateParseError



113
114
115
 
# File 'lib/commonmarker/merge/smart_merger.rb', line 113

def template_parse_error_class
  TemplateParseError
end