Module: Ast::Merge::RegionMergeable

Included in:
SmartMergerBase
Defined in:
lib/ast/merge/region_mergeable.rb

Overview

Mixin for adding region support to SmartMerger classes.

This module provides functionality for detecting and handling regions within documents that should be merged with different strategies. Regions are portions of a document (like YAML frontmatter or fenced code blocks) that may require specialized merging.

Examples:

Basic region configuration

class SmartMerger
  include RegionMergeable

  def initialize(template, dest, regions: [], region_placeholder: nil)
    @template_content = template
    @dest_content = dest
    setup_regions(regions: regions, region_placeholder: region_placeholder)
  end
end

With YAML frontmatter regions

merger = SmartMerger.new(
  template,
  dest,
  regions: [
    {
      detector: YamlFrontmatterDetector.new,
      merger_class: SomeYamlMerger,
      merger_options: { preserve_order: true }
    }
  ]
)

With nested regions (code blocks in markdown)

merger = SmartMerger.new(
  template,
  dest,
  regions: [
    {
      detector: FencedCodeBlockDetector.ruby,
      merger_class: Prism::Merge::SmartMerger,
      regions: [...]  # Nested regions!
    }
  ]
)

Defined Under Namespace

Classes: ExtractedRegion, RegionConfig

Constant Summary collapse

DEFAULT_PLACEHOLDER_PREFIX =

Default placeholder prefix for extracted regions

"<<<AST_MERGE_REGION_"
DEFAULT_PLACEHOLDER_SUFFIX = 
">>>"

Instance Method Summary collapse

Instance Method Details

#extract_dest_regions(content) ⇒ String

Extract regions from the destination content, replacing with placeholders.

Parameters:

  • content (String) —

    Destination content

Returns:

  • (String) —

    Content with regions replaced by placeholders

Raises:



127
128
129
130
131
 
# File 'lib/ast/merge/region_mergeable.rb', line 127

def extract_dest_regions(content)
  return content unless regions_configured?

  extract_regions(content, @extracted_dest_regions)
end

#extract_template_regions(content) ⇒ String

Extract regions from the template content, replacing with placeholders.

Parameters:

  • content (String) —

    Template content

Returns:

  • (String) —

    Content with regions replaced by placeholders

Raises:



114
115
116
117
118
 
# File 'lib/ast/merge/region_mergeable.rb', line 114

def extract_template_regions(content)
  return content unless regions_configured?

  extract_regions(content, @extracted_template_regions)
end

#regions_configured? ⇒ Boolean

Check if this merger has region configurations.

Returns:

  • (Boolean) —

    true if regions are configured



103
104
105
 
# File 'lib/ast/merge/region_mergeable.rb', line 103

def regions_configured?
  @region_configs && !@region_configs.empty?
end

#setup_regions(regions:, region_placeholder: nil) ⇒ Object

Set up region handling for this merger instance.

Parameters:

  • regions (Array<Hash>) —

    Array of region configurations

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

    Custom placeholder prefix (optional)

Raises:

  • (ArgumentError) —

    if regions configuration is invalid



91
92
93
94
95
96
 
# File 'lib/ast/merge/region_mergeable.rb', line 91

def setup_regions(regions:, region_placeholder: nil)
  @region_configs = build_region_configs(regions)
  @region_placeholder_prefix = region_placeholder || DEFAULT_PLACEHOLDER_PREFIX
  @extracted_template_regions = []
  @extracted_dest_regions = []
end

#substitute_merged_regions(merged_content) ⇒ String

Merge extracted regions and substitute them back into the merged content.

Parameters:

  • merged_content (String) —

    The merged content with placeholders

Returns:

  • (String) —

    Content with placeholders replaced by merged regions



139
140
141
142
143
144
145
146
147
 
# File 'lib/ast/merge/region_mergeable.rb', line 139

def substitute_merged_regions(merged_content)
  return merged_content unless regions_configured?

  result = merged_content

  # Process regions in reverse order of extraction to handle nested placeholders
  # We need to merge template and dest regions by their placeholder index
  merge_and_substitute_regions(result)
end