moxml 0.1.6 → 0.1.8

data/examples/api_client/api_client.rb

@@ -0,0 +1,394 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# API Client Example
+# This example demonstrates how to use Moxml for API interactions:
+# - Building XML API requests (SOAP)
+# - Parsing XML API responses
+# - Handling authentication elements
+# - Working with namespaces
+# - Error handling and validation
+
+# Load moxml from the local source (use 'require "moxml"' in production)
+require_relative "../../lib/moxml"
+require "securerandom"
+require "time"
+
+# User class to represent API user data
+class User
+  attr_reader :id, :username, :email, :full_name, :role, :status,
+              :created_at, :last_login, :permissions, :profile
+
+  def initialize(data)
+    @id = data[:id]
+    @username = data[:username]
+    @email = data[:email]
+    @full_name = data[:full_name]
+    @role = data[:role]
+    @status = data[:status]
+    @created_at = data[:created_at]
+    @last_login = data[:last_login]
+    @permissions = data[:permissions] || []
+    @profile = data[:profile] || {}
+  end
+
+  def to_s
+    output = []
+    output << "User ID: #{@id}"
+    output << "Username: #{@username}"
+    output << "Email: #{@email}"
+    output << "Full Name: #{@full_name}"
+    output << "Role: #{@role}"
+    output << "Status: #{@status}"
+    output << "Created: #{@created_at}"
+    output << "Last Login: #{@last_login}"
+    output << "Permissions: #{@permissions.join(', ')}"
+    output << "Profile:"
+    @profile.each { |key, value| output << "  #{key}: #{value}" }
+    output.join("\n")
+  end
+end
+
+# APIResponse class to encapsulate API response data
+class APIResponse
+  attr_reader :status_code, :message, :data, :metadata, :session_id, :request_id
+
+  def initialize(status_code:, message:, data: nil, metadata: {},
+session_id: nil, request_id: nil)
+    @status_code = status_code.to_i
+    @message = message
+    @data = data
+    @metadata = metadata
+    @session_id = session_id
+    @request_id = request_id
+  end
+
+  def success?
+    @status_code >= 200 && @status_code < 300
+  end
+
+  def to_s
+    output = []
+    output << "Status: #{@status_code} - #{@message}"
+    output << "Session ID: #{@session_id}" if @session_id
+    output << "Request ID: #{@request_id}" if @request_id
+    output << "Metadata: #{@metadata.inspect}" unless @metadata.empty?
+    output.join("\n")
+  end
+end
+
+# SOAPClient class for making SOAP API requests
+class SOAPClient
+  # SOAP namespaces used in requests/responses
+  NAMESPACES = {
+    "soap" => "http://schemas.xmlsoap.org/soap/envelope/",
+    "xsi" => "http://www.w3.org/2001/XMLSchema-instance",
+    "xsd" => "http://www.w3.org/2001/XMLSchema",
+    "auth" => "http://api.example.com/auth",
+    "users" => "http://api.example.com/users",
+  }.freeze
+
+  def initialize
+    @moxml = Moxml.new
+  end
+
+  # Build a SOAP GetUser request
+  def build_get_user_request(user_id, session_id = nil)
+    # Generate request ID and timestamp
+    request_id = "req-#{SecureRandom.hex(6)}"
+    timestamp = Time.now.utc.iso8601
+
+    # Build the SOAP envelope using Moxml::Builder
+    Moxml::Builder.new(@moxml).build do
+      # XML declaration
+      declaration version: "1.0", encoding: "UTF-8"
+
+      # SOAP Envelope with namespaces
+      element "soap:Envelope",
+              "xmlns:soap" => NAMESPACES["soap"],
+              "xmlns:xsi" => NAMESPACES["xsi"],
+              "xmlns:xsd" => NAMESPACES["xsd"] do
+        # SOAP Header with authentication
+        element "soap:Header" do
+          element "AuthHeader", "xmlns" => NAMESPACES["auth"] do
+            element "SessionId" do
+              text(session_id || "demo-session-id")
+            end
+            element "Timestamp" do
+              text timestamp
+            end
+            element "RequestId" do
+              text request_id
+            end
+          end
+        end
+
+        # SOAP Body with request
+        element "soap:Body" do
+          element "GetUserRequest", "xmlns" => NAMESPACES["users"] do
+            element "UserId" do
+              text user_id.to_s
+            end
+          end
+        end
+      end
+    end
+  end
+
+  # Build a SOAP CreateUser request
+  def build_create_user_request(username, email, full_name, role)
+    request_id = "req-#{SecureRandom.hex(6)}"
+    timestamp = Time.now.utc.iso8601
+
+    Moxml::Builder.new(@moxml).build do
+      declaration version: "1.0", encoding: "UTF-8"
+
+      element "soap:Envelope",
+              "xmlns:soap" => NAMESPACES["soap"],
+              "xmlns:xsi" => NAMESPACES["xsi"],
+              "xmlns:xsd" => NAMESPACES["xsd"] do
+        element "soap:Header" do
+          element "AuthHeader", "xmlns" => NAMESPACES["auth"] do
+            element "SessionId" do
+              text "demo-session-id"
+            end
+            element "Timestamp" do
+              text timestamp
+            end
+            element "RequestId" do
+              text request_id
+            end
+          end
+        end
+
+        element "soap:Body" do
+          element "CreateUserRequest", "xmlns" => NAMESPACES["users"] do
+            element "Username" do
+              text username
+            end
+            element "Email" do
+              text email
+            end
+            element "FullName" do
+              text full_name
+            end
+            element "Role" do
+              text role
+            end
+          end
+        end
+      end
+    end
+  end
+
+  # Parse a SOAP response
+  def parse_response(xml_string)
+    # Parse the XML response
+    doc = begin
+      @moxml.parse(xml_string)
+    rescue Moxml::ParseError => e
+      puts "Failed to parse API response: #{e.message}"
+      raise
+    end
+
+    # Extract authentication header
+    session_id = extract_text(doc, "//auth:SessionId", NAMESPACES)
+    request_id = extract_text(doc, "//auth:RequestId", NAMESPACES)
+
+    # Extract status information
+    status_code = extract_text(doc, "//users:Status/users:Code", NAMESPACES)
+    status_message = extract_text(doc, "//users:Status/users:Message",
+                                  NAMESPACES)
+
+    # Extract metadata
+    metadata = extract_metadata(doc)
+
+    # Check if response contains user data
+    user_element = doc.at_xpath("//users:User", NAMESPACES)
+    user_data = user_element ? parse_user(user_element) : nil
+
+    APIResponse.new(
+      status_code: status_code,
+      message: status_message,
+      data: user_data,
+      metadata: metadata,
+      session_id: session_id,
+      request_id: request_id,
+    )
+  end
+
+  private
+
+  # Parse user data from XML element
+  def parse_user(user_element)
+    # Extract basic user fields
+    id = extract_text(user_element, "./users:Id", NAMESPACES)
+    username = extract_text(user_element, "./users:Username", NAMESPACES)
+    email = extract_text(user_element, "./users:Email", NAMESPACES)
+    full_name = extract_text(user_element, "./users:FullName", NAMESPACES)
+    role = extract_text(user_element, "./users:Role", NAMESPACES)
+    status = extract_text(user_element, "./users:Status", NAMESPACES)
+    created_at = extract_text(user_element, "./users:CreatedAt", NAMESPACES)
+    last_login = extract_text(user_element, "./users:LastLogin", NAMESPACES)
+
+    # Extract permissions array
+    permission_nodes = user_element.xpath(
+      "./users:Permissions/users:Permission", NAMESPACES
+    )
+    permissions = permission_nodes.map(&:text)
+
+    # Extract profile data
+    profile_element = user_element.at_xpath("./users:Profile", NAMESPACES)
+    profile = if profile_element
+                {
+                  "Department" => extract_text(profile_element, "./users:Department",
+                                               NAMESPACES),
+                  "Title" => extract_text(profile_element, "./users:Title",
+                                          NAMESPACES),
+                  "Location" => extract_text(profile_element, "./users:Location",
+                                             NAMESPACES),
+                  "PhoneNumber" => extract_text(profile_element, "./users:PhoneNumber",
+                                                NAMESPACES),
+                }
+              else
+                {}
+              end
+
+    User.new(
+      id: id,
+      username: username,
+      email: email,
+      full_name: full_name,
+      role: role,
+      status: status,
+      created_at: created_at,
+      last_login: last_login,
+      permissions: permissions,
+      profile: profile,
+    )
+  end
+
+  # Extract metadata from response
+  def extract_metadata(doc)
+    metadata_element = doc.at_xpath("//users:Metadata", NAMESPACES)
+    return {} unless metadata_element
+
+    {
+      response_time: extract_text(metadata_element, "./users:ResponseTime",
+                                  NAMESPACES),
+      server_version: extract_text(metadata_element, "./users:ServerVersion",
+                                   NAMESPACES),
+      cache_hit: extract_text(metadata_element, "./users:CacheHit", NAMESPACES),
+    }
+  end
+
+  # Helper method to safely extract text from XPath
+  def extract_text(node, xpath, namespaces = {})
+    element = node.at_xpath(xpath, namespaces)
+    element&.text&.strip || ""
+  end
+end
+
+# Demonstrate request building
+def demonstrate_request_building
+  puts "=" * 80
+  puts "Building SOAP Requests"
+  puts "=" * 80
+  puts
+
+  client = SOAPClient.new
+
+  # Build GetUser request
+  puts "1. GetUser Request:"
+  puts "-" * 80
+  get_user_doc = client.build_get_user_request(1001, "session-abc-123")
+  puts get_user_doc.to_xml(indent: 2)
+  puts
+
+  # Build CreateUser request
+  puts "2. CreateUser Request:"
+  puts "-" * 80
+  create_user_doc = client.build_create_user_request(
+    "janedoe",
+    "jane.doe@example.com",
+    "Jane Doe",
+    "Developer",
+  )
+  puts create_user_doc.to_xml(indent: 2)
+  puts
+end
+
+# Demonstrate response parsing
+def demonstrate_response_parsing(response_file)
+  puts "=" * 80
+  puts "Parsing SOAP Response"
+  puts "=" * 80
+  puts
+
+  # Read response XML
+  xml_content = File.read(response_file)
+
+  # Parse response
+  client = SOAPClient.new
+  response = begin
+    client.parse_response(xml_content)
+  rescue Moxml::ParseError => e
+    puts "Error parsing response: #{e.message}"
+    return
+  rescue Moxml::XPathError => e
+    puts "Error querying response: #{e.message}"
+    return
+  end
+
+  # Display response information
+  puts "Response Information:"
+  puts "-" * 80
+  puts response
+  puts
+
+  # Display user data if present
+  if response.data
+    puts "User Data:"
+    puts "-" * 80
+    puts response.data
+    puts
+  end
+
+  # Show success/failure
+  puts "Result: #{response.success? ? 'SUCCESS ✓' : 'FAILED ✗'}"
+  puts
+end
+
+# Main execution
+if __FILE__ == $0
+  puts "SOAP API Client Example"
+  puts "=" * 80
+  puts
+
+  # Demonstrate building requests
+  demonstrate_request_building
+
+  # Demonstrate parsing responses
+  response_file = ARGV[0] || File.join(__dir__, "example_response.xml")
+
+  unless File.exist?(response_file)
+    puts "Error: Response file not found: #{response_file}"
+    puts "Usage: ruby api_client.rb [path/to/response.xml]"
+    exit 1
+  end
+
+  demonstrate_response_parsing(response_file)
+
+  # Summary
+  puts "=" * 80
+  puts "API Client Example Complete"
+  puts "=" * 80
+  puts
+  puts "Key Takeaways:"
+  puts "  - Use Moxml::Builder for clean XML request construction"
+  puts "  - Namespace handling is crucial for SOAP/XML APIs"
+  puts "  - XPath with namespaces extracts response data efficiently"
+  puts "  - Proper error handling ensures robust API interactions"
+  puts "  - Structure data into Ruby objects for easy manipulation"
+  puts "=" * 80
+end

data/examples/api_client/example_response.xml

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+  <soap:Header>
+    <AuthHeader xmlns="http://api.example.com/auth">
+      <SessionId>a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6</SessionId>
+      <Timestamp>2024-10-30T10:00:00Z</Timestamp>
+      <RequestId>req-12345</RequestId>
+    </AuthHeader>
+  </soap:Header>
+  <soap:Body>
+    <GetUserResponse xmlns="http://api.example.com/users">
+      <Status>
+        <Code>200</Code>
+        <Message>Success</Message>
+      </Status>
+      <Result>
+        <User>
+          <Id>1001</Id>
+          <Username>johndoe</Username>
+          <Email>john.doe@example.com</Email>
+          <FullName>John Doe</FullName>
+          <Role>Administrator</Role>
+          <Status>Active</Status>
+          <CreatedAt>2024-01-15T08:30:00Z</CreatedAt>
+          <LastLogin>2024-10-29T14:22:00Z</LastLogin>
+          <Permissions>
+            <Permission>users.read</Permission>
+            <Permission>users.write</Permission>
+            <Permission>admin.access</Permission>
+          </Permissions>
+          <Profile>
+            <Department>Engineering</Department>
+            <Title>Senior Developer</Title>
+            <Location>San Francisco, CA</Location>
+            <PhoneNumber>+1-555-0123</PhoneNumber>
+          </Profile>
+        </User>
+      </Result>
+      <Metadata>
+        <ResponseTime>45</ResponseTime>
+        <ServerVersion>2.1.0</ServerVersion>
+        <CacheHit>false</CacheHit>
+      </Metadata>
+    </GetUserResponse>
+  </soap:Body>
+</soap:Envelope>

data/examples/headed_ox_example/README.md

@@ -0,0 +1,90 @@
+# HeadedOx Demo
+
+This example demonstrates the HeadedOx adapter, which combines:
+- Ox's fast C-based XML parsing
+- Moxml's comprehensive pure Ruby XPath 1.0 engine
+
+## What is HeadedOx?
+
+HeadedOx is a hybrid adapter that provides:
+- **Fast parsing:** Uses Ox's C-based parser for speed
+- **Full XPath 1.0:** All 27 XPath functions and 6 common axes
+- **Production ready:** 99.20% test pass rate (1,992/2,008 tests)
+- **Pure Ruby XPath:** Debuggable implementation with expression caching
+- **Best of both:** Combines Ox speed with comprehensive XPath support
+
+## Running the Demo
+
+### For Development (from gem source):
+```bash
+# From the moxml root directory
+bundle exec ruby examples/headed_ox_example/headed_ox_demo.rb
+```
+
+Note: The example uses `require_relative` to load Moxml from source, which requires
+`bundle exec` to properly resolve dependencies in development.
+
+### After Installation:
+```bash
+# When using the installed gem
+ruby headed_ox_demo.rb
+```
+
+## Features Demonstrated
+
+1. **Descendant queries** - `//book` syntax
+2. **Attribute selection** - `@price` syntax
+3. **Predicates** - `[@price < 20]` filtering
+4. **XPath functions** - count(), sum(), string(), contains()
+5. **Complex queries** - Combining multiple features
+6. **Variable binding** - `$var` support
+
+## Output
+
+The demo shows HeadedOx executing various XPath queries on a sample library XML,
+demonstrating the full range of XPath 1.0 capabilities.
+
+## Expected Output
+
+```
+============================================================
+HeadedOx Demo - Comprehensive XPath on Fast Ox Parsing
+============================================================
+
+1. Find all books:
+Found 3 books
+
+2. Get all prices:
+Prices: 15.99, 25.99, 12.99
+
+3. Find cheap books (< $20):
+  - Programming Ruby: $15.99
+  - Programming JavaScript: $12.99
+
+4. XPath functions:
+  Total books: 3
+  Total price: $54.97
+  First title: Programming Ruby
+
+5. Books with 'Ruby' in title:
+  - Programming Ruby
+
+6. Using variables:
+Books under $20: 2
+
+============================================================
+HeadedOx provides full XPath 1.0 support!
+============================================================
+```
+
+## Why Choose HeadedOx?
+
+Use HeadedOx when you need:
+- Fast XML parsing (Ox's strength)
+- Comprehensive XPath beyond basic locate()
+- XPath 1.0 functions like count(), sum(), contains()
+- Complex predicates and expressions
+- Debuggable XPath implementation
+- Production-ready stability (99.20% test coverage)
+
+See `docs/HEADED_OX_LIMITATIONS.md` for detailed capabilities and known limitations.

data/examples/headed_ox_example/headed_ox_demo.rb

@@ -0,0 +1,71 @@
+require_relative "../../lib/moxml"
+
+# HeadedOx Adapter Demo
+# Demonstrates Ox's fast parsing + comprehensive XPath
+
+# Sample XML
+xml = <<~XML
+  <library>
+    <book id="1" price="15.99" year="2020">
+      <title>Programming Ruby</title>
+      <author>Matz</author>
+      <isbn>978-1234567890</isbn>
+    </book>
+    <book id="2" price="25.99" year="2021">
+      <title>Programming Python</title>
+      <author>Guido</author>
+      <isbn>978-0987654321</isbn>
+    </book>
+    <book id="3" price="12.99" year="2022">
+      <title>Programming JavaScript</title>
+      <author>Brendan</author>
+      <isbn>978-1122334455</isbn>
+    </book>
+  </library>
+XML
+
+# Initialize HeadedOx
+context = Moxml.new(:headed_ox)
+doc = context.parse(xml)
+
+puts "=" * 60
+puts "HeadedOx Demo - Comprehensive XPath on Fast Ox Parsing"
+puts "=" * 60
+
+# 1. Basic descendant queries
+puts "\n1. Find all books:"
+books = doc.xpath("//book")
+puts "Found #{books.size} books"
+
+# 2. Attribute selection
+puts "\n2. Get all prices:"
+prices = doc.xpath("//book/@price")
+puts "Prices: #{prices.map(&:value).join(', ')}"
+
+# 3. Predicates
+puts "\n3. Find cheap books (< $20):"
+cheap = doc.xpath("//book[@price < 20]")
+cheap.each do |book|
+  puts "  - #{book.xpath('title').first.text}: $#{book['price']}"
+end
+
+# 4. XPath functions
+puts "\n4. XPath functions:"
+puts "  Total books: #{doc.xpath('count(//book)')}"
+puts "  Total price: $#{doc.xpath('sum(//book/@price)')}"
+puts "  First title: #{doc.xpath('string(//book[1]/title)')}"
+
+# 5. Complex queries
+puts "\n5. Books with 'Ruby' in title:"
+ruby_books = doc.xpath('//book[contains(title, "Ruby")]')
+ruby_books.each { |book| puts "  - #{book.xpath('title').first.text}" }
+
+# 6. Variable binding
+puts "\n6. Using variables:"
+max_price = 20
+affordable = doc.xpath("//book[@price < $max]", { "max" => max_price })
+puts "Books under $#{max_price}: #{affordable.size}"
+
+puts "\n#{'=' * 60}"
+puts "HeadedOx provides full XPath 1.0 support!"
+puts "=" * 60