Class: Rhales::RueDocument

Inherits:
Object
  • Object
show all
Defined in:
lib/rhales/core/rue_document.rb

Overview

High-level interface for parsed .rue files

This class provides a convenient interface to .rue files parsed by RueFormatParser. It uses RueFormatParser internally for low-level parsing and provides high-level methods for accessing sections, attributes, and extracted data.

Features: - High-level interface to RueFormatParser AST - Accurate error reporting with line/column information - Convenient section access methods - Section validation and attribute extraction - Variable and partial dependency analysis - AST-to-string conversion when needed

Note: This class represents a parsed .rue file document, similar to how HTML::Document represents a parsed HTML document.

Usage: document = RueDocument.new(rue_content) document.parse! template_section = document.section(‘template’) variables = document.template_variables

Defined Under Namespace

Classes: InvalidSyntaxError, ParseError, SectionDuplicateError, SectionMissingError

Constant Summary collapse

REQUIRES_ONE_OF_SECTIONS =

At least one of these sections must be present

%w[schema template].freeze
KNOWN_SECTIONS = 
%w[schema template logic].freeze
ALL_SECTIONS = 
KNOWN_SECTIONS.freeze
KNOWN_SCHEMA_ATTRIBUTES =

Known schema section attributes

%w[lang version envelope window merge layout extends src].freeze
WINDOW_ATTRIBUTE_PATTERN =

The window attribute names a global JavaScript property and is interpolated into HTML attribute and 

/\A[a-zA-Z_][a-zA-Z0-9_]*\z/

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(content, file_path = nil) ⇒ RueDocument

Returns a new instance of RueDocument.



51
52
53
54
55
56
 
# File 'lib/rhales/core/rue_document.rb', line 51

def initialize(content, file_path = nil)
  @content   = content
  @file_path = file_path
  @grammar   = RueFormatParser.new(content, file_path)
  @ast       = nil
end

Instance Attribute Details

#ast ⇒ Object (readonly)

Returns the value of attribute ast.



49
50
51
 
# File 'lib/rhales/core/rue_document.rb', line 49

def ast
  @ast
end

#content ⇒ Object (readonly)

Returns the value of attribute content.



49
50
51
 
# File 'lib/rhales/core/rue_document.rb', line 49

def content
  @content
end

#file_path ⇒ Object (readonly)

Returns the value of attribute file_path.



49
50
51
 
# File 'lib/rhales/core/rue_document.rb', line 49

def file_path
  @file_path
end

#grammar ⇒ Object (readonly)

Returns the value of attribute grammar.



49
50
51
 
# File 'lib/rhales/core/rue_document.rb', line 49

def grammar
  @grammar
end

Class Method Details

.parse_file(file_path) ⇒ Object

Raises:



329
330
331
332
333
334
 
# File 'lib/rhales/core/rue_document.rb', line 329

def parse_file(file_path)
  raise ArgumentError, 'Not a .rue file' unless rue_file?(file_path)

  file_content = File.read(file_path)
  new(file_content, file_path).parse!
end

.rue_file?(file_path) ⇒ Boolean

Returns:



336
337
338
 
# File 'lib/rhales/core/rue_document.rb', line 336

def rue_file?(file_path)
  File.extname(file_path) == '.rue'
end

Instance Method Details

#all_variables ⇒ Object 



186
187
188
 
# File 'lib/rhales/core/rue_document.rb', line 186

def all_variables
  template_variables.uniq
end

#convert_node_to_string(node) ⇒ Object 



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/rhales/core/rue_document.rb', line 79

def convert_node_to_string(node)
  case node.type
  when :text
    node.value
  when :variable_expression
    name = node.value[:name]
    raw  = node.value[:raw]
    raw ? "{{{#{name}}}}" : "{{#{name}}}"
  when :partial_expression
    "{{> #{node.value[:name]}}}"
  when :if_block
    condition    = node.value[:condition]
    if_content   = convert_nodes_to_string(node.value[:if_content])
    else_content = convert_nodes_to_string(node.value[:else_content])
    if else_content.empty?
      "{{#if #{condition}}}#{if_content}{{/if}}"
    else
      "{{#if #{condition}}}#{if_content}{{else}}#{else_content}{{/if}}"
    end
  when :unless_block
    condition = node.value[:condition]
    content   = convert_nodes_to_string(node.value[:content])
    "{{#unless #{condition}}}#{content}{{/unless}}"
  when :each_block
    items   = node.value[:items]
    content = convert_nodes_to_string(node.value[:content])
    "{{#each #{items}}}#{content}{{/each}}"
  when :handlebars_expression
    # Handle raw handlebars expressions
    if node.value[:raw]
      "{{{#{node.value[:content]}}}"
    else
      "{{#{node.value[:content]}}}"
    end
  else
    ''
  end
end

#convert_nodes_to_string(nodes) ⇒ Object 



75
76
77
 
# File 'lib/rhales/core/rue_document.rb', line 75

def convert_nodes_to_string(nodes)
  nodes.map { |node| convert_node_to_string(node) }.join
end

#extract_partials_from_content_nodes(content_nodes, partials) ⇒ Object (private) 



204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/rhales/core/rue_document.rb', line 204

def extract_partials_from_content_nodes(content_nodes, partials)
  content_nodes.each do |content_node|
    case content_node.type
    when :partial_expression
      partials << content_node.value[:name]
    when :if_block
      extract_partials_from_content_nodes(content_node.value[:if_content], partials)
      extract_partials_from_content_nodes(content_node.value[:else_content], partials)
    when :unless_block, :each_block
      extract_partials_from_content_nodes(content_node.value[:content], partials)
    when :handlebars_expression
      # Handle handlebars expressions
      content = content_node.value[:content]
      if content.start_with?('>')
        partials << content[1..].strip
      end
    end
  end
end

#extract_partials_from_node(_node, partials) ⇒ Object (private) 



192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/rhales/core/rue_document.rb', line 192

def extract_partials_from_node(_node, partials)
  return unless @ast

  # Extract from all sections
  @grammar.sections.each do |_section_name, section_node|
    content_nodes = section_node.value[:content]
    next unless content_nodes.is_a?(Array)

    extract_partials_from_content_nodes(content_nodes, partials)
  end
end

#extract_variables_from_content(content_nodes, variables, exclude_partials: false) ⇒ Object (private) 



234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/rhales/core/rue_document.rb', line 234

def extract_variables_from_content(content_nodes, variables, exclude_partials: false)
  return unless content_nodes.is_a?(Array)

  content_nodes.each do |node|
    case node.type
    when :variable_expression
      variables << node.value[:name]
    when :if_block
      variables << node.value[:condition]
      extract_variables_from_content(node.value[:if_content], variables, exclude_partials: exclude_partials)
      extract_variables_from_content(node.value[:else_content], variables, exclude_partials: exclude_partials)
    when :unless_block
      variables << node.value[:condition]
      extract_variables_from_content(node.value[:content], variables, exclude_partials: exclude_partials)
    when :each_block
      variables << node.value[:items]
      extract_variables_from_content(node.value[:content], variables, exclude_partials: exclude_partials)
    when :partial_expression
      # Skip partials if requested
      next if exclude_partials
    when :text
      # Extract handlebars expressions from text content
      extract_variables_from_text(node.value, variables, exclude_partials: exclude_partials)
    when :handlebars_expression
      # Handle handlebars expressions
      content = node.value[:content]

      # Skip partials if requested
      next if exclude_partials && content.start_with?('>')

      # Skip block helpers
      next if content.match?(%r{^(#|/)(if|unless|each|with)\s})

      variables << content.strip
    end
  end
end

#extract_variables_from_section(section_name, exclude_partials: false) ⇒ Object (private) 



224
225
226
227
228
229
230
231
232
 
# File 'lib/rhales/core/rue_document.rb', line 224

def extract_variables_from_section(section_name, exclude_partials: false)
  section_node = @grammar.sections[section_name]
  return [] unless section_node

  variables     = []
  content_nodes = section_node.value[:content]
  extract_variables_from_content(content_nodes, variables, exclude_partials: exclude_partials)
  variables.uniq
end

#extract_variables_from_text(text, variables, exclude_partials: false) ⇒ Object (private) 



272
273
274
275
276
277
278
279
280
281
282
283
284
285
 
# File 'lib/rhales/core/rue_document.rb', line 272

def extract_variables_from_text(text, variables, exclude_partials: false)
  # Find all handlebars expressions in text content
  text.scan(/\{\{(.+?)\}\}/) do |match|
    content = match[0].strip

    # Skip partials if requested
    next if exclude_partials && content.start_with?('>')

    # Skip block helpers
    next if content.match?(%r{^(#|/)(if|unless|each|with)\s})

    variables << content
  end
end

#layout ⇒ Object 



122
123
124
 
# File 'lib/rhales/core/rue_document.rb', line 122

def layout
  schema_attributes['layout']
end

#parse! ⇒ Object 



58
59
60
61
62
63
64
65
 
# File 'lib/rhales/core/rue_document.rb', line 58

def parse!
  @grammar.parse!
  @ast = @grammar.ast
  parse_data_attributes!
  self
rescue RueFormatParser::ParseError => ex
  raise ParseError, "Parser error: #{ex.message}"
end

#parse_data_attributes! ⇒ Object (private) 



287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
 
# File 'lib/rhales/core/rue_document.rb', line 287

def parse_data_attributes!
  schema_section = @grammar.sections['schema']
  @schema_attributes = {}

  if schema_section
    @schema_attributes = schema_section.value[:attributes].dup
    # Validate attributes and warn about unknown ones
    validate_schema_attributes!
    # Set default window attribute for schema section
    @schema_attributes['window'] ||= 'data'
    validate_window_attribute!

    # Schema sections require lang attribute
    unless @schema_attributes['lang']
      raise ParseError, "Schema section requires 'lang' attribute (e.g., lang=\"ts-zod\")"
    end
  end
end

#partials ⇒ Object 



174
175
176
177
178
179
180
 
# File 'lib/rhales/core/rue_document.rb', line 174

def partials
  return [] unless @ast

  partials = []
  extract_partials_from_node(@ast, partials)
  partials.uniq
end

#schema_attributes ⇒ Object

Schema section accessors



127
128
129
 
# File 'lib/rhales/core/rue_document.rb', line 127

def schema_attributes
  @schema_attributes ||= {}
end

#schema_envelope ⇒ Object 



139
140
141
 
# File 'lib/rhales/core/rue_document.rb', line 139

def schema_envelope
  schema_attributes['envelope']
end

#schema_extends ⇒ Object 



155
156
157
 
# File 'lib/rhales/core/rue_document.rb', line 155

def schema_extends
  schema_attributes['extends']
end

#schema_lang ⇒ Object 



131
132
133
 
# File 'lib/rhales/core/rue_document.rb', line 131

def schema_lang
  schema_attributes['lang']
end

#schema_layout ⇒ Object 



151
152
153
 
# File 'lib/rhales/core/rue_document.rb', line 151

def schema_layout
  schema_attributes['layout']
end

#schema_merge_strategy ⇒ Object 



147
148
149
 
# File 'lib/rhales/core/rue_document.rb', line 147

def schema_merge_strategy
  schema_attributes['merge']
end

#schema_src ⇒ Object

External schema file reference (optional) When present, schema code is loaded from this path instead of inline content



161
162
163
 
# File 'lib/rhales/core/rue_document.rb', line 161

def schema_src
  schema_attributes['src']
end

#schema_version ⇒ Object 



135
136
137
 
# File 'lib/rhales/core/rue_document.rb', line 135

def schema_version
  schema_attributes['version']
end

#schema_window ⇒ Object 



143
144
145
 
# File 'lib/rhales/core/rue_document.rb', line 143

def schema_window
  schema_attributes['window'] || 'data'
end

#section(name) ⇒ Object 



118
119
120
 
# File 'lib/rhales/core/rue_document.rb', line 118

def section(name)
  sections[name]
end

#section?(name) ⇒ Boolean

Returns:



165
166
167
 
# File 'lib/rhales/core/rue_document.rb', line 165

def section?(name)
  @grammar.sections.key?(name)
end

#section_node(name) ⇒ Object

Get the raw section node with location information



170
171
172
 
# File 'lib/rhales/core/rue_document.rb', line 170

def section_node(name)
  @grammar.sections[name]
end

#sections ⇒ Object 



67
68
69
70
71
72
73
 
# File 'lib/rhales/core/rue_document.rb', line 67

def sections
  return {} unless @ast

  @grammar.sections.transform_values do |section_node|
    convert_nodes_to_string(section_node.value[:content])
  end
end

#template_variables ⇒ Object 



182
183
184
 
# File 'lib/rhales/core/rue_document.rb', line 182

def template_variables
  extract_variables_from_section('template', exclude_partials: true)
end

#validate_schema_attributes! ⇒ Object (private) 



306
307
308
309
310
311
312
 
# File 'lib/rhales/core/rue_document.rb', line 306

def validate_schema_attributes!
  unknown_attributes = @schema_attributes.keys - KNOWN_SCHEMA_ATTRIBUTES

  unknown_attributes.each do |attr|
    warn_unknown_schema_attribute(attr)
  end
end

#validate_window_attribute! ⇒ Object (private)

Raises:



314
315
316
317
318
319
320
321
 
# File 'lib/rhales/core/rue_document.rb', line 314

def validate_window_attribute!
  window = @schema_attributes['window']
  return if window.is_a?(String) && window.match?(WINDOW_ATTRIBUTE_PATTERN)

  raise ParseError,
    "Invalid window attribute #{window.inspect}: must be a valid JavaScript " \
    "identifier matching #{WINDOW_ATTRIBUTE_PATTERN.source}"
end

#warn_unknown_schema_attribute(attribute) ⇒ Object (private) 



323
324
325
326
 
# File 'lib/rhales/core/rue_document.rb', line 323

def warn_unknown_schema_attribute(attribute)
  file_info = @file_path ? " in #{@file_path}" : ''
  warn "Warning: schema section encountered '#{attribute}' attribute - not yet supported, ignoring#{file_info}"
end