moxml 0.1.6 → 0.1.8

data/docs/_config.yml

@@ -0,0 +1,138 @@
+# Site settings
+title: Moxml
+description: >-
+  Modern XML processing for Ruby with unified adapter interface
+baseurl: "/moxml"
+url: "https://lutaml.github.io"
+
+# Theme
+theme: just-the-docs
+remote_theme: just-the-docs/just-the-docs@v0.7.0
+
+# Color scheme
+color_scheme: light
+
+# Search
+search_enabled: true
+search:
+  heading_level: 2
+  previews: 3
+  preview_words_before: 5
+  preview_words_after: 10
+  tokenizer_separator: /[\s/]+/
+  rel_url: true
+  button: false
+
+# Heading anchors
+heading_anchors: true
+
+# Aux links for the upper right navigation
+aux_links:
+  "GitHub":
+    - "https://github.com/lutaml/moxml"
+  "RubyGems":
+    - "https://rubygems.org/gems/moxml"
+
+# Makes Aux links open in a new tab
+aux_links_new_tab: true
+
+# Back to top link
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# Footer content
+footer_content: >-
+  Copyright © 2025 Ribose. Distributed by a
+  <a href="https://github.com/lutaml/moxml/blob/main/LICENSE.md">BSD-2-Clause license</a>.
+
+# Footer last edit timestamp
+last_edit_timestamp: true
+last_edit_time_format: "%b %e %Y at %I:%M %p"
+
+# Navigation structure
+nav_sort: order
+
+# Collections for organizing content
+collections:
+  pages:
+    permalink: "/:path/"
+    output: true
+  tutorials:
+    permalink: "/:collection/:path/"
+    output: true
+  guides:
+    permalink: "/:collection/:path/"
+    output: true
+  references:
+    permalink: "/:collection/:path/"
+    output: true
+
+# Just the Docs collection configuration
+just_the_docs:
+  collections:
+    pages:
+      name: Core topics
+      nav_fold: false
+    tutorials:
+      name: Tutorials
+      nav_fold: true
+    guides:
+      name: Guides
+      nav_fold: true
+    references:
+      name: Reference
+      nav_fold: true
+
+# Plugins
+plugins:
+  - jekyll-asciidoc
+  - jekyll-seo-tag
+  - jekyll-sitemap
+
+# AsciiDoc configuration
+asciidoc: {}
+asciidoctor:
+  attributes:
+    - source-highlighter=rouge
+    - rouge-style=github
+    - icons=font
+    - sectanchors=true
+    - idprefix=
+    - idseparator=-
+    - experimental=true
+
+include:
+  - '*.adoc'
+
+# Exclude from processing
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - _site
+  - node_modules
+  - vendor/bundle/
+  - vendor/cache/
+  - vendor/gems/
+  - vendor/ruby/
+  - Rakefile
+
+# Enable code copy button
+enable_copy_code_button: true
+
+# Callouts
+callouts_level: quiet
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red

data/docs/_guides/advanced-features.adoc

@@ -0,0 +1,87 @@
+---
+title: Advanced features
+parent: Guides
+nav_order: 8
+---
+
+== Advanced features
+
+== Advanced features
+
+=== XPath querying and node mapping
+
+==== Nokogiri, Oga, REXML, LibXML
+
+Moxml provides efficient XPath querying by leveraging the native XML library's
+implementation while maintaining consistent node mapping:
+
+[source,ruby]
+----
+# Find all book elements
+books = doc.xpath('//book')
+# Returns Moxml::Element objects mapped to native nodes
+
+# Find with namespaces
+titles = doc.xpath('//dc:title',
+  'dc' => 'http://purl.org/dc/elements/1.1/')
+
+# Find first matching node
+first_book = doc.at_xpath('//book')
+
+# Chain queries
+doc.xpath('//book').each do |book|
+  # Each book is a mapped Moxml::Element
+  title = book.at_xpath('.//title')
+  puts "#{book['id']}: #{title.text}"
+end
+----
+
+==== Ox
+
+The native Ox's query method
+https://www.ohler.com/ox/Ox/Element.html#method-i-locate[`locate`] resembles
+XPath but has a different syntax.
+
+==== HeadedOx
+
+HeadedOx provides comprehensive (but not fully) XPath 1.0 support via a pure
+Ruby XPath engine layered on top of Ox.
+
+
+=== Namespace handling
+
+[source,ruby]
+----
+# Add namespace to element
+element.add_namespace('dc', 'http://purl.org/dc/elements/1.1/')
+
+# Create element in namespace
+title = doc.create_element('dc:title')
+title.text = 'Document Title'
+
+# Query with namespaces
+doc.xpath('//dc:title',
+  'dc' => 'http://purl.org/dc/elements/1.1/')
+----
+
+=== Accessing native implementation
+
+While not typically needed, you can access the underlying XML library's nodes:
+
+[source,ruby]
+----
+# Get native node
+native_node = element.native
+
+# Get adapter being used
+adapter = element.context.config.adapter
+
+# Create from native node
+element = Moxml::Element.new(native_node, context)
+----
+
+
+See also:
+
+* link:../pages/compatibility[Adapter compatibility]
+* link:../pages/adapters/[Individual adapter documentation]

data/docs/_guides/development-testing.adoc

@@ -0,0 +1,165 @@
+---
+title: Development and testing
+parent: Guides
+nav_order: 10
+---
+
+
+== Development and testing
+
+=== Skipping benchmarks
+
+Benchmark tests can be slow and are not needed for regular test runs. To
+speed up local development, you can skip benchmark tests using the
+`SKIP_BENCHMARKS` environment variable.
+
+Syntax:
+
+[source,shell]
+----
+SKIP_BENCHMARKS=1 bundle exec rspec
+----
+
+This will skip all benchmark tests while running the regular test suite.
+
+To run benchmarks explicitly:
+
+[source,shell]
+----
+bundle exec rspec spec/moxml/examples/xpath_benchmark_spec.rb
+----
+
+Or use the rake task:
+
+[source,shell]
+----
+rake benchmark:xpath
+----
+
+NOTE: The `rake benchmark:xpath` task always runs benchmarks regardless of the
+`SKIP_BENCHMARKS` environment variable setting.
+
+=== Running tests with coverage
+
+To run the test suite with code coverage tracking:
+
+[source,shell]
+----
+COVERAGE=true bundle exec rspec
+----
+
+After running, view the coverage report:
+
+[source,shell]
+----
+open coverage/index.html
+----
+
+The coverage configuration includes:
+
+* Minimum overall coverage: 90%
+* Minimum per-file coverage: 80%
+* Organized groups for Core, Adapters, and Utilities
+* Filters for spec and vendor directories
+
+=== Generating performance benchmark reports
+
+Moxml provides a comprehensive benchmark reporting system that measures and
+compares all adapters across multiple dimensions.
+
+==== Running the benchmark report
+
+To generate a complete performance report for all adapters:
+
+[source,shell]
+----
+rake benchmark:report
+----
+
+Or run the script directly:
+
+[source,shell]
+----
+bundle exec ruby benchmarks/generate_report.rb
+----
+
+This will benchmark all available adapters and generate a detailed report at
+[`benchmarks/PERFORMANCE_REPORT.md`](benchmarks/PERFORMANCE_REPORT.md).
+
+==== Benchmark categories
+
+The report includes the following benchmark categories:
+
+**Parsing benchmarks:**
+
+* Simple XML (< 1KB)
+* Medium XML (10KB, 50 elements with namespaces)
+* Large XML (145KB, 500 elements)
+* Complex nested structures
+
+**Serialization benchmarks:**
+
+* Simple documents
+* Documents with namespaces
+* Documents with mixed content
+
+**XPath benchmarks:**
+
+* Simple queries (`//element`)
+* Complex queries with predicates (`//element[@attribute]`)
+* Namespace-aware queries (`//ns:element`)
+
+**Memory benchmarks:**
+
+* Memory usage per document parse
+* Memory usage for large documents
+
+==== Report contents
+
+The generated report includes:
+
+* Summary table comparing all adapters with grades
+* Detailed performance metrics for each benchmark
+* ASCII performance visualization charts
+* Adapter selection recommendations based on results
+* Complete test environment details (Ruby version, platform, gem versions)
+* Best performers for each category
+
+==== Viewing the report
+
+After generation, the report is available at:
+
+[source,shell]
+----
+cat benchmarks/PERFORMANCE_REPORT.md
+----
+
+Or open it in your preferred Markdown viewer.
+
+NOTE: The generated report is machine-specific and excluded from git via
+`.gitignore`. Results will vary based on your hardware, OS, and Ruby version.
+
+==== Example output
+
+The summary table shows comparative performance:
+
+[source,markdown]
+----
+| Adapter | Parse (ips) | Serialize (ips) | XPath (ips) | Memory (MB) | Grade |
+|---------|-------------|-----------------|-------------|-------------|-------|
+| Nokogiri | 76 | 13900 | 64958 | -0.1 ⭐ | A |
+| Ox | 289 | 39203 | 9640 | 0.0 ⭐⭐⭐⭐⭐ | A+ |
+...
+----
+
+Performance visualizations help quickly identify the best adapter for specific
+needs:
+
+[source]
+----
+Parsing (Medium XML):
+  Nokogiri   █████████████ 76 ips
+  Ox         ██████████████████████████████████████████████████ 289 ips
+...
+----
+

data/docs/_guides/index.adoc

@@ -0,0 +1,45 @@
+---
+title: Overview
+nav_order: 1
+---
+
+== Guides
+
+Task-oriented guides for common XML processing operations with Moxml.
+
+=== Document operations
+
+link:parsing-xml[Parsing XML]::
+Parse XML from strings, files, and IO streams with different adapters.
+
+link:creating-documents[Creating documents]::
+Build XML documents from scratch using the builder pattern or direct
+manipulation.
+
+link:modifying-xml[Modifying XML]::
+Add, remove, and modify elements, attributes, and content in XML documents.
+
+link:serializing-xml[Serializing XML]::
+Convert XML documents to strings with formatting and encoding options.
+
+=== Querying and traversal
+
+link:xpath-queries[XPath queries]::
+Query XML documents using XPath expressions with namespaces and predicates.
+
+link:node-traversal[Node traversal]::
+Navigate XML document structure using parent, child, and sibling methods.
+
+link:finding-nodes[Finding nodes]::
+Different approaches to locate specific nodes in XML documents.
+
+=== Advanced operations
+
+link:namespace-management[Namespace management]::
+Work with XML namespaces including declarations, prefixes, and resolution.
+
+link:error-handling[Error handling]::
+Handle XML processing errors effectively with Moxml's error classes.
+
+link:performance-optimization[Performance optimization]::
+Tips and techniques for optimizing XML processing performance.

data/docs/_guides/modifying-xml.adoc

@@ -0,0 +1,293 @@
+---
+title: Modifying XML
+parent: Overview
+nav_order: 3
+---
+
+== Modifying XML
+
+=== Purpose
+
+Learn how to modify existing XML documents by adding, updating, and removing
+elements, attributes, and content.
+
+=== Modifying element content
+
+Update text content of elements:
+
+[source,ruby]
+----
+xml = '<library><book><title>Old Title</title></book></library>'
+doc = Moxml.new.parse(xml)
+
+# Find and update
+title = doc.at_xpath('//title')
+title.text = 'New Title'
+
+puts doc.to_xml
+# => <library><book><title>New Title</title></book></library>
+----
+
+=== Adding elements
+
+Add new elements to existing documents:
+
+[source,ruby]
+----
+xml = '<library><book id="1"><title>Ruby Basics</title></book></library>'
+doc = Moxml.new.parse(xml)
+
+book = doc.at_xpath('//book[@id="1"]')
+
+# Add author element
+author = doc.create_element('author')
+author.text = 'Jane Smith'
+book.add_child(author)
+
+# Add price element
+price = doc.create_element('price')
+price.text = '29.99'
+price['currency'] = 'USD'
+book.add_child(price)
+
+# Add ISBN element
+isbn = doc.create_element('isbn')
+isbn.text = '978-0-123456-78-9'
+book.add_child(isbn)
+
+puts doc.to_xml(indent: 2)
+----
+
+=== Removing elements
+
+Remove elements from documents:
+
+[source,ruby]
+----
+xml = <<~XML
+  <library>
+    <book id="1">
+      <title>Ruby Basics</title>
+      <author>Jane Smith</author>
+      <draft>true</draft>
+    </book>
+  </library>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# Find and remove element
+draft = doc.at_xpath('//draft')
+draft.remove
+
+# Remove by parent
+book = doc.at_xpath('//book')
+author = book.at_xpath('.//author')
+book.remove_child(author)
+
+puts doc.to_xml
+----
+
+=== Modifying attributes
+
+Update, add, and remove attributes:
+
+[source,ruby]
+----
+xml = '<book id="1" status="draft">Ruby Basics</book>'
+doc = Moxml.new.parse(xml)
+
+book = doc.root
+
+# Update existing attribute
+book['id'] = '100'
+
+# Add new attribute
+book['edition'] = '2nd'
+book['category'] = 'programming'
+
+# Remove attribute
+book.remove_attribute('status')
+
+# Get all attributes
+book.attributes.each do |attr|
+  puts "#{attr.name}=#{attr.value}"
+end
+# => id=100
+# => edition=2nd
+# => category=programming
+----
+
+=== Replacing nodes
+
+Replace elements with new content:
+
+[source,ruby]
+----
+xml = '<book><title>Old Title</title><author>Old Author</author></book>'
+doc = Moxml.new.parse(xml)
+
+# Replace title element
+old_title = doc.at_xpath('//title')
+new_title = doc.create_element('title')
+new_title.text = 'New Title'
+new_title['lang'] = 'en'
+
+old_title.replace(new_title)
+
+# Replace text node
+author = doc.at_xpath('//author')
+author.children.first.replace(doc.create_text('New Author'))
+
+puts doc.to_xml
+----
+
+=== Adding siblings
+
+Insert elements relative to existing nodes:
+
+[source,ruby]
+----
+xml = <<~XML
+  <book>
+    <title>Ruby Programming</title>
+    <price>29.99</price>
+  </book>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# Add before price
+price = doc.at_xpath('//price')
+author = doc.create_element('author')
+author.text = 'Jane Smith'
+price.add_previous_sibling(author)
+
+# Add after title
+title = doc.at_xpath('//title')
+subtitle = doc.create_element('subtitle')
+subtitle.text = 'A Comprehensive Guide'
+title.add_next_sibling(subtitle)
+
+puts doc.to_xml(indent: 2)
+----
+
+Output:
+
+[source,xml]
+----
+<book>
+  <title>Ruby Programming</title>
+  <subtitle>A Comprehensive Guide</subtitle>
+  <author>Jane Smith</author>
+  <price>29.99</price>
+</book>
+----
+
+=== Batch modifications
+
+Update multiple elements at once:
+
+[source,ruby]
+----
+xml = <<~XML
+  <library>
+    <book><price currency="USD">29.99</price></book>
+    <book><price currency="USD">39.99</price></book>
+    <book><price currency="USD">19.99</price></book>
+  </library>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# Apply 10% discount to all books
+doc.xpath('//price').each do |price|
+  current = price.text.to_f
+  discounted = (current * 0.9).round(2)
+  price.text = discounted.to_s
+  price['original'] = current.to_s
+end
+
+puts doc.to_xml(indent: 2)
+----
+
+=== Preserving structure
+
+Maintain document structure during modifications:
+
+[source,ruby]
+----
+xml = <<~XML
+  <?xml version="1.0" encoding="UTF-8"?>
+  <library>
+    <book id="1">Ruby Basics</book>
+  </library>
+XML
+
+doc = Moxml.new.parse(xml)
+
+# Modifications preserve declaration
+book = doc.at_xpath('//book')
+book['edition'] = '2nd'
+
+# Original structure maintained
+puts doc.to_xml(indent: 2)
+# => Still has <?xml ... ?> declaration
+----
+
+=== Common modification patterns
+
+==== Update or create pattern
+
+[source,ruby]
+----
+def ensure_element(parent, name, text)
+  elem = parent.at_xpath(".//#{name}")
+
+  if elem
+    # Update existing
+    elem.text = text
+  else
+    # Create new
+    elem = parent.document.create_element(name)
+    elem.text = text
+    parent.add_child(elem)
+  end
+
+  elem
+end
+
+book = doc.at_xpath('//book')
+ensure_element(book, 'author', 'Jane Smith')
+ensure_element(book, 'price', '29.99')
+----
+
+==== Conditional modification
+
+[source,ruby]
+----
+doc.xpath('//book').each do |book|
+  price = book.at_xpath('.//price')
+  next unless price
+
+  # Add discount for expensive books
+  if price.text.to_f > 30
+    book['discount'] = '10%'
+    price.text = (price.text.to_f * 0.9).to_s
+  end
+end
+----
+
+=== Best practices
+
+. **Find before modifying** - always locate elements first
+. **Check element exists** before calling methods on it
+. **Use transactions** for complex modifications if needed
+. **Validate structure** after major changes
+. **Preserve document metadata** (declarations, encoding)
+
+=== See also
+
+* link:creating-documents[Creating documents] - Build from scratch
+* link:../tutorials/basic-usage[Basic usage] - Fundamentals
+* link:../references/element-api[Element API] - Complete method reference