moxml 0.1.7 → 0.1.9

data/docs/_references/document-api.adoc

@@ -0,0 +1,407 @@
+---
+title: Document API
+nav_order: 2
+---
+
+== Document API
+
+=== Purpose
+
+Complete reference for the Document class methods and properties.
+
+=== Class: Moxml::Document
+
+The Document class represents an XML document and serves as the root container
+for all XML nodes.
+
+=== Creating documents
+
+[source,ruby]
+----
+# Parse from XML string
+doc = Moxml.new.parse(xml_string)
+
+# Create empty document
+doc = Moxml.new.create_document
+
+# Using builder
+doc = Moxml::Builder.build(Moxml.new) do |xml|
+  xml.root "content"
+end
+----
+
+=== Instance methods
+
+==== `#root`
+
+Returns the root element of the document.
+
+[source,ruby]
+----
+doc = Moxml.new.parse('<library><book/></library>')
+root = doc.root
+puts root.name  # => "library"
+----
+
+**Returns:** `Moxml::Element` or `nil`
+
+==== `#root=(element)`
+
+Sets the root element of the document.
+
+[source,ruby]
+----
+doc = Moxml.new.create_document
+root = doc.create_element('library')
+doc.root = root
+----
+
+**Parameters:**
+
+* `element` (`Moxml::Element`) - The element to set as root
+
+==== `#children`
+
+Returns all top-level children of the document.
+
+[source,ruby]
+----
+doc = Moxml.new.parse('<?xml version="1.0"?><root/>')
+children = doc.children
+# => [Declaration, Element]
+----
+
+**Returns:** `Moxml::NodeSet`
+
+==== `#add_child(node)`
+
+Adds a child node to the document.
+
+[source,ruby]
+----
+doc = Moxml.new.create_document
+
+# Add declaration
+decl = doc.create_declaration
+doc.add_child(decl)
+
+# Add root element
+root = doc.create_element('library')
+doc.add_child(root)
+----
+
+**Parameters:**
+
+* `node` (`Moxml::Node`) - The node to add
+
+**Returns:** `Moxml::Node` - The added node
+
+==== `#remove_child(node)`
+
+Removes a child node from the document.
+
+[source,ruby]
+----
+doc.remove_child(declaration)
+----
+
+**Parameters:**
+
+* `node` (`Moxml::Node`) - The node to remove
+
+==== `#create_element(name)`
+
+Creates a new element node.
+
+[source,ruby]
+----
+elem = doc.create_element('book')
+elem.text = 'Content'
+----
+
+**Parameters:**
+
+* `name` (`String`) - Element name
+
+**Returns:** `Moxml::Element`
+
+==== `#create_text(content)`
+
+Creates a new text node.
+
+[source,ruby]
+----
+text = doc.create_text('content')
+element.add_child(text)
+----
+
+**Parameters:**
+
+* `content` (`String`) - Text content
+
+**Returns:** `Moxml::Text`
+
+==== `#create_comment(content)`
+
+Creates a new comment node.
+
+[source,ruby]
+----
+comment = doc.create_comment('Note: this is important')
+element.add_child(comment)
+----
+
+**Parameters:**
+
+* `content` (`String`) - Comment text
+
+**Returns:** `Moxml::Comment`
+
+==== `#create_cdata(content)`
+
+Creates a new CDATA section.
+
+[source,ruby]
+----
+cdata = doc.create_cdata('<raw>HTML content</raw>')
+element.add_child(cdata)
+----
+
+**Parameters:**
+
+* `content` (`String`) - CDATA content
+
+**Returns:** `Moxml::Cdata`
+
+==== `#create_processing_instruction(target, content)`
+
+Creates a new processing instruction.
+
+[source,ruby]
+----
+pi = doc.create_processing_instruction('xml-stylesheet',
+  'type="text/xsl" href="style.xsl"')
+doc.add_child(pi)
+----
+
+**Parameters:**
+
+* `target` (`String`) - PI target
+* `content` (`String`) - PI content
+
+**Returns:** `Moxml::ProcessingInstruction`
+
+==== `#create_declaration(version, encoding, standalone)`
+
+Creates a new XML declaration.
+
+[source,ruby]
+----
+# With defaults
+decl = doc.create_declaration
+# => <?xml version="1.0" encoding="UTF-8"?>
+
+# Custom values
+decl = doc.create_declaration("1.1", "ISO-8859-1", "yes")
+# => <?xml version="1.1" encoding="ISO-8859-1" standalone="yes"?>
+----
+
+**Parameters:**
+
+* `version` (`String`, optional) - XML version (default: "1.0")
+* `encoding` (`String`, optional) - Character encoding (default: "UTF-8")
+* `standalone` (`String`, optional) - Standalone declaration ("yes"/"no")
+
+**Returns:** `Moxml::Declaration`
+
+==== `#create_doctype(name, external_id, system_id)`
+
+Creates a new DOCTYPE declaration.
+
+[source,ruby]
+----
+doctype = doc.create_doctype('html')
+doc.add_child(doctype)
+
+# With system ID
+doctype = doc.create_doctype('root', nil, 'test.dtd')
+----
+
+**Parameters:**
+
+* `name` (`String`) - DOCTYPE name
+* `external_id` (`String`, optional) - External ID
+* `system_id` (`String`, optional) - System ID
+
+**Returns:** `Moxml::Doctype`
+
+==== `#xpath(expression, namespaces = {})`
+
+Finds nodes matching XPath expression.
+
+[source,ruby]
+----
+books = doc.xpath('//book[@id="1"]')
+
+# With namespaces
+ns = { 'dc' => 'http://purl.org/dc/elements/1.1/' }
+titles = doc.xpath('//dc:title', ns)
+----
+
+**Parameters:**
+
+* `expression` (`String`) - XPath expression
+* `namespaces` (`Hash`, optional) - Namespace prefix mappings
+
+**Returns:** `Moxml::NodeSet`
+
+**Raises:** `Moxml::XPathError` if expression is invalid
+
+==== `#at_xpath(expression, namespaces = {})`
+
+Finds first node matching XPath expression.
+
+[source,ruby]
+----
+book = doc.at_xpath('//book[@id="1"]')
+----
+
+**Parameters:**
+
+* `expression` (`String`) - XPath expression
+* `namespaces` (`Hash`, optional) - Namespace prefix mappings
+
+**Returns:** `Moxml::Node` or `nil`
+
+**Raises:** `Moxml::XPathError` if expression is invalid
+
+==== `#to_xml(options = {})`
+
+Serializes document to XML string.
+
+[source,ruby]
+----
+# Default formatting
+xml = doc.to_xml
+
+# With indentation
+xml = doc.to_xml(indent: 2)
+
+# Without declaration
+xml = doc.to_xml(no_declaration: true)
+
+# Custom encoding
+xml = doc.to_xml(encoding: 'ISO-8859-1')
+----
+
+**Parameters:**
+
+* `options` (`Hash`, optional) - Serialization options
+** `:indent` (`Integer`) - Indentation spaces (default: 0)
+** `:encoding` (`String`) - Output encoding
+** `:no_declaration` (`Boolean`) - Omit XML declaration
+
+**Returns:** `String` - XML document as string
+
+==== `#declaration`
+
+Returns the XML declaration if present.
+
+[source,ruby]
+----
+doc = Moxml.new.parse('<?xml version="1.0"?><root/>')
+decl = doc.declaration
+puts decl.version    # => "1.0"
+puts decl.encoding   # => nil (not specified)
+----
+
+**Returns:** `Moxml::Declaration` or `nil`
+
+==== `#doctype`
+
+Returns the DOCTYPE declaration if present.
+
+[source,ruby]
+----
+doc = Moxml.new.parse('<!DOCTYPE root><root/>')
+doctype = doc.doctype
+puts doctype.name  # => "root"
+----
+
+**Returns:** `Moxml::Doctype` or `nil`
+
+==== `#encoding`
+
+Gets or sets document encoding.
+
+[source,ruby]
+----
+doc.encoding = 'UTF-8'
+puts doc.encoding  # => "UTF-8"
+----
+
+==== `#version`
+
+Gets or sets XML version.
+
+[source,ruby]
+----
+doc.version = '1.0'
+puts doc.version  # => "1.0"
+----
+
+==== `#context`
+
+Returns the Moxml context.
+
+[source,ruby]
+----
+context = doc.context
+adapter = context.config.adapter
+----
+
+**Returns:** `Moxml::Context`
+
+=== Complete example
+
+[source,ruby]
+----
+# Create comprehensive document
+doc = Moxml.new.create_document
+
+# Add declaration
+decl = doc.create_declaration("1.0", "UTF-8")
+doc.add_child(decl)
+
+# Add doctype
+doctype = doc.create_doctype('library')
+doc.add_child(doctype)
+
+# Create root
+root = doc.create_element('library')
+root.add_namespace('dc', 'http://purl.org/dc/elements/1.1/')
+doc.add_child(root)
+
+# Add content
+book = doc.create_element('book')
+book['id'] = '1'
+
+title = doc.create_element('dc:title')
+title.text = 'Ruby Programming'
+book.add_child(title)
+
+root.add_child(book)
+
+# Query
+ns = { 'dc' => 'http://purl.org/dc/elements/1.1/' }
+titles = doc.xpath('//dc:title', ns)
+
+# Serialize
+puts doc.to_xml(indent: 2)
+----
+
+=== See also
+
+* link:element-api[Element API] - Element methods
+* link:../pages/quick-start[Quick start] - Basic usage examples
+* link:../guides/creating-documents[Creating documents guide]

data/docs/_references/index.adoc

@@ -0,0 +1,48 @@
+---
+title: Overview
+nav_order: 1
+---
+
+== Reference
+
+Detailed technical specifications and API documentation for Moxml.
+
+=== API reference
+
+link:document-api[Document API]::
+Complete reference for Document class methods and properties.
+
+link:element-api[Element API]::
+Detailed documentation of Element class methods and operations.
+
+link:node-api[Node API]::
+Base Node class methods available to all node types.
+
+link:node-types[Node types]::
+Reference for Text, Comment, CDATA, ProcessingInstruction, and other node
+types.
+
+link:namespace-api[Namespace API]::
+Methods and operations for working with XML namespaces.
+
+link:xpath-api[XPath API]::
+XPath query methods, expressions, and namespace handling.
+
+=== Adapter reference
+
+link:adapter-api[Adapter API]::
+Base adapter interface and adapter-specific method documentation.
+
+link:adapter-capabilities[Adapter capabilities]::
+Detailed feature matrix and capability comparison across all adapters.
+
+=== Utilities
+
+link:builder-api[Builder API]::
+DSL methods for building XML documents programmatically.
+
+link:error-classes[Error classes]::
+Complete reference of all error classes with attributes and usage.
+
+link:xml-utils[XML utilities]::
+Validation, encoding, and utility functions.

data/docs/_tutorials/basic-usage.adoc

@@ -0,0 +1,267 @@
+---
+title: Basic usage
+nav_order: 2
+---
+
+== Basic usage
+
+=== Purpose
+
+Learn the fundamentals of XML processing with Moxml through hands-on examples
+covering parsing, creating, querying, and modifying XML documents.
+
+=== Prerequisites
+
+* Moxml installed with an adapter
+* Basic understanding of XML concepts
+
+=== Step 1: Parse XML documents
+
+Start by parsing existing XML:
+
+[source,ruby]
+----
+require 'moxml'
+
+# Create a Moxml context
+context = Moxml.new
+
+# Parse XML from a string
+xml = '<library><book id="1">Ruby Programming</book></library>'
+doc = context.parse(xml)
+
+# Access the root element
+puts doc.root.name  # => "library"
+
+# Access child elements
+book = doc.root.children.first
+puts book.name      # => "book"
+puts book['id']     # => "1"
+puts book.text      # => "Ruby Programming"
+----
+
+=== Step 2: Query with XPath
+
+Use XPath to find elements:
+
+[source,ruby]
+----
+xml = <<~XML
+  <library>
+    <book id="1" category="programming">
+      <title>Ruby Basics</title>
+      <author>Jane Smith</author>
+      <price>29.99</price>
+    </book>
+    <book id="2" category="fiction">
+      <title>Ruby Story</title>
+      <author>John Doe</author>
+      <price>19.99</price>
+    </book>
+  </library>
+XML
+
+doc = context.parse(xml)
+
+# Find all books
+all_books = doc.xpath('//book')
+puts "Total books: #{all_books.length}"  # => 2
+
+# Find specific book by attribute
+book1 = doc.at_xpath('//book[@id="1"]')
+puts book1.at_xpath('.//title').text  # => "Ruby Basics"
+
+# Find all titles
+titles = doc.xpath('//book/title')
+titles.each { |t| puts t.text }
+# => Ruby Basics
+# => Ruby Story
+
+# Find books by category
+programming = doc.xpath('//book[@category="programming"]')
+puts programming.first.at_xpath('.//title').text  # => "Ruby Basics"
+----
+
+=== Step 3: Create XML documents
+
+Build XML from scratch using the builder:
+
+[source,ruby]
+----
+doc = Moxml::Builder.build(context) do |xml|
+  xml.declaration version: "1.0", encoding: "UTF-8"
+
+  xml.library do
+    xml.book id: "1", category: "programming" do
+      xml.title "Ruby Basics"
+      xml.author "Jane Smith"
+      xml.price "29.99"
+    end
+  end
+end
+
+puts doc.to_xml(indent: 2)
+----
+
+Output:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<library>
+  <book id="1" category="programming">
+    <title>Ruby Basics</title>
+    <author>Jane Smith</author>
+    <price>29.99</price>
+  </book>
+</library>
+----
+
+=== Step 4: Modify XML content
+
+Update existing XML documents:
+
+[source,ruby]
+----
+xml = '<library><book id="1"><title>Old Title</title></book></library>'
+doc = context.parse(xml)
+
+# Find element to modify
+book = doc.at_xpath('//book[@id="1"]')
+
+# Update text content
+title = book.at_xpath('.//title')
+title.text = 'New Title'
+
+# Update attributes
+book['id'] = '100'
+book['category'] = 'programming'
+
+# Add new elements
+author = doc.create_element('author')
+author.text = 'Jane Smith'
+book.add_child(author)
+
+# Add price
+price = doc.create_element('price')
+price.text = '29.99'
+book.add_child(price)
+
+puts doc.to_xml(indent: 2)
+----
+
+=== Step 5: Work with attributes
+
+Manage element attributes:
+
+[source,ruby]
+----
+doc = context.parse('<book/>')
+book = doc.root
+
+# Set attributes
+book['id'] = '1'
+book['isbn'] = '978-0-123456-78-9'
+book['category'] = 'programming'
+
+# Get attributes
+puts book['id']        # => "1"
+puts book['isbn']      # => "978-0-123456-78-9"
+
+# Check attribute existence
+has_id = book.attributes.any? { |a| a.name == 'id' }
+puts has_id  # => true
+
+# Remove attributes
+book.remove_attribute('category')
+
+# List all attributes
+book.attributes.each do |attr|
+  puts "#{attr.name} = #{attr.value}"
+end
+----
+
+=== Step 6: Handle special content
+
+Work with CDATA, comments, and processing instructions:
+
+[source,ruby]
+----
+doc = context.create_document
+
+root = doc.create_element('data')
+doc.add_child(root)
+
+# Add comment
+comment = doc.create_comment('This is a note')
+root.add_child(comment)
+
+# Add CDATA section
+cdata = doc.create_cdata('<raw>XML content</raw>')
+root.add_child(cdata)
+
+# Add processing instruction
+pi = doc.create_processing_instruction('xml-stylesheet',
+  'type="text/xsl" href="style.xsl"')
+doc.add_child(pi)
+
+puts doc.to_xml
+----
+
+Output:
+
+[source,xml]
+----
+<?xml-stylesheet type="text/xsl" href="style.xsl"?>
+<data>
+  <!--This is a note-->
+  <![CDATA[<raw>XML content</raw>]]>
+</data>
+----
+
+=== Step 7: Error handling
+
+Handle XML processing errors:
+
+[source,ruby]
+----
+# Handle parse errors
+begin
+  doc = context.parse('<invalid><unclosed>', strict: true)
+rescue Moxml::ParseError => e
+  puts "Parse error: #{e.message}"
+  puts "Hint: #{e.to_s}"
+end
+
+# Handle XPath errors
+begin
+  doc.xpath('//invalid[[[')
+rescue Moxml::XPathError => e
+  puts "Invalid XPath: #{e.expression}"
+end
+
+# Handle validation errors
+begin
+  doc.version = "invalid"
+rescue Moxml::ValidationError => e
+  puts "Validation error: #{e.message}"
+end
+----
+
+=== Next steps
+
+* link:working-with-elements[Working with elements] - Deep dive into element
+manipulation
+* link:xpath-queries[XPath queries] - Master XPath querying
+* link:namespace-handling[Namespace handling] - Work with XML namespaces
+* link:../guides/[Guides] - Task-oriented documentation
+
+=== Practice exercises
+
+Try these exercises to reinforce your learning:
+
+. Parse an XML file from disk and find all elements with a specific attribute
+. Create a new XML document with nested elements and multiple attributes
+. Modify an existing document by adding, updating, and removing elements
+. Query a document using XPath with predicates
+. Handle namespaced XML documents