rng 0.1.2 → 0.3.3

data/Rakefile

@@ -1,12 +1,20 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
+require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
+
+# Extract external test fixtures from Jing-Trang spectest.xml
+namespace :fixtures do
+  desc "Extract external test resources from Jing-Trang's spectest.xml"
+  task :extract_spectest do
+    system('ruby scripts/extract_spectest_resources.rb')
+  end
+end

data/docs/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'bundler', '>= 2.0'
+gem 'jekyll', '~> 4.3'
+gem 'jekyll-asciidoc', '~> 3.0'
+gem 'just-the-docs', '~> 0.8'

data/docs/_config.yml

@@ -0,0 +1,23 @@
+title: RNG Ruby Gem
+description: A Ruby gem for parsing, manipulating, and converting RELAX NG schemas
+theme: just-the-docs
+
+plugins:
+  - jekyll-asciidoc
+
+asciidoc:
+  ext: .adoc
+  safe: unsafe
+
+collections:
+  guides:
+    output: true
+  reference:
+    output: true
+  getting-started:
+    output: true
+
+nav_sections:
+  getting-started: Getting Started
+  guides: Guides
+  reference: Reference

data/docs/getting-started/index.adoc

@@ -0,0 +1,75 @@
+---
+title: Getting Started
+layout: default
+nav_order: 2
+has_children: true
+---
+
+# Getting Started
+
+Learn how to install and use the RNG gem.
+
+## Installation
+
+```bash
+gem install rng
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'rng'
+```
+
+## Basic Usage
+
+### Parsing RNG XML
+
+```ruby
+require 'rng'
+
+# Parse from string
+rng_xml = <<~XML
+  <grammar xmlns="http://relaxng.org/ns/structure/1.0">
+    <start>
+      <element name="foo">
+        <empty/>
+      </element>
+    </start>
+  </grammar>
+XML
+
+grammar = Rng.parse(rng_xml)
+```
+
+### Parsing RNC Compact Syntax
+
+```ruby
+require 'rng'
+
+rnc_text = <<~RNC
+  element foo { empty }
+RNC
+
+grammar = Rng.parse_rnc(rnc_text)
+```
+
+### Converting Between Formats
+
+```ruby
+# RNG XML to RNC
+rng_xml = File.read('schema.rng')
+grammar = Rng.parse(rng_xml)
+rnc_output = Rng.to_rnc(grammar)
+
+# RNC to RNG XML
+rnc_text = File.read('schema.rnc')
+grammar = Rng.parse_rnc(rnc_text)
+rng_xml = grammar.to_xml
+```
+
+## Next Steps
+
+- Read the xref:guides/parsing-rng-xml.adoc[Parsing RNG XML] guide
+- Read the xref:guides/parsing-rnc.adoc[Parsing RNC] guide
+- Learn about xref:guides/external-references.adoc[External References]

data/docs/guides/error-handling.adoc

@@ -0,0 +1,137 @@
+---
+title: Error Handling
+layout: default
+nav_order: 5
+parent: Guides
+---
+
+= Error Handling
+
+The RNG gem provides specific error classes for different failure scenarios.
+
+== Error Classes
+
+=== `Rng::Error`
+
+Base error class for all RNG gem errors.
+
+[source,ruby]
+----
+begin
+  # ... RNG operations
+rescue Rng::Error => e
+  puts "RNG error: #{e.message}"
+end
+----
+
+=== `Rng::SchemaValidationError`
+
+Raised when schema validation fails.
+
+[source,ruby]
+----
+begin
+  Rng::SchemaValidator.validate(invalid_rng)
+rescue Rng::SchemaValidationError => e
+  puts "Validation failed: #{e.message}"
+end
+----
+
+=== `Rng::ExternalRefResolver::ExternalRefResolutionError`
+
+Raised when external reference resolution fails.
+
+[source,ruby]
+----
+begin
+  grammar = Rng.parse(rng_xml, location: path, resolve_external: true)
+rescue Rng::ExternalRefResolver::ExternalRefResolutionError => e
+  puts "Failed to resolve: #{e.href}"
+  puts "Cause: #{e.cause}"
+end
+----
+
+**Error attributes:**
+
+- `href` - The URI that failed to resolve
+- `cause` - The underlying error (`:circular`, `Errno::ENOENT`, or nil)
+
+== Common Error Scenarios
+
+=== File Not Found
+
+[source,ruby]
+----
+begin
+  grammar = Rng.parse(rng_xml, location: '/nonexistent/path.rng', resolve_external: true)
+rescue Rng::ExternalRefResolver::ExternalRefResolutionError => e
+  if e.cause == Errno::ENOENT
+    puts "External file not found: #{e.href}"
+  end
+end
+----
+
+=== Circular References
+
+[source,ruby]
+----
+begin
+  grammar = Rng.parse(circular_rng_xml, location: path, resolve_external: true)
+rescue Rng::ExternalRefResolver::ExternalRefResolutionError => e
+  if e.cause == :circular
+    puts "Circular reference detected at: #{e.href}"
+  end
+end
+----
+
+=== Invalid Schema Structure
+
+[source,ruby]
+----
+begin
+  grammar = Rng.parse(invalid_rng, validate: true)
+rescue Rng::SchemaValidationError => e
+  puts "Schema is invalid: #{e.message}"
+end
+----
+
+=== RNC Parse Errors
+
+[source,ruby]
+----
+begin
+  grammar = Rng.parse_rnc(invalid_rnc)
+rescue Parslet::ParseFailed => e
+  puts "RNC parse error: #{e.message}"
+end
+----
+
+== Handling Multiple Error Types
+
+[source,ruby]
+----
+begin
+  grammar = Rng.parse(rng_xml, validate: true, resolve_external: true)
+rescue Rng::SchemaValidationError => e
+  puts "Schema validation error: #{e.message}"
+rescue Rng::ExternalRefResolver::ExternalRefResolutionError => e
+  puts "External reference error: #{e.href}"
+rescue StandardError => e
+  puts "Unexpected error: #{e.class}: #{e.message}"
+end
+----
+
+== Verbose Mode
+
+Enable verbose logging for debugging:
+
+[source,bash]
+----
+RNG_VERBOSE=1 bundle exec ruby -e '
+  grammar = Rng.parse(File.read("schema.rng"), resolve_external: true)
+'
+----
+
+This outputs warnings for:
+- Unresolvable external references
+- Parsing issues

data/docs/guides/external-references.adoc

@@ -0,0 +1,128 @@
+---
+title: External References
+layout: default
+nav_order: 4
+parent: Guides
+---
+
+= External References
+
+The RNG format supports two types of external references that the gem can resolve.
+
+== Include Directive (`<include>`)
+
+The `<include>` directive at the grammar level merges definitions from an external grammar file.
+
+=== Example
+
+`main.rng`:
+[source,xml]
+----
+<grammar xmlns="http://relaxng.org/ns/structure/1.0">
+  <include href="library.rng"/>
+  <start>
+    <ref name="main-element"/>
+  </start>
+</grammar>
+----
+
+`library.rng`:
+[source,xml]
+----
+<grammar xmlns="http://relaxng.org/ns/structure/1.0">
+  <define name="main-element">
+    <element name="foo">
+      <empty/>
+    </element>
+  </define>
+</grammar>
+----
+
+=== Resolution
+
+[source,ruby]
+----
+grammar = Rng.parse(
+  File.read('main.rng'),
+  location: '/path/to/main.rng',
+  resolve_external: true
+)
+----
+
+After resolution, the `define` from `library.rng` is merged into `main.rng`.
+
+== ExternalRef (`<externalRef>`)
+
+The `<externalRef>` directive at the pattern level replaces itself with content from an external grammar's start pattern.
+
+=== Example
+
+`main.rng`:
+[source,xml]
+----
+<grammar xmlns="http://relaxng.org/ns/structure/1.0">
+  <start>
+    <group>
+      <externalRef href="external.rng"/>
+    </group>
+  </start>
+</grammar>
+----
+
+`external.rng`:
+[source,xml]
+----
+<grammar xmlns="http://relaxng.org/ns/structure/1.0">
+  <start>
+    <element name="bar">
+      <empty/>
+    </element>
+  </start>
+</grammar>
+----
+
+=== Resolution
+
+The `<externalRef>` is replaced with the content from `external.rng`'s start pattern:
+
+[source,xml]
+----
+<grammar xmlns="http://relaxng.org/ns/structure/1.0">
+  <start>
+    <group>
+      <element name="bar">
+        <empty/>
+      </element>
+    </group>
+  </start>
+</grammar>
+----
+
+== Circular Reference Detection
+
+The resolver detects circular references and raises an error:
+
+[source,ruby]
+----
+begin
+  grammar = Rng.parse(
+    File.read('circular.rng'),
+    location: '/path/to/circular.rng',
+    resolve_external: true
+  )
+rescue Rng::ExternalRefResolver::ExternalRefResolutionError => e
+  puts "Circular reference detected: #{e.href}"
+end
+----
+
+== Error Handling
+
+When external files cannot be found, the resolver issues a warning (when `RNG_VERBOSE=1`) and continues:
+
+[source,bash]
+----
+RNG_VERBOSE=1 bundle exec ruby -e '
+  grammar = Rng.parse(File.read("main.rng"), location: "/path", resolve_external: true)
+'
+# => Warning: Failed to resolve include "nonexistent.rng": External file not found: nonexistent.rng
+----

data/docs/guides/index.adoc

@@ -0,0 +1,24 @@
+---
+title: Guides
+layout: default
+nav_order: 3
+has_children: true
+---
+
+= Guides
+
+Step-by-step guides for common tasks with the RNG gem.
+
+== Available Guides
+
+* xref:parsing-rng-xml.adoc[Parsing RNG XML] - Parse and work with RNG XML format
+
+* xref:parsing-rnc.adoc[Parsing RNC] - Parse and work with RNC compact syntax
+
+* xref:rng-to-rnc.adoc[Converting Formats] - Convert between RNG and RNC formats
+
+* xref:validation.adoc[Schema Validation] - Validate RNG schemas
+
+* xref:external-references.adoc[External References] - Resolve include and externalRef directives
+
+* xref:error-handling.adoc[Error Handling] - Handle errors gracefully

data/docs/guides/parsing-rnc.adoc

@@ -0,0 +1,141 @@
+---
+title: Parsing RNC Compact Syntax
+layout: default
+nav_order: 2
+parent: Guides
+---
+
+= Parsing RNC Compact Syntax
+
+The RNG gem can parse RELAX NG schemas in compact syntax (RNC).
+
+== Basic Parsing
+
+[source,ruby]
+----
+require 'rng'
+
+rnc_text = <<~RNC
+  element foo {
+    element bar {
+      empty
+    }
+  }
+RNC
+
+grammar = Rng.parse_rnc(rnc_text)
+----
+
+== RNC Syntax Basics
+
+RNC is a more concise text representation of RELAX NG schemas.
+
+=== Elements
+
+[source,rnc]
+----
+element name { content }
+----
+
+=== Attributes
+
+[source,rnc]
+----
+attribute name { type }
+----
+
+=== Sequences and Choices
+
+[source,rnc]
+----
+# Sequence (both required)
+element a {}, element b {}
+
+# Choice (one of)
+element a {} | element b {}
+
+# Grouping with parentheses
+(element a {} | element b {}), element c {}
+----
+
+=== Occurrence Indicators
+
+[source,rnc]
+----
+# Optional (0 or 1)
+element foo?
+
+# Zero or more
+element foo*
+
+# One or more
+element foo+
+----
+
+=== Named Definitions
+
+[source,rnc]
+----
+# Define a named pattern
+patternName = element foo { empty }
+
+# Reference a named pattern
+element bar {
+  patternName
+}
+----
+
+=== Combining Patterns
+
+[source,rnc]
+----
+# Interleave (interleave is the default for elements)
+element foo { element a {} & element b {} }
+
+# Mixed content
+mixed { element p {} | text }
+----
+
+== Working with Parse Results
+
+The parsed grammar provides access to all definitions:
+
+[source,ruby]
+----
+grammar = Rng.parse_rnc(rnc_text)
+
+# Access start pattern
+grammar.start.each do |start_pattern|
+  puts start_pattern.to_xml
+end
+
+# Access named definitions
+grammar.define.each do |define|
+  puts "#{define.name}: #{define.element.map(&:attr_name).join(', ')}"
+end
+----
+
+== Converting RNC to RNG
+
+[source,ruby]
+----
+# Parse RNC and convert to RNG XML
+grammar = Rng.parse_rnc(rnc_text)
+rng_xml = grammar.to_xml
+
+puts rng_xml
+----
+
+== Using with External References
+
+When your RNC file uses `include` directives:
+
+[source,ruby]
+----
+grammar = Rng.parse_rnc(
+  File.read('schema.rnc'),
+  location: '/path/to/schema.rnc'
+)
+----
+
+Note: RNC include resolution is built into the RNC parser itself.

data/docs/guides/parsing-rng-xml.adoc

@@ -0,0 +1,81 @@
+---
+title: Parsing RNG XML
+layout: default
+nav_order: 3
+parent: Getting Started
+---
+
+= Parsing RNG XML
+
+The RNG gem can parse RELAX NG schemas in XML format.
+
+== Basic Parsing
+
+[source,ruby]
+----
+require 'rng'
+
+rng_xml = <<~XML
+  <grammar xmlns="http://relaxng.org/ns/structure/1.0">
+    <start>
+      <element name="foo">
+        <empty/>
+      </element>
+    </start>
+  </grammar>
+XML
+
+grammar = Rng.parse(rng_xml)
+----
+
+== With Location
+
+When your RNG file references external resources (via `<include>` or `<externalRef>`), provide the file location for proper relative path resolution:
+
+[source,ruby]
+----
+grammar = Rng.parse(
+  File.read('schema.rng'),
+  location: '/path/to/schema.rng'
+)
+----
+
+== Resolving External References
+
+By default, external references are NOT resolved. To resolve them:
+
+[source,ruby]
+----
+grammar = Rng.parse(
+  File.read('schema.rng'),
+  location: '/path/to/schema.rng',
+  resolve_external: true
+)
+----
+
+This will:
+
+- Process `<include href="..."/>` at the grammar level - merges definitions from external grammars
+- Process `<externalRef href="..."/>` at the pattern level - replaces with content from external grammars
+
+== Accessing Grammar Elements
+
+The parsed grammar provides access to all elements:
+
+[source,ruby]
+----
+grammar.start       # => Array of Start patterns
+grammar.define      # => Array of Define patterns
+grammar.element     # => Array of top-level Element patterns
+grammar.include     # => Array of Include directives
+grammar.div         # => Array of Div elements
+----
+
+== Generating XML Output
+
+Convert the grammar back to XML:
+
+[source,ruby]
+----
+puts grammar.to_xml
+----