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

Instance Attribute Details

#backend ⇒ Symbol (readonly)

Returns The backend used for parsing.

Returns:

  • (Symbol) —

    The backend used for parsing



52
53
54
 
# File 'lib/toml/merge/node_wrapper.rb', line 52

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



55
56
57
 
# File 'lib/toml/merge/node_wrapper.rb', line 55

def document_root
  @document_root
end

Class Method Details

.wrap(node, lines, source: nil, leading_comments: [], inline_comment: nil, backend: :tree_sitter) ⇒ 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: []) —

    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
 
# File 'lib/toml/merge/node_wrapper.rb', line 37

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

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

Instance Method Details

#array? ⇒ Boolean

Check if this is a TOML array

Returns:

  • (Boolean) 


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

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) 


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

def array_of_tables?
  canonical_type == :array_of_tables
end

#boolean? ⇒ Boolean

Check if this is a TOML boolean

Returns:

  • (Boolean) 


123
124
125
 
# File 'lib/toml/merge/node_wrapper.rb', line 123

def boolean?
  canonical_type == :boolean
end

#canonical_type ⇒ Symbol

Get the canonical (normalized) type for this node

Returns:

  • (Symbol) 


66
67
68
 
# File 'lib/toml/merge/node_wrapper.rb', line 66

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) 


296
297
298
299
300
 
# File 'lib/toml/merge/node_wrapper.rb', line 296

def closing_line
  return unless container? && @end_line

  @lines[@end_line - 1]
end

#comment? ⇒ Boolean

Check if this is a comment

Returns:

  • (Boolean) 


135
136
137
 
# File 'lib/toml/merge/node_wrapper.rb', line 135

def comment?
  canonical_type == :comment
end

#container? ⇒ Boolean

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

Returns:

  • (Boolean) 


280
281
282
 
# File 'lib/toml/merge/node_wrapper.rb', line 280

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) 


309
310
311
312
313
314
315
316
317
 
# File 'lib/toml/merge/node_wrapper.rb', line 309

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) 


141
142
143
 
# File 'lib/toml/merge/node_wrapper.rb', line 141

def datetime?
  canonical_type == :datetime
end

#document? ⇒ Boolean

Check if this is the document root

Returns:

  • (Boolean) 


147
148
149
 
# File 'lib/toml/merge/node_wrapper.rb', line 147

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) 


322
323
324
325
326
327
328
329
330
331
332
333
334
335
 
# File 'lib/toml/merge/node_wrapper.rb', line 322

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:



239
240
241
242
243
244
245
 
# File 'lib/toml/merge/node_wrapper.rb', line 239

def elements
  return [] unless array?

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

#float? ⇒ Boolean

Check if this is a TOML float

Returns:

  • (Boolean) 


117
118
119
 
# File 'lib/toml/merge/node_wrapper.rb', line 117

def float?
  canonical_type == :float
end

#inline_table? ⇒ Boolean

Check if this is a TOML inline table

Returns:

  • (Boolean) 


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

def inline_table?
  canonical_type == :inline_table
end

#integer? ⇒ Boolean

Check if this is a TOML integer

Returns:

  • (Boolean) 


111
112
113
 
# File 'lib/toml/merge/node_wrapper.rb', line 111

def integer?
  canonical_type == :integer
end

#key_name ⇒ String?

Get the key name if this is a pair node

Returns:

  • (String, nil) 


169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/toml/merge/node_wrapper.rb', line 169

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:



251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/toml/merge/node_wrapper.rb', line 251

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) 


286
287
288
289
290
291
 
# File 'lib/toml/merge/node_wrapper.rb', line 286

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) 


129
130
131
 
# File 'lib/toml/merge/node_wrapper.rb', line 129

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:



218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/toml/merge/node_wrapper.rb', line 218

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



59
60
61
62
 
# File 'lib/toml/merge/node_wrapper.rb', line 59

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

#string? ⇒ Boolean

Check if this is a TOML string

Returns:

  • (Boolean) 


105
106
107
 
# File 'lib/toml/merge/node_wrapper.rb', line 105

def string?
  canonical_type == :string
end

#table? ⇒ Boolean

Check if this is a TOML table (section)

Returns:

  • (Boolean) 


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

def table?
  canonical_type == :table
end

#table_name ⇒ String?

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

Returns:

  • (String, nil) 


153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/toml/merge/node_wrapper.rb', line 153

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) 


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

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:



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

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