rhales 0.3.0

data/lib/rhales/parsers/rue_format_parser.rb

@@ -0,0 +1,385 @@
+# lib/rhales/parsers/rue_format_parser.rb
+
+require 'strscan'
+require_relative 'handlebars_parser'
+
+module Rhales
+  # Hand-rolled recursive descent parser for .rue files
+  #
+  # This parser implements .rue file parsing rules in Ruby code and produces
+  # an Abstract Syntax Tree (AST) for .rue file processing. It handles:
+  #
+  # - Section-based parsing: <data>, <template>, <logic>
+  # - Attribute extraction from section tags
+  # - Delegation to HandlebarsParser for template content
+  # - Validation of required sections
+  #
+  # Note: This class is a parser implementation, not a formal grammar definition.
+  # A formal grammar would be written in BNF/EBNF notation, while this class
+  # contains the actual parsing logic written in Ruby.
+  #
+  # File format structure:
+  # rue_file := section+
+  # section := '<' tag_name attributes? '>' content '</' tag_name '>'
+  # tag_name := 'data' | 'template' | 'logic'
+  # attributes := attribute+
+  # attribute := key '=' quoted_value
+  # content := (text | handlebars_expression)*
+  # handlebars_expression := '{{' expression '}}'
+  class RueFormatParser
+    # At least one of these sections must be present
+    REQUIRES_ONE_OF_SECTIONS = %w[data template].freeze
+    KNOWN_SECTIONS = %w[data template logic].freeze
+    ALL_SECTIONS = KNOWN_SECTIONS.freeze
+
+    # Regular expression to match HTML/XML comments outside of sections
+    COMMENT_REGEX = /<!--.*?-->/m
+
+    class ParseError < ::Rhales::ParseError
+      def initialize(message, line: nil, column: nil, offset: nil)
+        super(message, line: line, column: column, offset: offset, source_type: :rue)
+      end
+    end
+
+    class Node
+      attr_reader :type, :location, :children, :value
+
+      def initialize(type, location, value: nil, children: [])
+        @type     = type
+        @location = location
+        @value    = value
+        @children = children
+      end
+    end
+
+    class Location
+      attr_reader :start_line, :start_column, :end_line, :end_column, :start_offset, :end_offset
+
+      def initialize(start_line:, start_column:, end_line:, end_column:, start_offset:, end_offset:)
+        @start_line   = start_line
+        @start_column = start_column
+        @end_line     = end_line
+        @end_column   = end_column
+        @start_offset = start_offset
+        @end_offset   = end_offset
+      end
+    end
+
+    def initialize(content, file_path = nil)
+      @content   = preprocess_content(content)
+      @file_path = file_path
+      @position  = 0
+      @line      = 1
+      @column    = 1
+      @ast       = nil
+    end
+
+    def parse!
+      @ast = parse_rue_file
+      validate_ast!
+      self
+    end
+
+    attr_reader :ast
+
+    def sections
+      return {} unless @ast
+
+      @ast.children.each_with_object({}) do |section_node, sections|
+        sections[section_node.value[:tag]] = section_node
+      end
+    end
+
+    private
+
+    def parse_rue_file
+      sections = []
+
+      until at_end?
+        skip_whitespace
+        break if at_end?
+
+        sections << parse_section
+      end
+
+      if sections.empty?
+        raise ParseError.new('Empty .rue file', line: @line, column: @column, offset: @position)
+      end
+
+      Node.new(:rue_file, current_location, children: sections)
+    end
+
+    def parse_section
+      start_pos = current_position
+
+      # Parse opening tag
+      consume('<') || parse_error("Expected '<' to start section")
+      tag_name   = parse_tag_name
+      attributes = parse_attributes
+      consume('>') || parse_error("Expected '>' to close opening tag")
+
+      # Parse content
+      content = parse_section_content(tag_name)
+
+      # Parse closing tag
+      consume("</#{tag_name}>") || parse_error("Expected '</#{tag_name}>' to close section")
+
+      end_pos  = current_position
+      location = Location.new(
+        start_line: start_pos[:line],
+        start_column: start_pos[:column],
+        end_line: end_pos[:line],
+        end_column: end_pos[:column],
+        start_offset: start_pos[:offset],
+        end_offset: end_pos[:offset],
+      )
+
+      Node.new(:section, location, value: {
+        tag: tag_name,
+        attributes: attributes,
+        content: content,
+      }
+      )
+    end
+
+    def parse_tag_name
+      start_pos = @position
+
+      advance while !at_end? && current_char.match?(/[a-zA-Z]/)
+
+      if start_pos == @position
+        parse_error('Expected tag name')
+      end
+
+      @content[start_pos...@position]
+    end
+
+    def parse_attributes
+      attributes = {}
+
+      while !at_end? && current_char != '>'
+        skip_whitespace
+        break if current_char == '>'
+
+        # Parse attribute name
+        attr_name = parse_identifier
+        skip_whitespace
+
+        consume('=') || parse_error("Expected '=' after attribute name")
+        skip_whitespace
+
+        # Parse attribute value
+        attr_value            = parse_quoted_string
+        attributes[attr_name] = attr_value
+
+        skip_whitespace
+      end
+
+      attributes
+    end
+
+    def parse_section_content(tag_name)
+      start_pos     = @position
+      content_start = @position
+
+      # Extract the raw content between section tags
+      raw_content = ''
+      while !at_end? && !peek_closing_tag?(tag_name)
+        raw_content << current_char
+        advance
+      end
+
+      # For template sections, use HandlebarsParser to parse the content
+      if tag_name == 'template'
+        handlebars_parser = HandlebarsParser.new(raw_content)
+        handlebars_parser.parse!
+        handlebars_parser.ast.children
+      else
+        # For data and logic sections, keep as simple text
+        return [Node.new(:text, current_location, value: raw_content)] unless raw_content.empty?
+
+        []
+      end
+    end
+
+    def parse_quoted_string
+      quote_char = current_char
+      unless ['"', "'"].include?(quote_char)
+        parse_error('Expected quoted string')
+      end
+
+      advance # Skip opening quote
+      value = ''
+
+      while !at_end? && current_char != quote_char
+        value << current_char
+        advance
+      end
+
+      consume(quote_char) || parse_error('Unterminated quoted string')
+      value
+    end
+
+    def parse_identifier
+      start_pos = @position
+
+      advance while !at_end? && current_char.match?(/[a-zA-Z0-9_]/)
+
+      if start_pos == @position
+        parse_error('Expected identifier')
+      end
+
+      @content[start_pos...@position]
+    end
+
+    def peek_closing_tag?(tag_name)
+      peek_string?("</#{tag_name}>")
+    end
+
+    def peek_string?(string)
+      @content[@position, string.length] == string
+    end
+
+    def consume(expected)
+      if peek_string?(expected)
+        expected.length.times { advance }
+        true
+      else
+        false
+      end
+    end
+
+    def current_char
+      return "\0" if at_end?
+
+      @content[@position]
+    end
+
+    def peek_char
+      return "\0" if @position + 1 >= @content.length
+
+      @content[@position + 1]
+    end
+
+    def advance
+      if current_char == "\n"
+        @line  += 1
+        @column = 1
+      else
+        @column += 1
+      end
+      @position += 1
+    end
+
+    def at_end?
+      @position >= @content.length
+    end
+
+    def skip_whitespace
+      advance while !at_end? && current_char.match?(/\s/)
+    end
+
+    def current_position
+      { line: @line, column: @column, offset: @position }
+    end
+
+    def current_location
+      pos = current_position
+      Location.new(
+        start_line: pos[:line],
+        start_column: pos[:column],
+        end_line: pos[:line],
+        end_column: pos[:column],
+        start_offset: pos[:offset],
+        end_offset: pos[:offset],
+      )
+    end
+
+    def validate_ast!
+      sections = @ast.children.map { |node| node.value[:tag] }
+
+      # Check that at least one required section is present
+      required_present = REQUIRES_ONE_OF_SECTIONS & sections
+      if required_present.empty?
+        raise ParseError.new("Must have at least one of: #{REQUIRES_ONE_OF_SECTIONS.join(', ')}", line: 1, column: 1)
+      end
+
+      # Check for duplicates
+      duplicates = sections.select { |tag| sections.count(tag) > 1 }.uniq
+      if duplicates.any?
+        raise ParseError.new("Duplicate sections: #{duplicates.join(', ')}", line: 1, column: 1)
+      end
+
+      # Check for unknown sections
+      unknown = sections - KNOWN_SECTIONS
+      if unknown.any?
+        raise ParseError.new("Unknown sections: #{unknown.join(', ')}", line: 1, column: 1)
+      end
+    end
+
+    def parse_error(message)
+      raise ParseError.new(message, line: @line, column: @column, offset: @position)
+    end
+
+    # Preprocess content to strip XML/HTML comments outside of sections
+    # Uses Ruby 3.4+ pattern matching for robust, secure parsing
+    def preprocess_content(content)
+      tokens = tokenize_content(content)
+
+      # Use pattern matching to filter out comments outside sections
+      result_parts = []
+      in_section = false
+
+      tokens.each do |token|
+        case token
+        in { type: :comment } unless in_section
+          # Skip comments outside sections
+          next
+        in { type: :section_start }
+          in_section = true
+          result_parts << token[:content]
+        in { type: :section_end }
+          in_section = false
+          result_parts << token[:content]
+        in { type: :comment | :text, content: content }
+          # Include comments inside sections and all text
+          result_parts << content
+        end
+      end
+
+      result_parts.join
+    end
+
+    private
+
+    # Tokenize content into structured tokens for pattern matching
+    # Uses StringScanner for better performance and cleaner code
+    def tokenize_content(content)
+      scanner = StringScanner.new(content)
+      tokens = []
+
+      until scanner.eos?
+        case
+        when scanner.scan(/<!--.*?-->/m)
+          # Comment token - non-greedy match for complete comments
+          tokens << { type: :comment, content: scanner.matched }
+        when scanner.scan(/<(data|template|logic)(\s[^>]*)?>/m)
+          # Section start token - matches opening tags with optional attributes
+          tokens << { type: :section_start, content: scanner.matched }
+        when scanner.scan(/<\/(data|template|logic)>/m)
+          # Section end token - matches closing tags
+          tokens << { type: :section_end, content: scanner.matched }
+        when scanner.scan(/[^<]+/)
+          # Text token - consolidates runs of non-< characters for efficiency
+          tokens << { type: :text, content: scanner.matched }
+        else
+          # Fallback for single characters (< that don't match patterns)
+          # This maintains compatibility with the original character-by-character behavior
+          tokens << { type: :text, content: scanner.getch }
+        end
+      end
+
+      tokens
+    end
+  end
+end

data/lib/rhales/refinements/require_refinements.rb

@@ -0,0 +1,236 @@
+# lib/rhales/refinements/require_refinements.rb
+
+require_relative '../rue_document'
+
+module Rhales
+  module Ruequire
+    # Thread-safe cache for parsed RSFC templates
+    @rsfc_cache     = {}
+    @file_watchers  = {}
+    @cache_mutex    = Mutex.new
+    @watchers_mutex = Mutex.new
+
+    class << self
+      # Thread-safe access to cache
+      def rsfc_cache
+        @cache_mutex.synchronize { @rsfc_cache.dup }
+      end
+
+      # Thread-safe access to file watchers
+      def file_watchers
+        @watchers_mutex.synchronize { @file_watchers.dup }
+      end
+
+      # Clear cache (useful for development and testing)
+      def clear_cache!
+        @cache_mutex.synchronize { @rsfc_cache.clear }
+        cleanup_file_watchers!
+      end
+
+      # Stop all file watchers and clean up resources
+      def cleanup_file_watchers!
+        @watchers_mutex.synchronize do
+          @file_watchers.each_value do |watcher_thread|
+            next unless watcher_thread.is_a?(Thread) && watcher_thread.alive?
+
+            watcher_thread.kill
+            begin
+              watcher_thread.join(1) # Wait up to 1 second for clean shutdown
+            rescue StandardError
+              # Thread might already be dead, ignore errors
+            end
+          end
+          @file_watchers.clear
+        end
+      end
+
+      # Stop watching a specific file
+      def stop_watching_file!(full_path)
+        @watchers_mutex.synchronize do
+          watcher_thread = @file_watchers.delete(full_path)
+          if watcher_thread.is_a?(Thread) && watcher_thread.alive?
+            watcher_thread.kill
+            begin
+              watcher_thread.join(1)
+            rescue StandardError
+              # Thread cleanup error, ignore
+            end
+          end
+        end
+      end
+
+      # Enable development mode file watching
+      def enable_file_watching!
+        @file_watching_enabled = true
+      end
+
+      # Disable file watching
+      def disable_file_watching!
+        @file_watching_enabled = false
+      end
+
+      def file_watching_enabled?
+        @file_watching_enabled ||= false
+      end
+    end
+
+    # Ensure cleanup on program exit
+    at_exit do
+      if defined?(Rhales::Ruequire)
+        Rhales::Ruequire.cleanup_file_watchers!
+      end
+    end
+
+    refine Kernel do
+      def require(path)
+        return process_rue(path) if path.end_with?('.rue')
+
+        super
+      end
+
+      def process_rue(path)
+        # Resolve full path
+        full_path = resolve_rue_path(path)
+
+        unless File.exist?(full_path)
+          raise LoadError, "cannot load such file -- #{path} (resolved to #{full_path})"
+        end
+
+        # Check cache first
+        cached_parser = get_cached_parser(full_path)
+        return cached_parser if cached_parser
+
+        # Parse the .rue file
+        parser = Rhales::RueDocument.parse_file(full_path)
+
+        # Cache the parsed result
+        cache_parser(full_path, parser)
+
+        # Set up file watching in development mode
+        setup_file_watching(full_path) if Rhales::Ruequire.file_watching_enabled?
+
+        parser
+      rescue StandardError => ex
+        if defined?(OT) && OT.respond_to?(:le)
+          OT.le "[RSFC] Failed to process .rue file #{path}: #{ex.message}"
+        else
+          puts "[RSFC] Failed to process .rue file #{path}: #{ex.message}"
+        end
+        raise
+      end
+
+      private
+
+      # Resolve .rue file path
+      def resolve_rue_path(path)
+        # If path is absolute and exists, use it
+        return path if path.start_with?('/') && File.exist?(path)
+
+        # If path is relative and exists in current directory
+        return File.expand_path(path) if File.exist?(path)
+
+        # Search in templates directory
+        boot_root      = defined?(OT) && OT.respond_to?(:boot_root) ? OT.boot_root : File.expand_path('../../..', __dir__)
+        templates_path = File.join(boot_root, 'templates', path)
+        return templates_path if File.exist?(templates_path)
+
+        # Search in templates/web directory
+        web_templates_path = File.join(boot_root, 'templates', 'web', path)
+        return web_templates_path if File.exist?(web_templates_path)
+
+        # If path doesn't have .rue extension, add it and try again
+        unless path.end_with?('.rue')
+          return resolve_rue_path("#{path}.rue")
+        end
+
+        # Return original path (will cause file not found error)
+        path
+      end
+
+      # Get parser from cache if available and not stale
+      def get_cached_parser(full_path)
+        Rhales::Ruequire.instance_variable_get(:@cache_mutex).synchronize do
+          cache_entry = Rhales::Ruequire.instance_variable_get(:@rsfc_cache)[full_path]
+          return nil unless cache_entry
+
+          # Check if file has been modified
+          if File.mtime(full_path) > cache_entry[:mtime]
+            # File modified, remove from cache
+            Rhales::Ruequire.instance_variable_get(:@rsfc_cache).delete(full_path)
+            return nil
+          end
+
+          cache_entry[:parser]
+        end
+      end
+
+      # Cache parsed parser with modification time
+      def cache_parser(full_path, parser)
+        Rhales::Ruequire.instance_variable_get(:@cache_mutex).synchronize do
+          Rhales::Ruequire.instance_variable_get(:@rsfc_cache)[full_path] = {
+            parser: parser,
+            mtime: File.mtime(full_path),
+          }
+        end
+      end
+
+      # Set up file watching for development mode
+      def setup_file_watching(full_path)
+        # Check if already watching in a thread-safe way
+        watchers_mutex      = Rhales::Ruequire.instance_variable_get(:@watchers_mutex)
+        is_already_watching = watchers_mutex.synchronize do
+          Rhales::Ruequire.instance_variable_get(:@file_watchers)[full_path]
+        end
+
+        return if is_already_watching
+
+        # Simple polling-based file watching
+        # In a production system, you might want to use a more sophisticated
+        # file watching library like Listen or rb-inotify
+        watcher_thread = Thread.new do
+          last_mtime = File.mtime(full_path)
+
+          loop do
+            sleep 1 # Check every second
+
+            begin
+              current_mtime = File.mtime(full_path)
+
+              if current_mtime > last_mtime
+                if defined?(OT) && OT.respond_to?(:ld)
+                  OT.ld "[RSFC] File changed, clearing cache: #{full_path}"
+                end
+
+                # Thread-safe cache removal
+                Rhales::Ruequire.instance_variable_get(:@cache_mutex).synchronize do
+                  Rhales::Ruequire.instance_variable_get(:@rsfc_cache).delete(full_path)
+                end
+
+                last_mtime = current_mtime
+              end
+            rescue StandardError => ex
+              # File might have been deleted
+              if defined?(OT) && OT.respond_to?(:ld)
+                OT.ld "[RSFC] File watcher error for #{full_path}: #{ex.message}"
+              end
+
+              # Clean up watcher entry on error
+              watchers_mutex.synchronize do
+                Rhales::Ruequire.instance_variable_get(:@file_watchers).delete(full_path)
+              end
+              break
+            end
+          end
+        end
+
+        # Set thread as daemon so it doesn't prevent program exit
+        watcher_thread.thread_variable_set(:daemon, true)
+
+        # Mark as being watched
+        watchers_mutex.synchronize do
+          Rhales::Ruequire.instance_variable_get(:@file_watchers)[full_path] = watcher_thread
+        end
+      end
+    end
+  end
+end