Class: Toml::Merge::NodeWrapper

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

Overview

Wraps tree-sitter nodes with comment associations, line information, and signatures.
This provides a unified interface for working with TOML AST nodes during merging.

Inherits common functionality from Ast::Merge::NodeWrapperBase:

  • Source context (lines, source, comments)
  • Line info extraction
  • Basic methods: #type, #text, #signature

Adds TOML-specific functionality:

  • Backend awareness for Citrus/tree-sitter normalization
  • Type predicates using NodeTypeNormalizer
  • Structural normalization for Citrus backend (pairs as siblings)

Examples:

Basic usage

parser = TreeHaver::Parser.new
parser.language = TreeHaver::Language.toml
tree = parser.parse(source)
wrapper = NodeWrapper.new(tree.root_node, lines: source.lines, source: source)
wrapper.signature # => [:table, "section"]

See Also:

  • Ast::Merge::NodeWrapperBase

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(node, lines:, source: nil, leading_comments: nil, inline_comment: nil, **options) ⇒ NodeWrapper

Returns a new instance of NodeWrapper.



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/toml/merge/node_wrapper.rb', line 53

def initialize(node, lines:, source: nil, leading_comments: nil, inline_comment: nil, **options)
  @explicit_leading_comments = !leading_comments.nil?
  @explicit_inline_comment = !inline_comment.nil?

  super(
    node,
    lines: lines,
    source: source,
    leading_comments: leading_comments || [],
    inline_comment: inline_comment,
    **options,
  )

  hydrate_comment_associations!
end

Instance Attribute Details

#backend ⇒ Symbol (readonly)

Returns The backend used for parsing.

Returns:

  • (Symbol) —

    The backend used for parsing



70
71
72
 
# File 'lib/toml/merge/node_wrapper.rb', line 70

def backend
  @backend
end

#document_root ⇒ TreeHaver::Node? (readonly)

Returns The document root node for sibling lookups.

Returns:

  • (TreeHaver::Node, nil) —

    The document root node for sibling lookups



73
74
75
 
# File 'lib/toml/merge/node_wrapper.rb', line 73

def document_root
  @document_root
end

Class Method Details

.wrap(node, lines, source: nil, leading_comments: nil, inline_comment: nil, backend: :tree_sitter, comment_entries: nil, comment_tracker: nil) ⇒ NodeWrapper?

Wrap a tree-sitter node, returning nil for nil input.

Parameters:

  • node (TreeHaver::Node, nil) —

    tree-sitter node to wrap

  • lines (Array<String>) —

    Source lines for content extraction

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

    Original source string

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

    Comments before this node

  • inline_comment (Hash, nil) (defaults to: nil) —

    Inline comment on the node’s line

  • backend (Symbol) (defaults to: :tree_sitter) —

    The backend used for parsing (:tree_sitter or :citrus)

Returns:

  • (NodeWrapper, nil) —

    Wrapped node or nil if node is nil



37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/toml/merge/node_wrapper.rb', line 37

def wrap(node, lines, source: nil, leading_comments: nil, inline_comment: nil, backend: :tree_sitter, comment_entries: nil, comment_tracker: nil)
  return if node.nil?

  new(
    node,
    lines: lines,
    source: source,
    leading_comments: leading_comments,
    inline_comment: inline_comment,
    backend: backend,
    comment_entries: comment_entries,
    comment_tracker: comment_tracker,
  )
end

Instance Method Details

#array? ⇒ Boolean

Check if this is a TOML array

Returns:

  • (Boolean) 


119
120
121
 
# File 'lib/toml/merge/node_wrapper.rb', line 119

def array?
  canonical_type == :array
end

#array_of_tables? ⇒ Boolean

Check if this is a TOML array of tables
Uses NodeTypeNormalizer for backend-agnostic type checking.

Returns:

  • (Boolean) 


107
108
109
 
# File 'lib/toml/merge/node_wrapper.rb', line 107

def array_of_tables?
  canonical_type == :array_of_tables
end

#boolean? ⇒ Boolean

Check if this is a TOML boolean

Returns:

  • (Boolean) 


143
144
145
 
# File 'lib/toml/merge/node_wrapper.rb', line 143

def boolean?
  canonical_type == :boolean
end

#canonical_type ⇒ Symbol

Get the canonical (normalized) type for this node

Returns:

  • (Symbol) 


86
87
88
 
# File 'lib/toml/merge/node_wrapper.rb', line 86

def canonical_type
  NodeTypeNormalizer.canonical_type(@node.type, @backend)
end

#closing_line ⇒ String?

Get the closing line for a container node
For tables, this is the last line of content before the next table or EOF

Returns:

  • (String, nil) 


316
317
318
319
320
 
# File 'lib/toml/merge/node_wrapper.rb', line 316

def closing_line
  return unless container? && @end_line

  @lines[@end_line - 1]
end

#comment? ⇒ Boolean

Check if this is a comment

Returns:

  • (Boolean) 


155
156
157
 
# File 'lib/toml/merge/node_wrapper.rb', line 155

def comment?
  canonical_type == :comment
end

#container? ⇒ Boolean

Check if this node is a container (has mergeable children)

Returns:

  • (Boolean) 


300
301
302
 
# File 'lib/toml/merge/node_wrapper.rb', line 300

def container?
  table? || array_of_tables? || inline_table? || array? || document?
end

#content ⇒ String

Get the content for this node from source lines.

Handles structural differences between backends:

  • Tree-sitter: table nodes include pairs, so start_line..end_line covers everything
  • Citrus: table nodes only include header, so we extend to include associated pairs

Returns:

  • (String) 


329
330
331
332
333
334
335
336
337
 
# File 'lib/toml/merge/node_wrapper.rb', line 329

def content
  return "" unless @start_line

  # For tables with Citrus backend, extend end_line to include pairs
  effective_end = effective_end_line
  return "" unless effective_end

  (@start_line..effective_end).map { |ln| @lines[ln - 1] }.compact.join("\n")
end

#datetime? ⇒ Boolean

Check if this is a datetime

Returns:

  • (Boolean) 


161
162
163
 
# File 'lib/toml/merge/node_wrapper.rb', line 161

def datetime?
  canonical_type == :datetime
end

#document? ⇒ Boolean

Check if this is the document root

Returns:

  • (Boolean) 


167
168
169
 
# File 'lib/toml/merge/node_wrapper.rb', line 167

def document?
  canonical_type == :document
end

#effective_end_line ⇒ Integer?

Get the effective end line for this node, accounting for Citrus backend.
For Citrus tables, this extends to the line before the next table.

Returns:

  • (Integer, nil) 


342
343
344
345
346
347
348
349
350
351
352
353
354
355
 
# File 'lib/toml/merge/node_wrapper.rb', line 342

def effective_end_line
  return @end_line if !(table? || array_of_tables?) || @document_root.nil?

  # Check if we have pairs as children (tree-sitter structure)
  child_pairs = collect_child_pairs
  return @end_line if child_pairs.any?

  # Citrus structure: find the last pair that belongs to us
  sibling_pairs = collect_sibling_pairs_for_table
  return @end_line if sibling_pairs.empty?

  # Return the end line of the last pair
  sibling_pairs.map(&:end_line).compact.max || @end_line
end

#elements ⇒ Array<NodeWrapper>

Get array elements if this is an array

Handles structural differences between backends:

  • Tree-sitter: values are direct children of array node
  • Citrus: values are nested inside array_elements container

Returns:



259
260
261
262
263
264
265
 
# File 'lib/toml/merge/node_wrapper.rb', line 259

def elements
  return [] unless array?

  result = []
  collect_array_elements(@node, result)
  result
end

#float? ⇒ Boolean

Check if this is a TOML float

Returns:

  • (Boolean) 


137
138
139
 
# File 'lib/toml/merge/node_wrapper.rb', line 137

def float?
  canonical_type == :float
end

#inline_table? ⇒ Boolean

Check if this is a TOML inline table

Returns:

  • (Boolean) 


113
114
115
 
# File 'lib/toml/merge/node_wrapper.rb', line 113

def inline_table?
  canonical_type == :inline_table
end

#integer? ⇒ Boolean

Check if this is a TOML integer

Returns:

  • (Boolean) 


131
132
133
 
# File 'lib/toml/merge/node_wrapper.rb', line 131

def integer?
  canonical_type == :integer
end

#key_name ⇒ String?

Get the key name if this is a pair node

Returns:

  • (String, nil) 


189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/toml/merge/node_wrapper.rb', line 189

def key_name
  return unless pair?

  # In TOML, pair has key children (bare_key, quoted_key, or dotted_key)
  @node.each do |child|
    child_canonical = NodeTypeNormalizer.canonical_type(child.type, @backend)
    if NodeTypeNormalizer.key_type?(child_canonical)
      key_text = node_text(child)
      # Remove surrounding quotes if present, and strip whitespace
      # (Citrus backend includes trailing space in key nodes)
      return key_text&.gsub(/\A["']|["']\z/, "")&.strip
    end
  end
  nil
end

#mergeable_children ⇒ Array<NodeWrapper>

Get mergeable children - the semantically meaningful children for tree merging
For tables, returns pairs. For arrays, returns elements.
For other node types, returns empty array (leaf nodes).

Returns:



271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
 
# File 'lib/toml/merge/node_wrapper.rb', line 271

def mergeable_children
  case canonical_type
  when :table, :inline_table, :array_of_tables
    pairs
  when :array
    elements
  when :document
    # Return top-level pairs and tables
    result = []
    @node.each do |child|
      child_canonical = NodeTypeNormalizer.canonical_type(child.type, @backend)
      next if child_canonical == :comment

      result << NodeWrapper.new(
        child,
        lines: @lines,
        source: @source,
        backend: @backend,
        document_root: @document_root,
      )
    end
    result
  else
    []
  end
end

#opening_line ⇒ String?

Get the opening line for a table (the line with [table_name])

Returns:

  • (String, nil) 


306
307
308
309
310
311
 
# File 'lib/toml/merge/node_wrapper.rb', line 306

def opening_line
  return unless @start_line
  return unless table? || array_of_tables?

  @lines[@start_line - 1]
end

#pair? ⇒ Boolean

Check if this is a key-value pair

Returns:

  • (Boolean) 


149
150
151
 
# File 'lib/toml/merge/node_wrapper.rb', line 149

def pair?
  canonical_type == :pair
end

#pairs ⇒ Array<NodeWrapper>

Get key-value pairs from a table or inline_table.

Handles structural differences between backends:

  • Tree-sitter: pairs are children of the table node
  • Citrus: pairs are siblings at document level (table only contains header)

For Citrus backend, when no pair children are found, we look for sibling
pairs in the document that belong to this table (pairs after this table’s
header but before the next table).

Returns:



238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/toml/merge/node_wrapper.rb', line 238

def pairs
  return [] unless table? || inline_table? || document? || array_of_tables?

  # First, try to find pairs as direct children (tree-sitter structure)
  result = collect_child_pairs
  return result if result.any?

  # For Citrus backend: pairs are siblings, not children
  # Look for pairs in document that belong to this table
  return [] if @document_root.nil? || !(table? || array_of_tables?)

  collect_sibling_pairs_for_table
end

#process_additional_options(options) ⇒ Object

Process TOML-specific options (backend, document_root)

Parameters:

  • options (Hash) —

    Additional options



77
78
79
80
81
82
 
# File 'lib/toml/merge/node_wrapper.rb', line 77

def process_additional_options(options)
  @backend = options.fetch(:backend, :tree_sitter)
  @document_root = options[:document_root]
  @comment_entries = Array(options[:comment_entries])
  @comment_tracker = options[:comment_tracker]
end

#string? ⇒ Boolean

Check if this is a TOML string

Returns:

  • (Boolean) 


125
126
127
 
# File 'lib/toml/merge/node_wrapper.rb', line 125

def string?
  canonical_type == :string
end

#table? ⇒ Boolean

Check if this is a TOML table (section)

Returns:

  • (Boolean) 


100
101
102
 
# File 'lib/toml/merge/node_wrapper.rb', line 100

def table?
  canonical_type == :table
end

#table_name ⇒ String?

Get the table name (header) if this is a table

Returns:

  • (String, nil) 


173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/toml/merge/node_wrapper.rb', line 173

def table_name
  return unless table? || array_of_tables?

  # Find the dotted_key or bare_key child that represents the table name
  @node.each do |child|
    child_canonical = NodeTypeNormalizer.canonical_type(child.type, @backend)
    if NodeTypeNormalizer.key_type?(child_canonical)
      # Strip whitespace (Citrus backend includes trailing space in key nodes)
      return node_text(child)&.strip
    end
  end
  nil
end

#type?(type_name) ⇒ Boolean

Check if this node has a specific type (checks both raw and canonical)

Parameters:

  • type_name (Symbol, String) —

    Type to check

Returns:

  • (Boolean) 


93
94
95
96
 
# File 'lib/toml/merge/node_wrapper.rb', line 93

def type?(type_name)
  type_sym = type_name.to_sym
  @node.type.to_sym == type_sym || canonical_type == type_sym
end

#value_node ⇒ NodeWrapper?

Get the value node if this is a pair

Returns:



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/toml/merge/node_wrapper.rb', line 207

def value_node
  return unless pair?

  @node.each do |child|
    child_canonical = NodeTypeNormalizer.canonical_type(child.type, @backend)
    # Skip keys, equals sign, whitespace, and unknown (Citrus uses these for delimiters)
    next if NodeTypeNormalizer.key_type?(child_canonical)
    next if %i[equals whitespace unknown space].include?(child_canonical)

    return NodeWrapper.new(
      child,
      lines: @lines,
      source: @source,
      backend: @backend,
      document_root: @document_root,
    )
  end
  nil
end