moxml 0.1.7 → 0.1.9

data/examples/web_scraper/web_scraper.rb

@@ -0,0 +1,312 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Web Scraper Example
+# This example demonstrates how to use Moxml to scrape data from HTML/XML:
+# - Parsing HTML as XML
+# - Extracting data from tables
+# - DOM structure navigation
+# - Attribute and text content access
+# - Working with structured data
+
+# Load moxml from the local source (use 'require "moxml"' in production)
+require_relative "../../lib/moxml"
+
+# Language class to represent programming language data
+class Language
+  attr_reader :rank, :name, :category, :score, :year, :use_cases
+
+  def initialize(rank:, name:, category:, score:, year:, use_cases:)
+    @rank = rank.to_i
+    @name = name
+    @category = category
+    @score = score.to_f
+    @year = year.to_i
+    @use_cases = use_cases
+  end
+
+  def to_s
+    "#{@rank}. #{@name} (#{@category}) - #{@score}% | Created: #{@year} | Uses: #{@use_cases}"
+  end
+end
+
+# CategoryStats class to represent category statistics
+class CategoryStats
+  attr_reader :name, :count, :avg_score, :top_language
+
+  def initialize(name:, count:, avg_score:, top_language:)
+    @name = name
+    @count = count.to_i
+    @avg_score = avg_score
+    @top_language = top_language
+  end
+
+  def to_s
+    "#{@name}: #{@count} languages, avg #{@avg_score}, top: #{@top_language}"
+  end
+end
+
+# WebScraper class encapsulates web scraping logic
+class WebScraper
+  # Initialize with the path to an HTML file
+  def initialize(html_path)
+    @html_path = html_path
+    @moxml = Moxml.new
+  end
+
+  # Scrape the HTML page and extract all data
+  def scrape
+    # Read and parse the HTML file
+    html_content = File.read(@html_path)
+
+    # Parse HTML as XML (Moxml can handle well-formed HTML)
+    doc = begin
+      @moxml.parse(html_content)
+    rescue Moxml::ParseError => e
+      puts "Failed to parse HTML: #{e.message}"
+      puts "Hint: Ensure the HTML is well-formed XML"
+      exit 1
+    end
+
+    puts "=" * 80
+    puts "Programming Language Statistics Scraper"
+    puts "=" * 80
+    puts
+
+    # Extract page title
+    title = extract_page_title(doc)
+    puts "Page Title: #{title}\n\n"
+
+    # Extract summary information
+    summary = extract_summary(doc)
+    puts "Summary:"
+    puts "  #{summary[:total]} total languages tracked"
+    puts "  Last updated: #{summary[:updated]}\n\n"
+
+    # Extract language data from the main table
+    languages = extract_languages_table(doc)
+    puts "Languages Extracted: #{languages.length}"
+    puts "-" * 80
+    languages.each { |lang| puts lang }
+    puts
+
+    # Extract category statistics
+    categories = extract_category_stats(doc)
+    puts "\nCategory Statistics:"
+    puts "-" * 80
+    categories.each { |cat| puts cat }
+    puts
+
+    # Extract detailed information
+    details = extract_detailed_info(doc)
+    puts "\nDetailed Information:"
+    puts "-" * 80
+    details.each do |lang, info|
+      puts "#{lang}:"
+      info.each { |key, value| puts "  #{key}: #{value}" }
+      puts
+    end
+
+    # Return structured data
+    {
+      title: title,
+      summary: summary,
+      languages: languages,
+      categories: categories,
+      details: details,
+    }
+  end
+
+  private
+
+  # Extract the page title from <title> element
+  def extract_page_title(doc)
+    # Find the title element using XPath
+    # The double slash (//) searches from the root
+    title_element = doc.at_xpath("//title")
+    title_element&.text&.strip || "Unknown Title"
+  end
+
+  # Extract summary statistics from the summary card
+  def extract_summary(doc)
+    # Find the summary div by id attribute
+    # XPath attribute selector: [@id='value']
+    summary_div = doc.at_xpath("//div[@id='summary']")
+
+    return { total: 0, updated: "Unknown" } unless summary_div
+
+    # Extract text from span elements with class 'stat-value'
+    # Using XPath class selector: [contains(@class, 'value')]
+    stats = summary_div.xpath(".//span[@class='stat-value']")
+
+    {
+      total: stats[0]&.text&.strip || "0",
+      updated: stats[1]&.text&.strip || "Unknown",
+    }
+  end
+
+  # Extract language data from the popularity table
+  def extract_languages_table(doc)
+    # Find the table by id
+    table = doc.at_xpath("//table[@id='popularity-table']")
+    return [] unless table
+
+    # Get all table body rows
+    # Using descendant axis to find tbody/tr elements
+    rows = table.xpath(".//tbody/tr")
+
+    # Parse each row into a Language object
+    rows.filter_map do |row|
+      # Get all td (cell) elements in this row
+      cells = row.xpath("./td")
+
+      # Skip if we don't have enough cells
+      next nil if cells.length < 6
+
+      # Extract data from each cell
+      # Using array indexing for predictable table structure
+      rank = cells[0].text.strip
+      name = cells[1].text.strip
+      category = cells[2].text.strip
+
+      # Access data-score attribute for the score
+      # Demonstrates attribute access with []
+      score = cells[3]["data-score"] || cells[3].text.strip.delete("%")
+
+      year = cells[4].text.strip
+      use_cases = cells[5].text.strip
+
+      Language.new(
+        rank: rank,
+        name: name,
+        category: category,
+        score: score,
+        year: year,
+        use_cases: use_cases,
+      )
+    end
+  end
+
+  # Extract category statistics from the category table
+  def extract_category_stats(doc)
+    # Find the category table
+    table = doc.at_xpath("//table[@id='category-table']")
+    return [] unless table
+
+    # Get table rows
+    rows = table.xpath(".//tbody/tr")
+
+    rows.filter_map do |row|
+      cells = row.xpath("./td")
+      next nil if cells.length < 4
+
+      CategoryStats.new(
+        name: cells[0].text.strip,
+        count: cells[1].text.strip,
+        avg_score: cells[2].text.strip,
+        top_language: cells[3].text.strip,
+      )
+    end
+  end
+
+  # Extract detailed language information from stats cards
+  def extract_detailed_info(doc)
+    # Find all divs with class 'stats-card' that have a data-language attribute
+    # This demonstrates combining class and attribute selectors
+    cards = doc.xpath("//div[contains(@class, 'stats-card') and @data-language]")
+
+    cards.each_with_object({}) do |card, hash|
+      # Get the language name from the data-language attribute
+      lang_name = card["data-language"]
+
+      # Extract all list items within this card
+      items = card.xpath(".//li")
+
+      # Parse each list item to extract key-value pairs
+      info = items.each_with_object({}) do |item, item_hash|
+        text = item.text.strip
+        # Simple parsing: split on first colon
+        if text.include?(":")
+          key, value = text.split(":", 2)
+          item_hash[key.strip] = value.strip
+        end
+      end
+
+      hash[lang_name] = info unless info.empty?
+    end
+  end
+end
+
+# Demonstration of various XPath patterns
+def demonstrate_xpath_patterns(doc)
+  puts "\n#{'=' * 80}"
+  puts "XPath Pattern Demonstrations"
+  puts "=" * 80
+
+  # Pattern 1: Direct descendant
+  puts "\n1. All table headers (//th):"
+  headers = doc.xpath("//th")
+  puts "   Found #{headers.length} headers: #{headers.map(&:text).join(', ')}"
+
+  # Pattern 2: Attribute selector
+  puts "\n2. Elements with data-language attribute (//tr[@data-language]):"
+  lang_rows = doc.xpath("//tr[@data-language]")
+  langs = lang_rows.map { |row| row["data-language"] }
+  puts "   Found #{langs.length} languages: #{langs.join(', ')}"
+
+  # Pattern 3: Class contains
+  puts "\n3. Elements with 'language-name' class:"
+  names = doc.xpath("//*[contains(@class, 'language-name')]")
+  puts "   Found #{names.length} elements: #{names.map(&:text).join(', ')}"
+
+  # Pattern 4: Combining conditions
+  puts "\n4. Table cells with data-score > 80:"
+  high_scores = doc.xpath("//td[@data-score]").select do |cell|
+    cell["data-score"].to_f > 80
+  end
+  puts "   Found #{high_scores.length} high scores"
+
+  # Pattern 5: Navigation axes
+  puts "\n5. Parent elements of language names:"
+  first_name = doc.at_xpath("//td[@class='language-name']")
+  if first_name
+    parent_row = first_name.parent
+    puts "   Parent tag: #{parent_row.name}"
+    puts "   Parent has #{parent_row.children.length} children"
+  end
+
+  puts "=" * 80
+end
+
+# Main execution
+if __FILE__ == $0
+  # Get the HTML path (use example page by default)
+  html_path = ARGV[0] || File.join(__dir__, "example_page.html")
+
+  # Check if file exists
+  unless File.exist?(html_path)
+    puts "Error: HTML file not found: #{html_path}"
+    puts "Usage: ruby web_scraper.rb [path/to/page.html]"
+    exit 1
+  end
+
+  puts "Scraping HTML page: #{html_path}\n"
+
+  # Scrape the page
+  scraper = WebScraper.new(html_path)
+  data = scraper.scrape
+
+  # Demonstrate various XPath patterns
+  doc = Moxml.new.parse(File.read(html_path))
+  demonstrate_xpath_patterns(doc)
+
+  # Summary
+  puts "\n#{'=' * 80}"
+  puts "Scraping Complete!"
+  puts "=" * 80
+  puts "Extracted:"
+  puts "  - #{data[:languages].length} programming languages"
+  puts "  - #{data[:categories].length} category statistics"
+  puts "  - #{data[:details].length} detailed information entries"
+  puts "=" * 80
+end

data/lib/moxml/adapter/base.rb

@@ -11,16 +11,54 @@ module Moxml
       class << self
         include XmlUtils
 
-        def set_root(doc, element)
-          raise NotImplementedError
-        end
-
-        def parse(xml, options = {})
-          raise NotImplementedError
-        end
-
-        def create_document(native_doc = nil)
-          raise NotImplementedError
+        def set_root(_doc, _element)
+          raise Moxml::NotImplementedError.new(
+            "set_root not implemented",
+            feature: "set_root",
+            adapter: name,
+          )
+        end
+
+        def parse(_xml, _options = {})
+          raise Moxml::NotImplementedError.new(
+            "parse not implemented",
+            feature: "parse",
+            adapter: name,
+          )
+        end
+
+        # Parse XML using SAX (event-driven) parsing
+        #
+        # SAX parsing provides a memory-efficient way to process XML
+        # by triggering events as the document is parsed, rather than
+        # building a complete DOM tree.
+        #
+        # @param xml [String, IO] XML string or IO object to parse
+        # @param handler [Moxml::SAX::Handler] Handler object receiving events
+        # @return [void]
+        # @raise [Moxml::NotImplementedError] if adapter doesn't support SAX
+        def sax_parse(_xml, _handler)
+          raise Moxml::NotImplementedError.new(
+            "sax_parse not implemented",
+            feature: "sax_parse",
+            adapter: name,
+          )
+        end
+
+        # Check if this adapter supports SAX parsing
+        #
+        # @return [Boolean] true if SAX parsing is supported
+        def sax_supported?
+          respond_to?(:sax_parse) &&
+            method(:sax_parse).owner != Moxml::Adapter::Base.singleton_class
+        end
+
+        def create_document(_native_doc = nil)
+          raise Moxml::NotImplementedError.new(
+            "create_document not implemented",
+            feature: "create_document",
+            adapter: name,
+          )
         end
 
         def create_element(name)
@@ -48,10 +86,12 @@ module Moxml
 
         def create_processing_instruction(target, content)
           validate_pi_target(target)
-          create_native_processing_instruction(target, normalize_xml_value(content))
+          create_native_processing_instruction(target,
+                                               normalize_xml_value(content))
         end
 
-        def create_declaration(version = "1.0", encoding = "UTF-8", standalone = nil)
+        def create_declaration(version = "1.0", encoding = "UTF-8",
+                               standalone = nil)
           validate_declaration_version(version)
           validate_declaration_encoding(encoding)
           validate_declaration_standalone(standalone)
@@ -81,38 +121,77 @@ module Moxml
           node
         end
 
+        def prepare_for_new_document(node, _target_doc)
+          # Hook for adapters that need special handling when moving nodes
+          # between documents (e.g., LibXML's document.import)
+          # Default: no-op for backward compatibility
+          node
+        end
+
         protected
 
-        def create_native_element(name)
-          raise NotImplementedError
+        def create_native_element(_name)
+          raise Moxml::NotImplementedError.new(
+            "create_native_element not implemented",
+            feature: "create_native_element",
+            adapter: name,
+          )
         end
 
-        def create_native_text(content)
-          raise NotImplementedError
+        def create_native_text(_content)
+          raise Moxml::NotImplementedError.new(
+            "create_native_text not implemented",
+            feature: "create_native_text",
+            adapter: name,
+          )
         end
 
-        def create_native_cdata(content)
-          raise NotImplementedError
+        def create_native_cdata(_content)
+          raise Moxml::NotImplementedError.new(
+            "create_native_cdata not implemented",
+            feature: "create_native_cdata",
+            adapter: name,
+          )
         end
 
-        def create_native_comment(content)
-          raise NotImplementedError
+        def create_native_comment(_content)
+          raise Moxml::NotImplementedError.new(
+            "create_native_comment not implemented",
+            feature: "create_native_comment",
+            adapter: name,
+          )
         end
 
-        def create_native_doctype(name, external_id, system_id)
-          raise NotImplementedError
+        def create_native_doctype(_name, _external_id, _system_id)
+          raise Moxml::NotImplementedError.new(
+            "create_native_doctype not implemented",
+            feature: "create_native_doctype",
+            adapter: name,
+          )
         end
 
-        def create_native_processing_instruction(target, content)
-          raise NotImplementedError
+        def create_native_processing_instruction(_target, _content)
+          raise Moxml::NotImplementedError.new(
+            "create_native_processing_instruction not implemented",
+            feature: "create_native_processing_instruction",
+            adapter: name,
+          )
         end
 
-        def create_native_declaration(version, encoding, standalone)
-          raise NotImplementedError
+        def create_native_declaration(_version, _encoding, _standalone)
+          raise Moxml::NotImplementedError.new(
+            "create_native_declaration not implemented",
+            feature: "create_native_declaration",
+            adapter: name,
+          )
         end
 
-        def create_native_namespace(element, prefix, uri)
-          raise NotImplementedError
+        def create_native_namespace(_element, _prefix, _uri)
+          raise Moxml::NotImplementedError.new(
+            "create_native_namespace not implemented",
+            feature: "create_native_namespace",
+            adapter: name,
+          )
         end
       end
     end

data/lib/moxml/adapter/customized_libxml/cdata.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "node"
+
+module Moxml
+  module Adapter
+    module CustomizedLibxml
+      # Wrapper for LibXML CDATA section nodes
+      class Cdata < Node
+        # Serialize as XML CDATA section
+        # LibXML auto-escapes content, we need to un-escape it
+        def to_xml
+          content = @native.content
+            .gsub("&quot;", '"')
+            .gsub("&apos;", "'")
+            .gsub("&lt;", "<")
+            .gsub("&gt;", ">")
+            .gsub("&amp;", "&")
+
+          # Handle CDATA end marker escaping (]]> becomes ]]]]><![CDATA[>)
+          # Replace all ]]> markers in the content before wrapping
+          escaped_content = content.gsub("]]>", "]]]]><![CDATA[>")
+          "<![CDATA[#{escaped_content}]]>"
+        end
+      end
+    end
+  end
+end

data/lib/moxml/adapter/customized_libxml/comment.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "node"
+
+module Moxml
+  module Adapter
+    module CustomizedLibxml
+      # Wrapper for LibXML comment nodes
+      class Comment < Node
+        # Serialize as XML comment
+        # LibXML auto-escapes content, we need to un-escape it
+        def to_xml
+          content = @native.content
+            .gsub("&quot;", '"')
+            .gsub("&apos;", "'")
+            .gsub("&lt;", "<")
+            .gsub("&gt;", ">")
+            .gsub("&amp;", "&")
+          "<!--#{content}-->"
+        end
+      end
+    end
+  end
+end

data/lib/moxml/adapter/customized_libxml/declaration.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Adapter
+    module CustomizedLibxml
+      # Wrapper for LibXML document declarations
+      #
+      # LibXML::XML::Document properties (version, encoding, standalone)
+      # are read-only after creation. This wrapper allows mutation by
+      # storing values internally and regenerating XML when needed.
+      class Declaration
+        attr_accessor :version, :encoding
+        attr_reader :native
+
+        def initialize(native_doc, version = nil, encoding = nil,
+                       standalone = nil)
+          @native = native_doc
+          # Store explicit values - don't default from native_doc
+          @version = version || native_doc.version || "1.0"
+          # Only use encoding if explicitly provided, otherwise nil
+          @encoding = encoding
+          # Parse standalone value
+          @standalone_value = case standalone
+                              when "yes", true
+                                true
+                              when "no", false
+                                false
+                              end
+        end
+
+        def standalone
+          return nil if @standalone_value.nil?
+
+          @standalone_value ? "yes" : "no"
+        end
+
+        def standalone=(value)
+          @standalone_value = case value
+                              when "yes", true
+                                true
+                              when "no", false
+                                false
+                              when nil
+                                nil
+                              end
+        end
+
+        # Generate XML declaration string
+        def to_xml
+          output = "<?xml version=\"#{@version}\""
+          if @encoding && !@encoding.empty?
+            output << " encoding=\"#{@encoding}\""
+          end
+          # Include standalone attribute if explicitly set (true or false)
+          unless @standalone_value.nil?
+            output << " standalone=\"#{standalone}\""
+          end
+          output << "?>"
+          output
+        end
+
+        private
+
+        def extract_encoding(libxml_encoding)
+          return nil unless libxml_encoding
+
+          case libxml_encoding
+          when ::LibXML::XML::Encoding::UTF_8
+            "UTF-8"
+          when ::LibXML::XML::Encoding::ISO_8859_1
+            "ISO-8859-1"
+          when ::LibXML::XML::Encoding::UTF_16LE
+            "UTF-16LE"
+          when ::LibXML::XML::Encoding::UTF_16BE
+            "UTF-16BE"
+          when ::LibXML::XML::Encoding::UCS_2
+            "UCS-2"
+          else
+            "UTF-8"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/moxml/adapter/customized_libxml/element.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "node"
+
+module Moxml
+  module Adapter
+    module CustomizedLibxml
+      # Wrapper for LibXML element nodes
+      #
+      # This wrapper provides automatic document import when adding children,
+      # solving LibXML's strict document ownership requirement.
+      class Element < Node
+        # Add a child to this element, handling document import automatically
+        def add_child(child)
+          child_native = child.respond_to?(:native) ? child.native : child
+
+          # Check if child needs to be imported
+          if needs_import?(child_native)
+            imported = @native.doc.import(child_native)
+            @native << imported
+          else
+            @native << child_native
+          end
+        end
+
+        private
+
+        def needs_import?(child_node)
+          return false unless @native.respond_to?(:doc)
+          return false unless @native.doc
+          return false unless child_node.respond_to?(:doc)
+          return false unless child_node.doc
+
+          child_node.doc != @native.doc
+        end
+      end
+    end
+  end
+end