rng 0.1.2 → 0.3.4

data/docs/guides/rng-to-rnc.adoc

@@ -0,0 +1,101 @@
+---
+title: Converting RNG to RNC
+layout: default
+nav_order: 3
+parent: Guides
+---
+
+= Converting Between RNG and RNC
+
+The RNG gem supports converting between RNG XML format and RNC compact syntax.
+
+== RNG to RNC Conversion
+
+Convert a grammar parsed from RNG XML to RNC compact syntax:
+
+[source,ruby]
+----
+require 'rng'
+
+# Parse RNG XML
+rng_xml = File.read('schema.rng')
+grammar = Rng.parse(rng_xml)
+
+# Convert to RNC
+rnc_output = Rng.to_rnc(grammar)
+
+puts rnc_output
+----
+
+== RNC to RNG Conversion
+
+Convert RNC compact syntax to RNG XML:
+
+[source,ruby]
+----
+require 'rng'
+
+# Parse RNC
+rnc_text = File.read('schema.rnc')
+grammar = Rng.parse_rnc(rnc_text)
+
+# Convert to RNG XML
+rng_xml = grammar.to_xml
+
+puts rng_xml
+----
+
+== Using the CLI
+
+The gem includes a CLI for quick conversions:
+
+[source,bash]
+----
+# RNG to RNC
+rng convert schema.rng -O rnc -o schema_converted.rnc
+
+# RNC to RNG
+rng convert schema.rnc -O rng -o schema_converted.rng
+----
+
+== Round-Trip Conversion
+
+The gem is designed to produce correct output that can be re-parsed:
+
+[source,ruby]
+----
+# Parse RNC
+grammar1 = Rng.parse_rnc(rnc_text)
+
+# Convert to RNG and back to RNC
+rng_xml = grammar1.to_xml
+grammar2 = Rng.parse(rng_xml)
+rnc_output = Rng.to_rnc(grammar2)
+
+# Both grammars should be equivalent
+----
+
+== Limitations
+
+1. **Whitespace handling**: Whitespace in RNC is normalized during parsing
+2. **Comments**: RNC comments are not preserved in RNG XML output
+3. **Foreign elements**: Elements from non-RNG namespaces are dropped
+4. **Name classes**: Complex name classes may serialize differently but remain semantically equivalent
+
+== Format Selection
+
+The conversion direction is inferred from the input format:
+
+| Input Format | Output Format |
+|--------------|---------------|
+| `.rnc` file  | RNG XML       |
+| `.rng` file  | RNC           |
+| Unknown      | RNG XML       |
+
+Use explicit format flags when the inference is incorrect:
+
+[source,bash]
+----
+rng convert input.rnc output.rng -O rng
+rng convert input.rng output.rnc -O rnc
+----

data/docs/guides/validation.adoc

@@ -0,0 +1,85 @@
+---
+title: Schema Validation
+layout: default
+nav_order: 4
+parent: Guides
+---
+
+= Schema Validation
+
+The RNG gem provides structural validation of RNG schemas.
+
+== Validating a Schema
+
+Validate that an RNG schema is well-formed and follows RELAX NG rules:
+
+[source,ruby]
+----
+require 'rng'
+
+begin
+  Rng::SchemaValidator.validate(rng_xml)
+  puts "Schema is valid"
+rescue Rng::SchemaValidationError => e
+  puts "Schema validation error: #{e.message}"
+end
+----
+
+== Validation During Parsing
+
+You can also validate during parsing with the `validate:` option:
+
+[source,ruby]
+----
+grammar = Rng.parse(rng_xml, validate: true)
+----
+
+This is equivalent to:
+
+[source,ruby]
+----
+Rng::SchemaValidator.validate(rng_xml)
+grammar = Rng.parse(rng_xml)
+----
+
+== Schema Validation Errors
+
+When validation fails, a `Rng::SchemaValidationError` is raised:
+
+[source,ruby]
+----
+begin
+  Rng::SchemaValidator.validate(invalid_rng_xml)
+rescue Rng::SchemaValidationError => e
+  puts e.message
+  puts e.errors if e.respond_to?(:errors)
+end
+----
+
+== What Gets Validated
+
+The SchemaValidator checks:
+
+1. **Grammar structure**: Start element, proper define elements
+2. **Pattern validity**: Elements properly nested, correct attributes
+3. **Name class validity**: NCName, QName, nsName proper usage
+4. **Datatype Library**: Correct datatype library references
+5. **Reference integrity**: Refs point to defined patterns
+
+== Limitations
+
+Schema validation does NOT:
+
+- Validate XML documents against the schema (use a validator like Jing for that)
+- Check semantic equivalence of patterns
+- Validate external references (those require I/O)
+
+== Schema Structure Validation
+
+The gem validates the schema structure when parsing with `validate: true`:
+
+[source,ruby]
+----
+# This will raise if the schema is invalid
+grammar = Rng.parse(File.read('invalid_schema.rng'), validate: true)
+----

data/docs/index.adoc

@@ -0,0 +1,52 @@
+---
+title: RNG Ruby Gem
+nav_order: 1
+---
+
+# RNG Ruby Gem
+
+A Ruby gem for parsing, manipulating, and converting RELAX NG schemas (both RNG XML and RNC compact syntax).
+
+## Features
+
+- Parse RNG XML format
+- Parse RNC compact syntax
+- Convert between RNG and RNC formats
+- Validate RNG schemas
+- Resolve external references (`<include>` and `<externalRef>`)
+
+## Installation
+
+```bash
+gem install rng
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'rng'
+```
+
+## Quick Start
+
+```ruby
+require 'rng'
+
+# Parse RNG XML
+rng_xml = File.read('schema.rng')
+grammar = Rng.parse(rng_xml)
+
+# Parse RNC compact syntax
+rnc_text = File.read('schema.rnc')
+grammar = Rng.parse_rnc(rnc_text)
+
+# Convert RNG to RNC
+rnc_output = Rng.to_rnc(grammar)
+
+# Resolve external references
+grammar = Rng.parse(rng_xml, location: '/path/to/schema.rng', resolve_external: true)
+```
+
+## Status
+
+This gem is under active development. The core parsing functionality is complete and well-tested against the Jing-Trang test suite.

data/docs/reference/api.adoc

@@ -0,0 +1,126 @@
+---
+title: API Reference
+layout: default
+nav_order: 5
+has_children: true
+---
+
+= API Reference
+
+Complete API documentation for the RNG gem.
+
+== Main Module: `Rng`
+
+=== `Rng.parse`
+
+Parse RNG XML format.
+
+[source,ruby]
+----
+Rng.parse(rng_xml, location: nil, nested_schema: false, validate: false, resolve_external: false)
+----
+
+**Parameters:**
+
+- `rng_xml` (String) - The RNG XML content
+- `location` (String, optional) - File location for resolving relative external refs
+- `nested_schema` (Boolean, default: false) - Whether this is a nested schema
+- `validate` (Boolean, default: false) - Whether to validate the schema
+- `resolve_external` (Boolean, default: false) - Whether to resolve external refs
+
+**Returns:** `Rng::Grammar`
+
+=== `Rng.parse_rnc`
+
+Parse RNC compact syntax.
+
+[source,ruby]
+----
+Rng.parse_rnc(rnc_text, location: nil)
+----
+
+**Parameters:**
+
+- `rnc_text` (String) - The RNC compact syntax content
+- `location` (String, optional) - File location for include resolution
+
+**Returns:** `Rng::Grammar`
+
+=== `Rng.to_rnc`
+
+Convert a Grammar to RNC compact syntax.
+
+[source,ruby]
+----
+Rng.to_rnc(grammar)
+----
+
+**Parameters:**
+
+- `grammar` (Rng::Grammar) - The grammar to convert
+
+**Returns:** String (RNC text)
+
+=== `Rng::Grammar.from_xml`
+
+Create a Grammar from XML.
+
+[source,ruby]
+----
+Rng::Grammar.from_xml(xml_string)
+----
+
+=== `Rng::SchemaValidator.validate`
+
+Validate an RNG schema.
+
+[source,ruby]
+----
+Rng::SchemaValidator.validate(rng_xml)
+----
+
+**Raises:** `Rng::SchemaValidationError` if invalid
+
+== Grammar Object Model
+
+The gem uses Lutaml::Model for the object model. All classes inherit from `Lutaml::Model::Serializable`.
+
+=== Core Classes
+
+- `Rng::Grammar` - Root container
+- `Rng::Start` - Entry point definition
+- `Rng::Define` - Named pattern definitions
+- `Rng::Element` - XML element patterns
+- `Rng::Attribute` - XML attribute patterns
+- `Rng::Group`, `Rng::Choice`, `Rng::Interleave` - Compositors
+- `Rng::Optional`, `Rng::ZeroOrMore`, `Rng::OneOrMore` - Occurrence indicators
+- `Rng::Ref`, `Rng::ParentRef`, `Rng::ExternalRef` - References
+- `Rng::Text`, `Rng::Empty`, `Rng::NotAllowed` - Basic patterns
+- `Rng::Value`, `Rng::Data`, `Rng::List` - Data patterns
+
+=== Common Methods
+
+All pattern objects support:
+
+- `.to_xml` - Convert to XML string
+- `.to_h` - Convert to hash representation
+
+== Error Classes
+
+=== `Rng::Error`
+
+Base error class.
+
+=== `Rng::SchemaValidationError`
+
+Raised when schema validation fails.
+
+=== `Rng::ExternalRefResolver::ExternalRefResolutionError`
+
+Raised when external reference resolution fails.
+
+[source,ruby]
+----
+error.href   # => The href that failed
+error.cause  # => :circular, Errno::ENOENT, or nil
+----

data/docs/reference/cli.adoc

@@ -0,0 +1,182 @@
+---
+title: CLI Reference
+layout: default
+nav_order: 2
+parent: Reference
+---
+
+= CLI Reference
+
+The RNG gem includes a command-line interface for common tasks.
+
+== Installation
+
+The CLI is automatically installed with the gem:
+
+[source,bash]
+----
+gem install rng
+rng --version
+----
+
+== Global Options
+
+[source,bash]
+----
+-v, --verbose    # Verbose output
+-q, --quiet      # Suppress non-error output
+-h, --help       # Show help
+--version        # Show version number
+----
+
+== Commands
+
+=== validate
+
+Validate an XML document against a RELAX NG schema (replaces Jing).
+
+[source,bash]
+----
+rng validate SCHEMA [DOCUMENT]
+----
+
+**Options:**
+
+- `-c, --compact` - Schema is in RNC compact format
+- `-x, --xml` - Schema is in RNG XML format (default: auto-detect)
+- `-o, --output FORMAT` - Output format: text, xml, json
+
+**Examples:**
+
+[source,bash]
+----
+# Validate a schema
+rng validate schema.rng
+
+# Validate an XML document
+rng validate schema.rng document.xml
+
+# Validate with RNC schema
+rng validate -c schema.rnc document.xml
+----
+
+=== convert
+
+Convert between RNC and RNG formats (replaces Trang).
+
+[source,bash]
+----
+rng convert INPUT [OUTPUT]
+----
+
+**Options:**
+
+- `-I, --input-format FORMAT` - Input format: rng, rnc, auto
+- `-O, --output-format FORMAT` - Output format: rng, rnc, auto
+
+**Examples:**
+
+[source,bash]
+----
+# RNC to RNG
+rng convert schema.rnc -o schema.rng
+
+# RNG to RNC
+rng convert schema.rng schema_converted.rnc
+----
+
+=== parse
+
+Parse a schema and display its structure.
+
+[source,bash]
+----
+rng parse SCHEMA
+----
+
+**Options:**
+
+- `-f, --format FORMAT` - Output format: text, json, yaml, xml
+- `--ast` - Show abstract syntax tree (RNC only)
+
+**Examples:**
+
+[source,bash]
+----
+# Text output (default)
+rng parse schema.rng
+
+# JSON output
+rng parse -f json schema.rng
+----
+
+=== info
+
+Show information about a schema.
+
+[source,bash]
+----
+rng info SCHEMA
+----
+
+**Options:**
+
+- `--statistics` - Show pattern statistics
+- `--namespaces` - List used namespaces
+
+**Examples:**
+
+[source,bash]
+----
+# Basic info
+rng info schema.rng
+
+# With statistics
+rng info --statistics schema.rng
+----
+
+=== version
+
+Show version number.
+
+[source,bash]
+----
+rng version
+----
+
+== Exit Codes
+
+- `0` - Success
+- `1` - Invalid input or validation failure
+- `2` - Error (file not found, parse error, etc.)
+
+== Examples
+
+=== Validate a document
+
+[source,bash]
+----
+$ rng validate spec/fixtures/rng/xhtml.rng spec/fixtures/xhtml/sample.xml
+Validating spec/fixtures/rng/xhtml.rng against spec/fixtures/xhtml/sample.xml...
+Document is valid
+----
+
+=== Convert a schema
+
+[source,bash]
+----
+$ rng convert spec/fixtures/rng/address_book.rng -o /tmp/address_book.rnc
+Converting spec/fixtures/rng/address_book.rng (rng) to rnc...
+Written to /tmp/address_book.rnc
+----
+
+=== Inspect a schema
+
+[source,bash]
+----
+$ rng parse spec/fixtures/rng/address_book.rng
+Schema Structure:
+  Start: Start
+  Definitions:
+    cardContent: element
+----

data/docs/understanding/architecture.adoc

@@ -0,0 +1,58 @@
+---
+title: Architecture
+layout: default
+nav_order: 3
+parent: Understanding
+---
+
+= Architecture
+
+The RNG gem has two parsing paths and one generation path.
+
+== RNG XML Parsing
+
+[source]
+----
+Rng.parse() → Grammar.from_xml() → Lutaml::Model with Nokogiri adapter
+----
+
+All RNG model classes inherit from `Lutaml::Model::Serializable` and define XML mappings via the `xml do` block.
+
+== RNC Compact Parsing
+
+[source]
+----
+Rng.parse_rnc() → RncParser.parse() → ParseTreeProcessor.normalize()
+    → RncToRngConverter.convert() → Grammar.from_xml()
+----
+
+The RNC parser is a Parslet-based PEG parser in `lib/rng/rnc_parser.rb`.
+
+== RNG to RNC Generation
+
+[source]
+----
+Rng.to_rnc() → ToRnc.convert() → RncBuilder.build()
+----
+
+`RncBuilder` traverses the object model and generates RNC text.
+
+== Object Model Structure
+
+The object model mirrors RELAX NG concepts:
+
+- `Grammar` - Root container
+- `Start` - Entry point definition
+- `Define` - Named pattern definitions
+- `Element`, `Attribute` - XML structures
+- Pattern classes: `Choice`, `Group`, `Interleave`, `Mixed`, `Optional`, `ZeroOrMore`, `OneOrMore`, `Text`, `Empty`, `Value`, `Data`, `List`
+- Reference classes: `Ref`, `ParentRef`, `ExternalRef`
+- Name classes: `Name`, `AnyName`, `NsName`, `Except`
+- `Div` - Documentation and grouping container
+
+== Dependencies
+
+- **lutaml-model** - Object model and XML serialization
+- **nokogiri** - XML parsing and building
+- **parslet** - RNC compact syntax parser
+- **canon** - XML comparison matchers for tests

data/docs/understanding/rng-vs-rnc.adoc

@@ -0,0 +1,118 @@
+---
+title: RNG vs RNC
+layout: default
+nav_order: 1
+parent: Understanding
+---
+
+= RNG vs RNC
+
+RELAX NG schemas can be written in two formats: XML (RNG) and Compact (RNC).
+
+== RNG XML Format
+
+RNG is the XML-based representation of RELAX NG schemas.
+
+=== Example
+
+[source,xml]
+----
+<grammar xmlns="http://relaxng.org/ns/structure/1.0">
+  <start>
+    <element name="person">
+      <zeroOrMore>
+        <element name="child">
+          <empty/>
+        </element>
+      </zeroOrMore>
+    </element>
+  </start>
+</grammar>
+----
+
+=== Advantages
+
+- **Standard XML tools**: Can be edited with any XML editor
+- **Explicit structure**: All elements and attributes are visible
+- **Namespaces**: Full namespace support is natural
+- **Transformation**: Can be processed with XSLT
+- **Validation**: Can be validated with XML schemas
+
+=== Disadvantages
+
+- **Verbose**: More characters to type
+- **Less readable**: Harder to scan quickly
+- **XML overhead**: Requires proper escaping
+
+== RNC Compact Syntax
+
+RNC is a text-based shorthand for RELAX NG schemas.
+
+=== Example
+
+[source,rnc]
+----
+element person {
+  element child {
+    empty
+  }*
+}
+----
+
+=== Advantages
+
+- **Concise**: Much shorter than equivalent XML
+- **Readable**: Easier to see the structure at a glance
+- **Programming-like**: Familiar syntax for developers
+- **Quick prototyping**: Faster to write and modify
+
+=== Disadvantages
+
+- **No native tools**: Requires conversion for XML tools
+- **Escaping**: Special characters need escaping
+- **Limited namespace support**: More complex namespace handling
+
+== When to Use Each
+
+=== Use RNG when:
+
+- You need to validate the schema itself with XML tools
+- You're integrating with XML processing pipelines
+- Namespace handling is critical
+- You need to embed schema documentation in foreign elements
+- You're working with teams more familiar with XML
+
+=== Use RNC when:
+
+- You want a quick prototype
+- The schema is primarily for Ruby processing
+- Readability is more important than tool compatibility
+- You're writing tests or examples
+
+== Conversion
+
+Both formats are fully equivalent - you can convert between them without loss:
+
+[source,ruby]
+----
+# RNG to RNC
+grammar = Rng.parse(rng_xml)
+rnc = Rng.to_rnc(grammar)
+
+# RNC to RNG
+grammar = Rng.parse_rnc(rnc_text)
+rng_xml = grammar.to_xml
+----
+
+== Quick Reference
+
+| Feature | RNG | RNC |
+|---------|-----|-----|
+| Element | `<element name="foo">...</element>` | `element foo { ... }` |
+| Attribute | `<attribute name="bar">...</attribute>` | `attribute bar { ... }` |
+| Optional | `<optional>...</optional>` | `... ?` |
+| Zero or more | `<zeroOrMore>...</zeroOrMore>` | `... *` |
+| One or more | `<oneOrMore>...</oneOrMore>` | `... +` |
+| Choice | `<choice>...</choice>` | `... \| ...` |
+| Sequence | `<group>...</group>` | `..., ...` |
+| Interleave | `<interleave>...</interleave>` | `... & ...` |