Class: Markly::Merge::SmartMerger

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

Overview

Orchestrates the smart merge process for Markdown files using Markly.

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

  • Forces the :markly backend
  • Sets markly-specific defaults (freeze token, inner_merge_code_blocks)
  • Exposes markly-specific options (flags, extensions)

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
)

Disable inner-merge for code blocks

merger = SmartMerger.new(
  template_content,
  dest_content,
  inner_merge_code_blocks: false
)

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, inner_merge_code_blocks: DEFAULT_INNER_MERGE_CODE_BLOCKS, freeze_token: DEFAULT_FREEZE_TOKEN, flags: ::Markly::DEFAULT, extensions: [:table], match_refiner: nil, node_typing: nil, **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
  • inner_merge_code_blocks (Boolean, CodeBlockMerger) (defaults to: DEFAULT_INNER_MERGE_CODE_BLOCKS) —

    Controls inner-merge for
    fenced code blocks:

    • true (default for markly-merge) - Enable inner-merge using default CodeBlockMerger
    • false - Disable inner-merge (use standard conflict resolution)
    • CodeBlockMerger instance - Use custom CodeBlockMerger
  • freeze_token (String) (defaults to: DEFAULT_FREEZE_TOKEN) —

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

  • flags (Integer) (defaults to: ::Markly::DEFAULT) —

    Markly parse flags (e.g., Markly::FOOTNOTES | Markly::SMART).
    Default: Markly::DEFAULT

  • extensions (Array<Symbol>) (defaults to: [:table]) —

    Markly extensions to enable (e.g., [:table, :strikethrough])
    Available extensions: :table, :strikethrough, :autolink, :tagfilter, :tasklist

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

    Optional match refiner for fuzzy matching of
    unmatched nodes. Default: nil (fuzzy matching disabled).

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

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

  • options (Hash) —

    Additional options for forward compatibility

Raises:



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/markly/merge/smart_merger.rb', line 98

def initialize(
  template_content,
  dest_content,
  signature_generator: nil,
  preference: :destination,
  add_template_only_nodes: false,
  inner_merge_code_blocks: DEFAULT_INNER_MERGE_CODE_BLOCKS,
  freeze_token: DEFAULT_FREEZE_TOKEN,
  flags: ::Markly::DEFAULT,
  extensions: [:table],
  match_refiner: nil,
  node_typing: nil,
  **options
)
  super(
    template_content,
    dest_content,
    backend: :markly,
    signature_generator: signature_generator,
    preference: preference,
    add_template_only_nodes: add_template_only_nodes,
    inner_merge_code_blocks: inner_merge_code_blocks,
    freeze_token: freeze_token,
    match_refiner: match_refiner,
    node_typing: node_typing,
    flags: flags,
    extensions: extensions,
    **options
  )
end

Instance Method Details

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

Create a FileAnalysis instance for parsing.

Parameters:

  • content (String) —

    Markdown content to analyze

  • options (Hash) —

    Analysis options

Returns:



148
149
150
151
152
153
154
155
156
 
# File 'lib/markly/merge/smart_merger.rb', line 148

def create_file_analysis(content, **opts)
  FileAnalysis.new(
    content,
    freeze_token: opts[:freeze_token],
    signature_generator: opts[:signature_generator],
    flags: opts[:flags] || ::Markly::DEFAULT,
    extensions: opts[:extensions] || [:table],
  )
end

#destination_parse_error_class ⇒ Class

Returns the DestinationParseError class to use.

Returns:

  • (Class) —

    Markly::Merge::DestinationParseError



139
140
141
 
# File 'lib/markly/merge/smart_merger.rb', line 139

def destination_parse_error_class
  DestinationParseError
end

#template_parse_error_class ⇒ Class

Returns the TemplateParseError class to use.

Returns:

  • (Class) —

    Markly::Merge::TemplateParseError



132
133
134
 
# File 'lib/markly/merge/smart_merger.rb', line 132

def template_parse_error_class
  TemplateParseError
end