xsdvi 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cbb88134a26f0713dea31aa8032d38e06fc8fe5e9b04b321211dd86fac4eadb5
+  data.tar.gz: 21cf471f50d28f47267af0cdd85a3733941e3dd23026389dd21b23fbfc6a7330
+SHA512:
+  metadata.gz: 6c7d8578f22756bd8ae89f9f516da49a02ce926579a05fff307d244a47f8ff33dfc595c60d0fec04ba94412f722bad879da8500043f7af89bea870f10ad2ffff
+  data.tar.gz: 4a74687246d90e2136311111f5046fd768f9347115e2f22cb517adb922c932ca0c508efa0b5fa8ecf0cc8d09e671781b29f85594b31b52836baec98c58e9c76d

data/LICENSE

@@ -0,0 +1,30 @@
+Copyright (c) Ribose Inc. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in
+   the documentation and/or other materials provided with the
+   distribution.
+
+3. Neither the name of Ribose nor the names of its contributors may
+   be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,317 @@
+= XSDVI Ruby
+
+image:https://img.shields.io/gem/v/xsdvi.svg[Gem Version]
+image:https://img.shields.io/badge/license-MIT-blue.svg[License]
+
+== Purpose
+
+XSDVI (XML Schema Definition Visualizer) is a Ruby gem that transforms W3C XML
+Schema (XSD) files into interactive, hierarchical SVG diagrams. It provides a
+visual representation of complex XML Schema structures, making it easier to
+understand schema relationships, element hierarchies, attribute requirements,
+and data type definitions.
+
+The tool parses XSD files and generates SVG diagrams that display:
+
+* Element structures with their types, cardinality, and attributes
+* Compositor relationships (sequence, choice, all)
+* Type hierarchies and inheritance
+* Identity constraints (key, keyref, unique)
+* Namespace information
+* Documentation annotations from the schema
+* Recursive references with loop detection
+
+This is a pure Ruby port of the original Java XsdVi tool, providing the same
+functionality with modern Ruby idioms and gemification for easy integration into
+Ruby projects.
+
+== Features
+
+=== XSD Component Visualization
+
+* Elements and Attributes: Visual boxes showing element names, types, cardinality (min..max occurrences),  required/optional status, and namespace information
+* Compositors: Graphical representation of sequence (ordered), choice (alternatives), and all (unordered) element groups
+* Wildcards: Display of `<any>` and `<anyAttribute>` with namespace constraints and processing modes
+* Identity Constraints: Visualization of key, keyref, unique constraints with their selectors and fields
+* Type Information: Display of simple and complex type definitions, base types, and anonymous types
+
+=== Interactive SVG Output
+
+* Hierarchical Layout: Tree-structure visualization with proper indentation and connections
+* Collapsible/Expandable: JavaScript-enabled expand/collapse functionality for complex schemas (optional)
+* Clickable Elements: Navigate between related schema components
+* Documentation Display: Inline display of `<xs:documentation>` annotations
+* Color-coded Symbols: Different visual styles for elements, attributes, compositors, and constraints
+
+=== Flexible Output Options
+
+* Single Diagram: Generate one SVG showing the entire schema or a specific root element
+* Per-Element Diagrams: Generate separate SVG files for each top-level element
+* Custom Styling: Embed CSS in SVG files or use external stylesheets
+* Output Directory: Organize generated diagrams in custom folder structures
+
+=== Processing Capabilities
+
+* Multiple XSD Files: Process multiple schema files in a single run
+* Loop Detection: Automatically detects and marks recursive element references
+* Namespace Handling: Properly displays and distinguishes multiple namespaces
+* Documentation Extraction: Extracts and formats XSD documentation for display
+* Large Schema Support: Handles complex, real-world schemas with hundreds of elements
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem 'xsdvi'
+----
+
+And then execute:
+
+[source,shell]
+----
+bundle install
+----
+
+Or install it yourself as:
+
+[source,shell]
+----
+gem install xsdvi
+----
+
+== Usage
+
+=== Basic usage
+
+Generate an SVG diagram from an XSD file:
+
+[source,shell]
+----
+xsdvi generate schema.xsd
+----
+
+This creates `schema.svg` in the current directory, showing all top-level
+elements and their hierarchical structure.
+
+=== Generate diagram for specific root element
+
+[source,shell]
+----
+xsdvi generate schema.xsd -r UnitsML
+----
+
+This generates a diagram starting from the `UnitsML` element, showing its
+complete structure and all nested elements.
+
+=== Generate separate SVG for each element
+
+[source,shell]
+----
+xsdvi generate schema.xsd -r all -o -p output/diagrams
+----
+
+This creates individual SVG files for each top-level element in the
+`output/diagrams` directory.
+
+=== Command-line options
+
+`-r, --root-node-name NAME`::
+Specify the schema root element name to visualize. Use "all" to generate
+diagrams for all top-level elements. If omitted, generates a complete schema
+diagram showing all elements.
+
+`-o, --one-node-only`::
+Generate diagram showing only the specified element without its children
+(single-level view). Automatically enabled when using `-r all`. This mode hides
+the expand/collapse control buttons.
+
+`-p, --output-path PATH`::
+Specify output directory for generated SVG files. The tool automatically creates
+the directory if it doesn't exist. If omitted, files are created in the current
+directory.
+
+`--embody-style`::
+Embed CSS styling directly in each SVG file (default: true). This creates
+self-contained SVG files that display correctly without external dependencies.
+
+`--generate-style FILE`::
+Generate an external CSS file with the specified name and reference it from SVG
+files. Useful when generating multiple diagrams that should share styling.
+
+`--use-style URL`::
+Reference an existing external CSS file at the specified URL in generated SVG
+files. The CSS file must be accessible when the SVG is viewed.
+
+=== Examples
+
+.Generate full schema diagram with root element
+[example]
+====
+[source,shell]
+----
+xsdvi generate UnitsML-v1.0.xsd -r UnitsML
+----
+
+Creates `UnitsML.svg` showing the complete structure starting from the UnitsML
+root element, including all nested elements, attributes, and constraints.
+====
+
+.Generate diagram for single element only
+[example]
+====
+[source,shell]
+----
+xsdvi generate UnitsML-v1.0.xsd -r Quantity -o
+----
+
+Creates `Quantity.svg` showing only the Quantity element definition without
+expanding its children, useful for focused documentation.
+====
+
+.Generate separate diagrams for all top-level elements
+[example]
+====
+[source,shell]
+----
+xsdvi generate UnitsML-v1.0.xsd -r all -o -p images/SVG
+----
+
+Creates individual SVG files (`Quantity.svg`, `Unit.svg`, etc.) in the
+`images/SVG` directory, one for each top-level element in the schema.
+====
+
+.Generate diagram using external CSS
+[example]
+====
+[source,shell]
+----
+xsdvi generate schema.xsd --generate-style custom.css -p output
+----
+
+Creates `output/schema.svg` and `output/custom.css`, with the SVG referencing
+the external stylesheet. Useful for customizing diagram appearance.
+====
+
+==  Architecture
+
+=== Core components
+
+TreeElement and TreeBuilder:: Manage the tree structure representing the XSD
+schema hierarchy. TreeElement provides parent-child relationships, traversal
+methods, and unique node identification.
+
+XsdHandler:: Parses XSD files using Nokogiri and builds the symbol tree
+structure. Handles all XSD constructs including elements, attributes,
+compositors, wildcards, and identity constraints. Performs loop detection for
+recursive schemas.
+
+Symbol classes::
+14 specialized symbol types representing different XSD constructs:
++
+* Element, Attribute - schema components
+* Choice, Sequence, All - compositors
+* Any, AnyAttribute - wildcards
+* Key, Keyref, Unique - identity constraints
+* Selector, Field - constraint components
+* Loop - recursive reference indicator
+* Schema - root container
+
+SVG::Generator:: Generates SVG output files from the symbol tree. Manages
+layout, styling, resource loading, and recursive symbol drawing. Produces
+interactive diagrams with JavaScript-enabled expand/collapse functionality.
+
+CLI:: Thor-based command-line interface providing easy access to all generation
+options with built-in help and validation.
+
+=== Data flow
+
+[source]
+----
+XSD File → XsdHandler (Nokogiri parsing)
+              ↓
+         Symbol Tree (TreeBuilder)
+              ↓
+  Symbol Processing (prepare_box, calculate dimensions)
+              ↓
+      SVG Generation (Generator.draw)
+              ↓
+         SVG File Output
+----
+
+
+== Differences from Java version
+
+=== Text wrapping
+
+The Ruby implementation uses a custom text wrapping algorithm that produces
+slightly different line breaks compared to Apache Commons Text
+`WordUtils.wrap()`. The Ruby version optimizes for keeping related content
+together when it fits within the line width, while maintaining valid XML
+structure.
+
+Impact: Documentation text may wrap at different character positions, but
+the visual output and functionality remain identical. The Ruby version ensures
+HTML tags and entities in documentation are not broken across lines, improving
+SVG validity.
+
+Example:
+
+Java may break HTML tags mid-structure:
+
+[source,xml]
+----
+<text>See &lt;a</text>
+<text>href="...">text&lt;/a>.</text>
+----
+
+Ruby keeps tags together for better validity:
+
+[source,xml]
+----
+<text>See &lt;a href="...">text&lt;/a>.</text>
+----
+
+Both outputs are functionally equivalent and render correctly in SVG viewers.
+The Ruby approach actually produces more semantically correct output by
+preserving the integrity of embedded HTML elements.
+
+== Development
+
+After checking out the repo, run `bundle install` to install dependencies.
+
+Run tests:
+
+[source,shell]
+----
+bundle exec rspec
+----
+
+Run rubocop:
+
+[source,shell]
+----
+bundle exec rubocop
+----
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/metanorma/xsdvi-ruby
+
+== Copyright and license
+
+Copyright https://www.ribose.com[Ribose Inc.]
+
+The gem is available as open source under the Ribose 3-Clause BSD License.
+
+== Acknowledgments
+
+This is a Ruby port of the Metanorma version of the XsdVi tool, which is itself
+a fork of the original XsdVi Java tool created by Václav Slavìtínský. See the
+original project at https://sourceforge.net/projects/xsdvi/
+
+The Ruby port maintains compatibility with the Java version's output format
+while providing a pure Ruby implementation suitable for modern Ruby applications
+and workflows.

data/exe/xsdvi

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/xsdvi"
+
+Xsdvi::CLI.start(ARGV)

data/lib/xsdvi/cli.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Xsdvi
+  # Command-line interface for XSDVI
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "generate INPUT [INPUT2...] [OPTIONS]",
+         "Generate SVG diagrams from XSD schema files"
+    method_option :root_node_name,
+                  type: :string,
+                  aliases: "-r",
+                  desc: "Schema root node name (or 'all' for all elements)"
+    method_option :one_node_only,
+                  type: :boolean,
+                  aliases: "-o",
+                  desc: "Show only one element"
+    method_option :output_path,
+                  type: :string,
+                  aliases: "-p",
+                  desc: "Output folder path"
+    method_option :embody_style,
+                  type: :boolean,
+                  default: true,
+                  desc: "Embody CSS style in SVG (default: true)"
+    method_option :generate_style,
+                  type: :string,
+                  desc: "Generate CSS file with specified name"
+    method_option :use_style,
+                  type: :string,
+                  desc: "Use external CSS file at specified URL"
+    def generate(*inputs)
+      if inputs.empty?
+        puts "Error: No input files specified"
+        exit(1)
+      end
+
+      # Validate input files exist
+      inputs.each do |input|
+        unless File.exist?(input)
+          puts "Error: XSD file '#{input}' not found!"
+          exit(1)
+        end
+      end
+
+      # Process options
+      root_node_name = options[:root_node_name]
+      one_node_only = options[:one_node_only]
+      one_node_only = true if root_node_name == "all"
+      output_path = options[:output_path]
+
+      # Determine style mode
+      style_mode = determine_style_mode(options)
+
+      # Process each input file
+      builder = Tree::Builder.new
+      xsd_handler = XsdHandler.new(builder)
+      writer_helper = Utils::Writer.new
+      svg_generator = SVG::Generator.new(writer_helper)
+
+      svg_generator.hide_menu_buttons = one_node_only
+
+      apply_style_settings(svg_generator, style_mode, options)
+
+      inputs.each do |input|
+        process_input_file(
+          input,
+          xsd_handler,
+          svg_generator,
+          builder,
+          writer_helper,
+          root_node_name,
+          one_node_only,
+          output_path,
+        )
+      end
+    end
+
+    default_task :generate
+
+    private
+
+    def determine_style_mode(options)
+      return :generate_style if options[:generate_style]
+      return :use_style if options[:use_style]
+
+      :embody_style
+    end
+
+    def apply_style_settings(svg_generator, style_mode, options)
+      case style_mode
+      when :embody_style
+        puts "The style will be embodied"
+        svg_generator.embody_style = true
+      when :generate_style
+        style_url = options[:generate_style]
+        puts "Generating style #{style_url}..."
+        svg_generator.embody_style = false
+        svg_generator.style_uri = style_url
+        svg_generator.print_extern_style
+        puts "Done."
+      when :use_style
+        style_url = options[:use_style]
+        puts "Using external style #{style_url}"
+        svg_generator.embody_style = false
+        svg_generator.style_uri = style_url
+      end
+    end
+
+    def process_input_file(input, xsd_handler, svg_generator, builder,
+                           writer_helper, root_node_name, one_node_only,
+                           output_path)
+      puts "Parsing #{input}..."
+
+      xsd_handler.root_node_name = root_node_name
+      xsd_handler.one_node_only = one_node_only
+
+      # Parse and process XSD
+      xsd_handler.process_file(input)
+
+      puts "Processing XML Schema model..."
+
+      # Generate output filename
+      output_file = generate_output_filename(
+        input,
+        root_node_name,
+        one_node_only,
+        output_path,
+      )
+
+      puts "Drawing SVG #{output_file}..."
+      writer_helper.new_writer(output_file)
+
+      if builder.root
+        svg_generator.draw(builder.root)
+        puts "Done."
+      else
+        warn "SVG is empty!"
+      end
+    end
+
+    def generate_output_filename(input, root_node_name, one_node_only,
+                                  output_path)
+      basename = File.basename(input, ".*")
+      filename = if root_node_name && one_node_only
+                   "#{root_node_name}.svg"
+                 else
+                   "#{basename}.svg"
+                 end
+
+      if output_path
+        FileUtils.mkdir_p(output_path)
+        File.join(output_path, filename)
+      else
+        filename
+      end
+    end
+  end
+end

data/lib/xsdvi/svg/generator.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "../utils/resource_loader"
+
+module Xsdvi
+  module SVG
+    # Generates SVG files from symbol trees
+    class Generator
+      attr_accessor :writer, :embody_style, :style_uri, :hide_menu_buttons
+
+      def initialize(writer)
+        @writer = writer
+        @embody_style = true
+        @style_uri = nil
+        @hide_menu_buttons = false
+        @resource_loader = Utils::ResourceLoader.new
+      end
+
+      def draw(root_symbol)
+        # Reset class variables before drawing
+        Symbol.reset_class_variables
+
+        svg_begin
+        draw_symbol(root_symbol)
+        svg_end
+      end
+
+      def print_extern_style
+        writer.new_writer(style_uri)
+        print(load_resource("svg/style.css"))
+        writer.close
+      end
+
+      def print(string)
+        writer.append("#{string}\n")
+      end
+
+      private
+
+      def svg_begin
+        print(load_resource("svg/xml_declaration.xml"))
+        print_style_ref unless embody_style
+        print(load_resource("svg/doctype.txt"))
+        print(load_resource("svg/svg_start.txt"))
+        print(load_resource("svg/title.txt"))
+
+        script = load_resource("svg/script.js")
+        script = script.gsub("%HEIGHT_SUM%", (Symbol::MAX_HEIGHT + Symbol::Y_INDENT).to_s)
+        script = script.gsub("%HEIGHT_HALF%", (Symbol::MAX_HEIGHT / 2).to_s)
+        print(script)
+
+        print_defs(embody_style, true)
+        print(load_resource("svg/menu_buttons.svg")) unless hide_menu_buttons
+      end
+
+      def svg_end
+        print(load_resource("svg/svg_end.txt"))
+        writer.close
+      end
+
+      def print_style_ref
+        style_template = load_resource("svg/style.xml")
+        print(style_template.gsub("%STYLE_URI%", style_uri))
+      end
+
+      def print_embodied_style
+        style_template = load_resource("svg/style.html")
+        style = load_resource("svg/style.css")
+        print(style_template.gsub("%STYLE%", style))
+      end
+
+      def print_defs(style, symbols)
+        print("<defs>")
+        print_embodied_style if style
+        print(load_resource("svg/defined_symbols.svg")) if symbols
+        print("</defs>")
+      end
+
+      def draw_symbol(symbol)
+        symbol.svg = self
+        symbol.prepare_box
+        symbol.draw
+        symbol.children.each do |child|
+          draw_symbol(child)
+        end
+      end
+
+      def load_resource(path)
+        @resource_loader.read_resource_file(path)
+      end
+    end
+  end
+end