Class: Ast::Merge::Comment::Attachment

Inherits:
Object
  • Object
show all
Defined in:
lib/ast/merge/comment/attachment.rb

Overview

A passive per-node container for comment regions associated with a structural AST node.

This does not yet impose merge policy. It simply normalizes how merge gems can describe leading, inline, trailing, and orphan comment regions around a structural owner node.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(owner: nil, leading_region: nil, inline_region: nil, trailing_region: nil, orphan_regions: [], leading_gap: nil, trailing_gap: nil, metadata: {}, **options) ⇒ void

Build a passive comment attachment.

Parameters:

  • owner (Object, nil) (defaults to: nil) —

    structural owner for the attachment

  • leading_region (Region, nil) (defaults to: nil) —

    leading comment region

  • inline_region (Region, nil) (defaults to: nil) —

    inline comment region

  • trailing_region (Region, nil) (defaults to: nil) —

    trailing comment region

  • orphan_regions (Array<Region>) (defaults to: []) —

    detached regions associated with the owner

  • leading_gap (Layout::Gap, nil) (defaults to: nil) —

    adjacent leading blank-line gap

  • trailing_gap (Layout::Gap, nil) (defaults to: nil) —

    adjacent trailing blank-line gap

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

    base metadata

  • options (Hash) —

    extra metadata merged into metadata



42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/ast/merge/comment/attachment.rb', line 42

def initialize(owner: nil, leading_region: nil, inline_region: nil, trailing_region: nil, orphan_regions: [],
               leading_gap: nil, trailing_gap: nil, metadata: {}, **options)
  @owner = owner
  @leading_region = leading_region
  @inline_region = inline_region
  @trailing_region = trailing_region
  @orphan_regions = Array(orphan_regions).freeze
  @leading_gap = leading_gap
  @trailing_gap = trailing_gap
  @metadata = metadata.merge(options).freeze
end

Instance Attribute Details

#inline_region ⇒ Object, ... (readonly)

Returns:

  • (Object, nil) —

    structural node this attachment belongs to

  • (Region, nil) —

    normalized leading comment region

  • (Region, nil) —

    normalized inline comment region

  • (Region, nil) —

    normalized trailing comment region

  • (Array<Region>) —

    detached/orphan regions carried with this owner

  • (Layout::Gap, nil) —

    leading layout gap associated with the owner

  • (Layout::Gap, nil) —

    trailing layout gap associated with the owner

  • (Hash) —

    producer metadata for downstream consumers



21
22
23
 
# File 'lib/ast/merge/comment/attachment.rb', line 21

def inline_region
  @inline_region
end

#leading_gap ⇒ Object, ... (readonly)

Returns:

  • (Object, nil) —

    structural node this attachment belongs to

  • (Region, nil) —

    normalized leading comment region

  • (Region, nil) —

    normalized inline comment region

  • (Region, nil) —

    normalized trailing comment region

  • (Array<Region>) —

    detached/orphan regions carried with this owner

  • (Layout::Gap, nil) —

    leading layout gap associated with the owner

  • (Layout::Gap, nil) —

    trailing layout gap associated with the owner

  • (Hash) —

    producer metadata for downstream consumers



21
22
23
 
# File 'lib/ast/merge/comment/attachment.rb', line 21

def leading_gap
  @leading_gap
end

#leading_region ⇒ Object, ... (readonly)

Returns:

  • (Object, nil) —

    structural node this attachment belongs to

  • (Region, nil) —

    normalized leading comment region

  • (Region, nil) —

    normalized inline comment region

  • (Region, nil) —

    normalized trailing comment region

  • (Array<Region>) —

    detached/orphan regions carried with this owner

  • (Layout::Gap, nil) —

    leading layout gap associated with the owner

  • (Layout::Gap, nil) —

    trailing layout gap associated with the owner

  • (Hash) —

    producer metadata for downstream consumers



21
22
23
 
# File 'lib/ast/merge/comment/attachment.rb', line 21

def leading_region
  @leading_region
end

#metadata ⇒ Object, ... (readonly)

Returns:

  • (Object, nil) —

    structural node this attachment belongs to

  • (Region, nil) —

    normalized leading comment region

  • (Region, nil) —

    normalized inline comment region

  • (Region, nil) —

    normalized trailing comment region

  • (Array<Region>) —

    detached/orphan regions carried with this owner

  • (Layout::Gap, nil) —

    leading layout gap associated with the owner

  • (Layout::Gap, nil) —

    trailing layout gap associated with the owner

  • (Hash) —

    producer metadata for downstream consumers



21
22
23
 
# File 'lib/ast/merge/comment/attachment.rb', line 21

def metadata
  @metadata
end

#orphan_regions ⇒ Object, ... (readonly)

Returns:

  • (Object, nil) —

    structural node this attachment belongs to

  • (Region, nil) —

    normalized leading comment region

  • (Region, nil) —

    normalized inline comment region

  • (Region, nil) —

    normalized trailing comment region

  • (Array<Region>) —

    detached/orphan regions carried with this owner

  • (Layout::Gap, nil) —

    leading layout gap associated with the owner

  • (Layout::Gap, nil) —

    trailing layout gap associated with the owner

  • (Hash) —

    producer metadata for downstream consumers



21
22
23
 
# File 'lib/ast/merge/comment/attachment.rb', line 21

def orphan_regions
  @orphan_regions
end

#owner ⇒ Object, ... (readonly)

Returns:

  • (Object, nil) —

    structural node this attachment belongs to

  • (Region, nil) —

    normalized leading comment region

  • (Region, nil) —

    normalized inline comment region

  • (Region, nil) —

    normalized trailing comment region

  • (Array<Region>) —

    detached/orphan regions carried with this owner

  • (Layout::Gap, nil) —

    leading layout gap associated with the owner

  • (Layout::Gap, nil) —

    trailing layout gap associated with the owner

  • (Hash) —

    producer metadata for downstream consumers



21
22
23
 
# File 'lib/ast/merge/comment/attachment.rb', line 21

def owner
  @owner
end

#trailing_gap ⇒ Object, ... (readonly)

Returns:

  • (Object, nil) —

    structural node this attachment belongs to

  • (Region, nil) —

    normalized leading comment region

  • (Region, nil) —

    normalized inline comment region

  • (Region, nil) —

    normalized trailing comment region

  • (Array<Region>) —

    detached/orphan regions carried with this owner

  • (Layout::Gap, nil) —

    leading layout gap associated with the owner

  • (Layout::Gap, nil) —

    trailing layout gap associated with the owner

  • (Hash) —

    producer metadata for downstream consumers



21
22
23
 
# File 'lib/ast/merge/comment/attachment.rb', line 21

def trailing_gap
  @trailing_gap
end

#trailing_region ⇒ Object, ... (readonly)

Returns:

  • (Object, nil) —

    structural node this attachment belongs to

  • (Region, nil) —

    normalized leading comment region

  • (Region, nil) —

    normalized inline comment region

  • (Region, nil) —

    normalized trailing comment region

  • (Array<Region>) —

    detached/orphan regions carried with this owner

  • (Layout::Gap, nil) —

    leading layout gap associated with the owner

  • (Layout::Gap, nil) —

    trailing layout gap associated with the owner

  • (Hash) —

    producer metadata for downstream consumers



21
22
23
 
# File 'lib/ast/merge/comment/attachment.rb', line 21

def trailing_region
  @trailing_region
end

Instance Method Details

#empty? ⇒ Boolean

Returns:

  • (Boolean) 


61
62
63
 
# File 'lib/ast/merge/comment/attachment.rb', line 61

def empty?
  regions.empty?
end

#freeze?(freeze_token) ⇒ Boolean

Returns:

  • (Boolean) 


99
100
101
 
# File 'lib/ast/merge/comment/attachment.rb', line 99

def freeze?(freeze_token)
  regions.any? { |region| region.respond_to?(:freeze?) && region.freeze?(freeze_token) }
end

#freeze_marker?(freeze_token) ⇒ Boolean

Returns:

  • (Boolean) 


107
108
109
 
# File 'lib/ast/merge/comment/attachment.rb', line 107

def freeze_marker?(freeze_token)
  freeze?(freeze_token) || unfreeze?(freeze_token)
end

#inspect ⇒ String

Return a concise debug representation of the attachment.

Returns:

  • (String) 


114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/ast/merge/comment/attachment.rb', line 114

def inspect
  owner_desc = if owner.respond_to?(:type)
                 owner.method(:type).call
               elsif owner.nil?
                 nil
               else
                 owner.class.name
               end

  "#<#{self.class.name} owner=#{owner_desc.inspect} regions=#{regions.size} layout_gaps=#{layout_gaps.size}>"
end

#layout_gaps ⇒ Array<Layout::Gap>

Return all distinct layout gaps referenced by this attachment.

Returns:



68
69
70
 
# File 'lib/ast/merge/comment/attachment.rb', line 68

def layout_gaps
  [leading_gap, trailing_gap].compact.uniq
end

#layout_owned_regions(**options) ⇒ Object 



84
85
86
87
88
89
 
# File 'lib/ast/merge/comment/attachment.rb', line 84

def layout_owned_regions(**options)
  [
    (leading_region if leading_region_layout_owned?(**options)),
    (trailing_region if trailing_region_layout_owned?(**options))
  ].compact
end

#leading_freeze?(freeze_token) ⇒ Boolean

Returns:

  • (Boolean) 


91
92
93
 
# File 'lib/ast/merge/comment/attachment.rb', line 91

def leading_freeze?(freeze_token)
  leading_region.respond_to?(:freeze?) && leading_region.freeze?(freeze_token)
end

#leading_region_layout_owned?(**options) ⇒ Boolean

Returns:

  • (Boolean) 


72
73
74
75
76
 
# File 'lib/ast/merge/comment/attachment.rb', line 72

def leading_region_layout_owned?(**options)
  !!(leading_region&.floating? &&
    leading_gap&.leading_for?(owner) &&
    leading_gap.controls_output_for?(owner, **options))
end

#leading_unfreeze?(freeze_token) ⇒ Boolean

Returns:

  • (Boolean) 


95
96
97
 
# File 'lib/ast/merge/comment/attachment.rb', line 95

def leading_unfreeze?(freeze_token)
  leading_region.respond_to?(:unfreeze?) && leading_region.unfreeze?(freeze_token)
end

#regions ⇒ Array<Region>

Return all normalized comment regions carried by this attachment.

Returns:



57
58
59
 
# File 'lib/ast/merge/comment/attachment.rb', line 57

def regions
  [leading_region, inline_region, trailing_region, *orphan_regions].compact
end

#trailing_region_layout_owned?(**options) ⇒ Boolean

Returns:

  • (Boolean) 


78
79
80
81
82
 
# File 'lib/ast/merge/comment/attachment.rb', line 78

def trailing_region_layout_owned?(**options)
  !!(trailing_region&.floating? &&
    trailing_gap&.trailing_for?(owner) &&
    trailing_gap.controls_output_for?(owner, **options))
end

#unfreeze?(freeze_token) ⇒ Boolean

Returns:

  • (Boolean) 


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

def unfreeze?(freeze_token)
  regions.any? { |region| region.respond_to?(:unfreeze?) && region.unfreeze?(freeze_token) }
end