xseed 1.0.0

data/examples/advanced_usage.rb

@@ -0,0 +1,286 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Advanced SVG Generation Usage
+#
+# This example demonstrates advanced features of Xseed including
+# parser introspection, complex error handling, and custom workflows.
+
+require "bundler/setup"
+require "xseed"
+require "fileutils"
+
+# Advanced Example 1: Parser introspection and metadata extraction
+def example_parser_introspection
+  puts "Advanced Example 1: Parser Introspection"
+  puts "=" * 60
+
+  xsd_file = File.join(__dir__, "schemas", "person.xsd")
+  parser = Xseed::Parser::XsdParser.new(xsd_file)
+
+  puts "Schema Metadata:"
+  puts "  Target Namespace: #{parser.target_namespace || 'None'}"
+  puts "  Version: #{parser.schema_version || 'Not specified'}"
+  puts "  Element Form Default: #{parser.element_form_default || 'Not specified'}"
+  puts ""
+
+  puts "Global Elements:"
+  parser.elements.each do |element|
+    name = element["name"] || element.name
+    type = element["type"] || "inline"
+    puts "  - #{name} (#{type})"
+
+    # Extract documentation
+    doc = parser.element_documentation(name)
+    puts "    Doc: #{doc.strip}" if doc
+  end
+  puts ""
+
+  puts "Complex Types:"
+  parser.complex_types.each do |type|
+    name = type["name"] || type.name
+    puts "  - #{name}"
+
+    # Extract documentation
+    doc = parser.type_documentation(name)
+    puts "    Doc: #{doc.strip}" if doc
+  end
+  puts ""
+
+  puts "Simple Types:"
+  parser.simple_types.each do |type|
+    name = type["name"] || type.name
+    puts "  - #{name}"
+  end
+  puts ""
+
+  puts "Namespaces:"
+  parser.namespaces.each do |prefix, uri|
+    puts "  #{prefix}: #{uri}"
+  end
+  puts "\n"
+end
+
+# Advanced Example 2: Conditional generation based on schema analysis
+def example_conditional_generation
+  puts "Advanced Example 2: Conditional Generation"
+  puts "=" * 60
+
+  xsd_file = File.join(__dir__, "schemas", "person.xsd")
+  parser = Xseed::Parser::XsdParser.new(xsd_file)
+
+  # Analyze schema complexity
+  total_components = parser.elements.size + parser.types.size
+  puts "Schema complexity: #{total_components} components"
+
+  if total_components > 50
+    puts "⚠ Large schema detected - generation may take time"
+  else
+    puts "✓ Schema size is optimal"
+  end
+
+  # Check for documentation
+  has_docs = !parser.documentation.nil?
+  puts has_docs ? "✓ Schema has documentation" : "⚠ No schema-level documentation"
+
+  # Generate with awareness of complexity
+  output_file = File.join(__dir__, "output", "conditional-person.svg")
+  FileUtils.mkdir_p(File.dirname(output_file))
+
+  start_time = Time.now
+  generator = Xseed::Svg::SvgGenerator.new(xsd_file)
+  generator.generate_file(output_file)
+  elapsed = Time.now - start_time
+
+  puts "\nGeneration completed in #{(elapsed * 1000).round(2)}ms"
+  puts "Output: #{output_file}\n\n"
+end
+
+# Advanced Example 3: Custom error handling and logging
+def example_custom_error_handling
+  puts "Advanced Example 3: Custom Error Handling"
+  puts "=" * 60
+
+  test_files = [
+    File.join(__dir__, "schemas", "person.xsd"),
+    File.join(__dir__, "schemas", "nonexistent.xsd"),
+    File.join(__dir__, "invalid.txt"),
+  ]
+
+  results = { success: [], failed: [] }
+
+  test_files.each do |xsd_file|
+    puts "Processing: #{File.basename(xsd_file)}..."
+
+    generator = Xseed::Svg::SvgGenerator.new(xsd_file)
+    output_file = File.join(__dir__, "output",
+                            "#{File.basename(xsd_file, '.xsd')}.svg")
+    FileUtils.mkdir_p(File.dirname(output_file))
+
+    generator.generate_file(output_file)
+    results[:success] << xsd_file
+    puts "  ✓ Success\n"
+  rescue ArgumentError => e
+    results[:failed] << { file: xsd_file, error: "Validation: #{e.message}" }
+    puts "  ✗ Validation error: #{e.message}\n"
+  rescue Xseed::ParserError => e
+    results[:failed] << { file: xsd_file, error: "Parser: #{e.message}" }
+    puts "  ✗ Parser error: #{e.message}\n"
+  rescue Xseed::Svg::GenerationError => e
+    results[:failed] << { file: xsd_file, error: "Generation: #{e.message}" }
+    puts "  ✗ Generation error: #{e.message}\n"
+  rescue StandardError => e
+    results[:failed] << { file: xsd_file, error: "Unexpected: #{e.message}" }
+    puts "  ✗ Unexpected error: #{e.message}\n"
+  end
+
+  puts "\nSummary:"
+  puts "  Successful: #{results[:success].size}"
+  puts "  Failed: #{results[:failed].size}"
+
+  if results[:failed].any?
+    puts "\nFailed files:"
+    results[:failed].each do |failure|
+      puts "  - #{File.basename(failure[:file])}: #{failure[:error]}"
+    end
+  end
+
+  puts "\n"
+end
+
+# Advanced Example 4: Performance monitoring
+def example_performance_monitoring
+  puts "Advanced Example 4: Performance Monitoring"
+  puts "=" * 60
+
+  xsd_file = File.join(__dir__, "schemas", "person.xsd")
+  output_file = File.join(__dir__, "output", "perf-person.svg")
+  FileUtils.mkdir_p(File.dirname(output_file))
+
+  # Measure each phase
+  timings = {}
+
+  # Phase 1: File validation
+  timings[:validation] = measure_time do
+    File.exist?(xsd_file) && File.readable?(xsd_file)
+  end
+
+  # Phase 2: Parsing
+  parser = nil
+  timings[:parsing] = measure_time do
+    parser = Xseed::Parser::XsdParser.new(xsd_file)
+  end
+
+  # Phase 3: Generation
+  generator = Xseed::Svg::SvgGenerator.new(xsd_file)
+  timings[:generation] = measure_time do
+    generator.generate
+  end
+
+  # Phase 4: File writing
+  timings[:writing] = measure_time do
+    generator.generate_file(output_file)
+  end
+
+  # Total time
+  total = timings.values.sum
+
+  puts "Performance Breakdown:"
+  puts "  Validation:  #{format_time(timings[:validation])}"
+  puts "  Parsing:     #{format_time(timings[:parsing])}"
+  puts "  Generation:  #{format_time(timings[:generation])}"
+  puts "  File Write:  #{format_time(timings[:writing])}"
+  puts "  ─────────────────────────"
+  puts "  Total:       #{format_time(total)}"
+
+  # File size info
+  file_size = File.size(output_file)
+  puts "\nOutput File:"
+  puts "  Path: #{output_file}"
+  puts "  Size: #{format_bytes(file_size)}"
+  puts "  Rate: #{format_bytes(file_size / total)}/s" if total.positive?
+
+  puts "\n"
+end
+
+# Advanced Example 5: Integration with other tools
+def example_tool_integration
+  puts "Advanced Example 5: Tool Integration"
+  puts "=" * 60
+
+  xsd_file = File.join(__dir__, "schemas", "person.xsd")
+  svg_file = File.join(__dir__, "output", "person-optimized.svg")
+  FileUtils.mkdir_p(File.dirname(svg_file))
+
+  # Generate SVG
+  puts "Step 1: Generate SVG..."
+  generator = Xseed::Svg::SvgGenerator.new(xsd_file)
+  generator.generate_file(svg_file)
+  puts "  ✓ Generated: #{svg_file}"
+
+  # Example: Validate SVG with xmllint (if available)
+  if system("which xmllint > /dev/null 2>&1")
+    puts "\nStep 2: Validate SVG with xmllint..."
+    if system("xmllint --noout #{svg_file} 2>&1")
+      puts "  ✓ SVG is valid XML"
+    else
+      puts "  ✗ SVG validation failed"
+    end
+  else
+    puts "\nStep 2: xmllint not available (skipping validation)"
+  end
+
+  # Example: Display stats
+  puts "\nStep 3: File statistics..."
+  lines = File.readlines(svg_file).size
+  bytes = File.size(svg_file)
+  puts "  Lines: #{lines}"
+  puts "  Size: #{format_bytes(bytes)}"
+
+  puts "\n"
+end
+
+# Helper methods
+def measure_time
+  start = Time.now
+  yield
+  Time.now - start
+end
+
+def format_time(seconds)
+  if seconds < 0.001
+    "#{(seconds * 1_000_000).round(2)}μs"
+  elsif seconds < 1
+    "#{(seconds * 1000).round(2)}ms"
+  else
+    "#{seconds.round(3)}s"
+  end
+end
+
+def format_bytes(bytes)
+  if bytes < 1024
+    "#{bytes}B"
+  elsif bytes < 1024 * 1024
+    "#{(bytes / 1024.0).round(2)}KB"
+  else
+    "#{(bytes / 1024.0 / 1024.0).round(2)}MB"
+  end
+end
+
+# Run all advanced examples
+if __FILE__ == $PROGRAM_NAME
+  puts "\n"
+  puts "╔#{'═' * 58}╗"
+  puts "║#{' ' * 11}Xseed Advanced Usage Examples#{' ' * 16}║"
+  puts "╚#{'═' * 58}╝"
+  puts "\n"
+
+  example_parser_introspection
+  example_conditional_generation
+  example_custom_error_handling
+  example_performance_monitoring
+  example_tool_integration
+
+  puts "All advanced examples completed!"
+  puts "\nGenerated files are in: #{File.join(__dir__, 'output')}"
+end

data/examples/html_generation.rb

@@ -0,0 +1,167 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage Examples for Xseed HTML Documentation Generation
+# Phase 2: Weeks 5-6 - Final Integration and Testing
+
+require_relative "../lib/xseed"
+
+puts "=== Xseed HTML Documentation Generation Examples ===\n\n"
+
+# Example 1: Basic HTML generation
+puts "Example 1: Basic HTML Generation"
+puts "-" * 50
+
+begin
+  # Create generator with default configuration
+  xsd_path = File.expand_path("../spec/fixtures/simple/element_only.xsd",
+                              __dir__)
+  generator = Xseed::Documentation::HtmlGenerator.new(xsd_path)
+
+  # Generate HTML to string
+  html = generator.generate
+
+  # Write to file
+  output_path = File.expand_path("../tmp/example1_basic.html", __dir__)
+  FileUtils.mkdir_p(File.dirname(output_path))
+  File.write(output_path, html)
+
+  puts "✓ Generated basic HTML documentation"
+  puts "  Output: tmp/example1_basic.html"
+  puts "  Features: Default styling, navigation, properties tables, instance samples"
+  puts
+rescue StandardError => e
+  puts "✗ Error: #{e.message}"
+  puts
+end
+
+# Example 2: Custom configuration
+puts "Example 2: Custom Configuration"
+puts "-" * 50
+
+begin
+  # Create custom configuration
+  config = Xseed::Documentation::Config.new
+  config.title = "My Custom Schema Documentation"
+  config.sort_by_component = true
+  config.print_glossary = true
+
+  # Create generator with custom config
+  xsd_path = File.expand_path("../spec/fixtures/simple/element_only.xsd",
+                              __dir__)
+  generator = Xseed::Documentation::HtmlGenerator.new(xsd_path, config)
+
+  # Generate directly to file
+  output_path = File.expand_path("../tmp/example2_custom.html", __dir__)
+  FileUtils.mkdir_p(File.dirname(output_path))
+  generator.generate_file(output_path)
+
+  puts "✓ Generated HTML with custom configuration"
+  puts "  Output: tmp/example2_custom.html"
+  puts "  Custom title: #{config.title}"
+  puts "  Sorted by component: #{config.sort_by_component}"
+  puts "  Includes glossary: #{config.print_glossary}"
+  puts
+rescue StandardError => e
+  puts "✗ Error: #{e.message}"
+  puts
+end
+
+# Example 3: External CSS/JS (demonstration)
+puts "Example 3: External CSS/JS Configuration"
+puts "-" * 50
+
+begin
+  # Create configuration with external resources
+  config = Xseed::Documentation::Config.new
+  config.title = "Schema with External Resources"
+  # NOTE: These would typically point to actual hosted files
+  # config.external_css_url = "https://example.com/custom.css"
+  # config.jquery_url = "https://example.com/jquery.js"
+
+  xsd_path = File.expand_path("../spec/fixtures/simple/element_only.xsd",
+                              __dir__)
+  generator = Xseed::Documentation::HtmlGenerator.new(xsd_path, config)
+
+  html = generator.generate
+  output_path = File.expand_path("../tmp/example3_external.html", __dir__)
+  FileUtils.mkdir_p(File.dirname(output_path))
+  File.write(output_path, html)
+
+  puts "✓ Generated HTML with external resource configuration"
+  puts "  Output: tmp/example3_external.html"
+  puts "  Note: External CSS/JS URLs can be configured via Config object"
+  puts "  Default: Uses embedded styles and CDN-hosted jQuery/Bootstrap"
+  puts
+rescue StandardError => e
+  puts "✗ Error: #{e.message}"
+  puts
+end
+
+# Example 4: Batch generation
+puts "Example 4: Batch Generation"
+puts "-" * 50
+
+begin
+  # Define schemas to process
+  base_dir = File.expand_path("..", __dir__)
+  schemas = [
+    File.join(base_dir, "spec/fixtures/simple/element_only.xsd"),
+  ]
+
+  # Process each schema
+  tmp_dir = File.expand_path("../tmp", __dir__)
+  FileUtils.mkdir_p(tmp_dir)
+
+  schemas.each do |xsd_file|
+    next unless File.exist?(xsd_file)
+
+    name = File.basename(xsd_file, ".xsd")
+    output_file = File.join(tmp_dir, "batch_#{name}.html")
+
+    # Create generator
+    config = Xseed::Documentation::Config.new
+    config.title = "#{name.tr('_', ' ').capitalize} Schema"
+
+    generator = Xseed::Documentation::HtmlGenerator.new(xsd_file, config)
+    generator.generate_file(output_file)
+
+    puts "✓ Generated: #{output_file}"
+  end
+
+  puts "\n✓ Batch generation complete"
+  puts "  All schemas processed successfully"
+  puts
+rescue StandardError => e
+  puts "✗ Error: #{e.message}"
+  puts
+end
+
+# Example 5: CLI Usage Examples
+puts "Example 5: CLI Usage"
+puts "-" * 50
+
+puts <<~CLI_EXAMPLES
+  Basic usage:
+    $ xseed html schema.xsd -o output.html
+
+  With custom title:
+    $ xseed html schema.xsd -o output.html --title "My Schema"
+
+  With verbose output:
+    $ xseed html schema.xsd -o output.html --verbose
+
+  Combine options:
+    $ xseed html schema.xsd -o output.html \\
+        --title "Custom Title" \\
+        --verbose
+
+  Using from Ruby code:
+    require 'xseed'
+    generator = Xseed::Documentation::HtmlGenerator.new('schema.xsd')
+    generator.generate_file('output.html')
+CLI_EXAMPLES
+
+puts "=== Examples Complete ===\n"
+puts "Output files generated in tmp/ directory"
+puts "Open any HTML file in a web browser to view the documentation"

data/examples/parser_usage.rb

@@ -0,0 +1,102 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "xseed/parser/xsd_parser"
+
+# Example 1: Parse a simple XSD file
+puts "=" * 60
+puts "Example 1: Parsing a Simple XSD File"
+puts "=" * 60
+
+xsd_file = File.join(__dir__, "../spec/fixtures/simple/element_only.xsd")
+parser = Xseed::Parser::XsdParser.new(xsd_file)
+
+puts "\nTarget Namespace: #{parser.target_namespace}"
+puts "Element Form Default: #{parser.element_form_default}"
+puts "\nSchema Documentation:"
+puts parser.documentation
+
+puts "\nGlobal Elements:"
+parser.elements.each do |element|
+  name = element["name"]
+  type = element["type"]
+  puts "  - #{name} (#{type})"
+  doc = parser.element_documentation(name)
+  puts "    Documentation: #{doc}" if doc
+end
+
+# Example 2: Parse XSD with complex types
+puts "\n#{'=' * 60}"
+puts "Example 2: Parsing XSD with Complex Types"
+puts "=" * 60
+
+xsd_file = File.join(__dir__, "../spec/fixtures/simple/complex_type.xsd")
+parser = Xseed::Parser::XsdParser.new(xsd_file)
+
+puts "\nTarget Namespace: #{parser.target_namespace}"
+
+puts "\nComplex Types:"
+parser.complex_types.each do |complex_type|
+  name = complex_type["name"]
+  puts "  - #{name}"
+  doc = parser.type_documentation(name)
+  puts "    Documentation: #{doc}" if doc
+end
+
+puts "\nGlobal Elements:"
+parser.elements.each do |element|
+  puts "  - #{element['name']} (type: #{element['type']})"
+end
+
+# Example 3: Parse XSD with simple types
+puts "\n#{'=' * 60}"
+puts "Example 3: Parsing XSD with Simple Types"
+puts "=" * 60
+
+xsd_file = File.join(__dir__, "../spec/fixtures/simple/simple_type.xsd")
+parser = Xseed::Parser::XsdParser.new(xsd_file)
+
+puts "\nTarget Namespace: #{parser.target_namespace}"
+
+puts "\nSimple Types:"
+parser.simple_types.each do |simple_type|
+  name = simple_type["name"]
+  puts "  - #{name}"
+  doc = parser.type_documentation(name)
+  puts "    Documentation: #{doc}" if doc
+end
+
+# Example 4: Explore namespace mappings
+puts "\n#{'=' * 60}"
+puts "Example 4: Namespace Mappings"
+puts "=" * 60
+
+puts "\nNamespace Prefixes:"
+parser.namespaces.each do |prefix, uri|
+  puts "  #{prefix} => #{uri}"
+end
+
+# Example 5: Parse real-world XSD
+puts "\n#{'=' * 60}"
+puts "Example 5: Parsing Real-World XSD (unitsml-v1.0.xsd)"
+puts "=" * 60
+
+xsd_file = File.join(
+  __dir__,
+  "../spec/fixtures/real_world/unitsml-v1.0.xsd",
+)
+parser = Xseed::Parser::XsdParser.new(xsd_file)
+
+puts "\nTarget Namespace: #{parser.target_namespace}"
+puts "Schema Version: #{parser.schema_version || 'N/A'}"
+puts "\nStatistics:"
+puts "  Elements: #{parser.elements.size}"
+puts "  Complex Types: #{parser.complex_types.size}"
+puts "  Simple Types: #{parser.simple_types.size}"
+puts "  Total Types: #{parser.types.size}"
+puts "  Groups: #{parser.groups.size}"
+
+puts "\n#{'=' * 60}"
+puts "All examples completed successfully!"
+puts "=" * 60