railroad_diagrams 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 992d560c768d0ad4991ea5c774a60083b4a2f8c407b88c91abfe6c92ab73fea5
+  data.tar.gz: 108ce587863fb33a368d2e5278002ff6ee6bd6885576f6f7b9a7cd4e7c8eec3a
+SHA512:
+  metadata.gz: 6795906adf826df7a16207cea05cc54a3724cd66ab5dd0a9120643d5b2bf24f08ab7ac2b66d517478cd826c1baccc6faadfe1365b40dc6636bcd102e2ab393cf
+  data.tar.gz: e041c348cea71435c688dedb451eb368b00e71dac41cce239492766e7dd2991c61576c0087774064a948d9248538f74b233dfde439117b6587ed46df310a4ba3

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 - 2025-02-01
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/MIT

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,30 @@
+# RailroadDiagrams
+
+A tiny Ruby+SVG library for drawing railroad syntax diagrams.
+
+# Installation
+
+Add this line to your application's Gemfile:
+```ruby
+gem 'railroad_diagrams'
+```
+
+Add then execute:
+```bash
+bundle install
+```
+
+Or install it yourself as:
+```bash
+gem install railroad_diagrams
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ydah/railroad_diagrams.

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+task default: %i[]

data/exe/railroad_diagrams

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH << File.join(__dir__, '../lib')
+require 'railroad_diagrams'
+
+RailroadDiagrams::Command.new.run(ARGV.dup)

data/lib/railroad_diagrams/alternating_sequence.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module RailroadDiagrams
+  class AlternatingSequence < DiagramMultiContainer
+    def self.new(*items)
+      raise "AlternatingSequence takes exactly two arguments, but got #{items.size} arguments." unless items.size == 2
+
+      super
+    end
+
+    def initialize(*items)
+      super('g', items)
+      @needs_space = false
+
+      arc = AR
+      vert = VS
+      first, second = @items
+
+      arc_x = 1 / Math.sqrt(2) * arc * 2
+      arc_y = (1 - (1 / Math.sqrt(2))) * arc * 2
+      cross_y = [arc, vert].max
+      cross_x = (cross_y - arc_y) + arc_x
+
+      first_out = [
+        arc + arc, (cross_y / 2) + arc + arc, (cross_y / 2) + vert + first.down
+      ].max
+      @up = first_out + first.height + first.up
+
+      second_in = [
+        arc + arc, (cross_y / 2) + arc + arc, (cross_y / 2) + vert + second.up
+      ].max
+      @down = second_in + second.height + second.down
+
+      @height = 0
+
+      first_width = (first.needs_space ? 20 : 0) + first.width
+      second_width = (second.needs_space ? 20 : 0) + second.width
+      @width = (2 * arc) + [first_width, cross_x, second_width].max + (2 * arc)
+    end
+
+    def to_s
+      items = @items.map(&:to_s).join(', ')
+      "AlternatingSequence(#{items})"
+    end
+
+    def format(x, y, width)
+      arc = AR
+      gaps = determine_gaps(width, @width)
+      Path.new(x, y).right(gaps[0]).add(self)
+      x += gaps[0]
+      Path.new(x + @width, y + @height).right(gaps[1]).add(self)
+      # bounding box
+      # Path(x+gaps[0], y).up(@up).right(@width).down(@up+@down).left(@width).up(@up).add(self)
+      first, second = @items
+
+      # top
+      first_in = @up - first.up
+      first_out = @up - first.up - first.height
+      Path.new(x, y).arc('se').up(first_in - (2 * arc)).arc('wn').add(self)
+      first.format(x + (2 * arc), y - first_in, @width - (4 * arc)).add(self)
+      Path.new(x + @width - (2 * arc), y - first_out)
+          .arc('ne').down(first_out - (2 * arc)).arc('ws').add(self)
+
+      # bottom
+      second_in = @down - second.down - second.height
+      second_out = @down - second.down
+      Path.new(x, y)
+          .arc('ne')
+          .down(second_in - (2 * arc))
+          .arc('ws')
+          .add(self)
+      second.format(x + (2 * arc), y + second_in, @width - (4 * arc)).add(self)
+      Path.new(x + @width - (2 * arc), y + second_out)
+          .arc('se').up(second_out - (2 * arc)).arc('wn').add(self)
+
+      # crossover
+      arc_x = 1 / Math.sqrt(2) * arc * 2
+      arc_y = (1 - (1 / Math.sqrt(2))) * arc * 2
+      cross_y = [arc, VS].max
+      cross_x = (cross_y - arc_y) + arc_x
+      cross_bar = (@width - (4 * arc) - cross_x) / 2
+
+      Path.new(x + arc, y - (cross_y / 2) - arc)
+          .arc('ws')
+          .right(cross_bar)
+          .arc_8('n', 'cw')
+          .l(cross_x - arc_x, cross_y - arc_y)
+          .arc_8('sw', 'ccw')
+          .right(cross_bar)
+          .arc('ne')
+          .add(self)
+
+      Path.new(x + arc, y + (cross_y / 2) + arc)
+          .arc('wn')
+          .right(cross_bar)
+          .arc_8('s', 'ccw')
+          .l(cross_x - arc_x, -(cross_y - arc_y))
+          .arc_8('nw', 'cw')
+          .right(cross_bar)
+          .arc('se')
+          .add(self)
+
+      self
+    end
+
+    def text_diagram
+      cross_diag, corner_bot_left, corner_bot_right, corner_top_left, corner_top_right,
+      line, line_vertical, tee_left, tee_right = TextDiagram.get_parts(
+        %w[
+          cross_diag roundcorner_bot_left roundcorner_bot_right
+          roundcorner_top_left roundcorner_top_right line
+          line_vertical tee_left tee_right
+        ]
+      )
+
+      first_td = @items[0].text_diagram
+      second_td = @items[1].text_diagram
+      max_width = TextDiagram._max_width(first_td, second_td)
+      left_width, right_width = TextDiagram._gaps(max_width, 0)
+
+      left_lines = []
+      right_lines = []
+      separator = []
+
+      left_size, right_size = TextDiagram._gaps(first_td.width, 0)
+      diagram_td = first_td.expand(left_width - left_size, right_width - right_size, 0, 0)
+
+      left_lines += [' ' * 2] * diagram_td.entry
+      left_lines << (corner_top_left + line)
+      left_lines += ["#{line_vertical} "] * (diagram_td.height - diagram_td.entry - 1)
+      left_lines << (corner_bot_left + line)
+
+      right_lines += [' ' * 2] * diagram_td.entry
+      right_lines << (line + corner_top_right)
+      right_lines += [" #{line_vertical}"] * (diagram_td.height - diagram_td.entry - 1)
+      right_lines << (line + corner_bot_right)
+
+      separator << ("#{line * (left_width - 1)}#{corner_top_right} #{corner_top_left}#{line * (right_width - 2)}")
+      separator << ("#{' ' * (left_width - 1)} #{cross_diag} #{' ' * (right_width - 2)}")
+      separator << ("#{line * (left_width - 1)}#{corner_bot_right} #{corner_bot_left}#{line * (right_width - 2)}")
+
+      left_lines << (' ' * 2)
+      right_lines << (' ' * 2)
+
+      left_size, right_size = TextDiagram._gaps(second_td.width, 0)
+      second_td = second_td.expand(left_width - left_size, right_width - right_size, 0, 0)
+      diagram_td = diagram_td.append_below(second_td, separator, move_entry: true, move_exit: true)
+
+      left_lines << (corner_top_left + line)
+      left_lines += ["#{line_vertical} "] * second_td.entry
+      left_lines << (corner_bot_left + line)
+
+      right_lines << (line + corner_top_right)
+      right_lines += [" #{line_vertical}"] * second_td.entry
+      right_lines << (line + corner_bot_right)
+
+      mid_point = first_td.height + (separator.size / 2)
+      diagram_td = diagram_td.alter(entry: mid_point, exit: mid_point)
+
+      left_td = TextDiagram.new(mid_point, mid_point, left_lines)
+      right_td = TextDiagram.new(mid_point, mid_point, right_lines)
+
+      diagram_td = left_td.append_right(diagram_td, '').append_right(right_td, '')
+      TextDiagram.new(1, 1, [corner_top_left, tee_left, corner_bot_left])
+                 .append_right(diagram_td, '')
+                 .append_right(TextDiagram.new(1, 1, [corner_top_right, tee_right, corner_bot_right]), '')
+    end
+  end
+end

data/lib/railroad_diagrams/choice.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module RailroadDiagrams
+  class Choice < DiagramMultiContainer
+    def initialize(default, *items)
+      super('g', items)
+      raise ArgumentError, 'default index out of range' if default >= items.size
+
+      @default = default
+      @width = (AR * 4) + @items.map(&:width).max
+
+      # The calcs are non-trivial and need to be done both here
+      # and in .format(), so no reason to do it twice.
+      @separators = Array.new(items.size - 1, VS)
+
+      # If the entry or exit lines would be too close together
+      # to accommodate the arcs,
+      # bump up the vertical separation to compensate.
+      @up = 0
+      (default - 1).downto(0) do |i|
+        arcs =
+          if i == default - 1
+            AR * 2
+          else
+            AR
+          end
+
+        item = @items[i]
+        lower_item = @items[i + 1]
+
+        entry_delta = lower_item.up + VS + item.down + item.height
+        exit_delta = lower_item.height + lower_item.up + VS + item.down
+
+        separator = VS
+        separator += [arcs - entry_delta, arcs - exit_delta].max if entry_delta < arcs || exit_delta < arcs
+        @separators[i] = separator
+
+        @up += lower_item.up + separator + item.down + item.height
+      end
+      @up += @items[0].up
+
+      @height = @items[default].height
+      @down = 0
+
+      (default + 1...@items.size).each do |i|
+        arcs =
+          if i == default + 1
+            AR * 2
+          else
+            AR
+          end
+
+        item = @items[i]
+        upper_item = @items[i - 1]
+
+        entry_delta = upper_item.height + upper_item.down + VS + item.up
+        exit_delta = upper_item.down + VS + item.up + item.height
+
+        separator = VS
+        separator += [arcs - entry_delta, arcs - exit_delta].max if entry_delta < arcs || exit_delta < arcs
+        @separators[i - 1] = separator
+
+        @down += upper_item.down + separator + item.up + item.height
+      end
+      @down += @items[-1].down
+      @needs_space = false
+    end
+
+    def to_s
+      items_str = @items.map(&:inspect).join(', ')
+      "Choice(#{@default}, #{items_str})"
+    end
+
+    def format(x, y, width)
+      left_gap, right_gap = determine_gaps(width, @width)
+
+      # Hook up the two sides if self is narrower than its stated width.
+      Path.new(x, y).h(left_gap).add(self)
+      Path.new(x + left_gap + @width, y + @height).h(right_gap).add(self)
+      x += left_gap
+
+      inner_width = @width - (AR * 4)
+      default = @items[@default]
+
+      # Do the elements that curve above
+      distance_from_y = 0
+      (@default - 1).downto(0) do |i|
+        item = @items[i]
+        lower_item = @items[i + 1]
+        distance_from_y += lower_item.up + @separators[i] + item.down + item.height
+        Path.new(x, y)
+            .arc('se')
+            .up(distance_from_y - (AR * 2))
+            .arc('wn')
+            .add(self)
+        item.format(x + (AR * 2), y - distance_from_y, inner_width).add(self)
+        Path.new(x + (AR * 2) + inner_width, y - distance_from_y + item.height)
+            .arc('ne')
+            .down(distance_from_y - item.height + default.height - (AR * 2))
+            .arc('ws')
+            .add(self)
+      end
+
+      # Do the straight-line path.
+      Path.new(x, y).right(AR * 2).add(self)
+      @items[@default].format(x + (AR * 2), y, inner_width).add(self)
+      Path.new(x + (AR * 2) + inner_width, y + @height).right(AR * 2).add(self)
+
+      # Do the elements that curve below
+      distance_from_y = 0
+      (@default + 1...@items.size).each do |i|
+        item = @items[i]
+        upper_item = @items[i - 1]
+        distance_from_y += upper_item.height + upper_item.down + @separators[i - 1] + item.up
+        Path.new(x, y)
+            .arc('ne')
+            .down(distance_from_y - (AR * 2))
+            .arc('ws')
+            .add(self)
+        item.format(x + (AR * 2), y + distance_from_y, inner_width).add(self)
+        Path.new(x + (AR * 2) + inner_width, y + distance_from_y + item.height)
+            .arc('se')
+            .up(distance_from_y - (AR * 2) + item.height - default.height)
+            .arc('wn')
+            .add(self)
+      end
+
+      self
+    end
+
+    def text_diagram
+      cross, line, line_vertical, roundcorner_bot_left, roundcorner_bot_right, roundcorner_top_left, roundcorner_top_right =
+        TextDiagram.get_parts(
+          %w[
+            cross line line_vertical roundcorner_bot_left roundcorner_bot_right roundcorner_top_left roundcorner_top_right
+          ]
+        )
+
+      # Format all the child items, so we can know the maximum width.
+      item_tds = @items.map { |item| item.text_diagram.expand(1, 1, 0, 0) }
+      max_item_width = item_tds.map(&:width).max
+      diagram_td = TextDiagram.new(0, 0, [])
+      # Format the choice collection.
+      item_tds.each_with_index do |item_td, i|
+        left_pad, right_pad = TextDiagram.gaps(max_item_width, item_td.width)
+        item_td = item_td.expand(left_pad, right_pad, 0, 0)
+        has_separator = true
+        left_lines = [line_vertical] * item_td.height
+        right_lines = [line_vertical] * item_td.height
+        move_entry = false
+        move_exit = false
+        if i <= @default
+          # First item and above the line: also remove ascenders above the item's entry and exit, suppress the separator above it.
+          has_separator = false
+          [0..item_td.entry].each { |j| left_lines[j] = ' ' }
+          [0..item_td.exit].each { |j| right_lines[j] = ' ' }
+        end
+        if i >= @default
+          # Item below the line: round off the entry/exit lines downwards.
+          left_lines[item_td.entry] = roundcorner_bot_left
+          right_lines[item_td.entry] = roundcorner_bot_right
+          if i == 0
+            # First item and below the line: also suppress the separator above it.
+            has_separator = false
+          end
+          if i == @items.size - 1
+            # Last item and below the line: also remove descenders below the item's entry and exit
+            [item_td.entry + 1..item_td.height].each { |j| left_lines[j] = ' ' }
+            [item_td.exit + 1..item_td.height].each { |j| right_lines[j] = ' ' }
+          end
+        end
+        if i == @default
+          # Item on the line: entry/exit are horizontal, and sets the outer entry/exit.
+          left_lines[item_td.entry] = cross
+          right_lines[item_td.entry] = cross
+          move_entry = true
+          move_exit = true
+          if i == 0 && i == @items.size - 1
+            # Only item and on the line: set entry/exit for straight through.
+            left_lines[item_td.entry] = line
+            right_lines[item_td.entry] = line
+          elsif i == 0
+            # First item and on the line: set entry/exit for no ascenders.
+            left_lines[item_td.entry] = roundcorner_top_left
+            left_lines[item_td.exit] = roundcorner_bot_left
+          elsif i == @items.size - 1
+            # Last item and on the line: set entry/exit for no descenders.
+            left_lines[item_td.entry] = roundcorner_bot_left
+            right_lines[item_td.entry] = roundcorner_bot_right
+          end
+        end
+        left_join_td = TextDiagram.new(item_td.entry, item_td.entry, left_lines)
+        right_join_td = TextDiagram.new(item_td.exit, item_td.exit, right_lines)
+        item_td = left_join_td.append_right(item_td, '').append_right(right_join_td, '')
+        separator = if has_separator
+                      [
+                        line_vertical +
+                          (' ' * (TextDiagram.max_width(diagram_td, item_td) - 2)) +
+                          line_vertical
+                      ]
+                    else
+                      []
+                    end
+        diagram_td = diagram_td.append_below(item_td, separator, move_entry:, move_exit:)
+      end
+      diagram_td
+    end
+  end
+end

data/lib/railroad_diagrams/command.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module RailroadDiagrams
+  class Command
+    def initialize
+      @format = 'svg'
+    end
+
+    def run(argv)
+      OptionParser.new do |opts|
+        opts.banner = <<~BANNER
+          This is a test runner for railroad_diagrams:
+          Usage: railroad_diagrams [options] [files]
+        BANNER
+
+        opts.on('-f', '--format FORMAT', 'Output format (svg, ascii, unicode, standalone)') do |format|
+          @format = format
+        end
+        opts.on('-h', '--help', 'Print this help') do
+          puts opts
+          exit
+        end
+        opts.on('-v', '--version', 'Print version') do
+          puts "railroad_diagrams #{RailroadDiagrams::VERSION}"
+          exit 0
+        end
+        opts.parse!(argv)
+      end
+
+      @test_list = argv
+
+      puts <<~HTML
+        <!doctype html>
+        <html>
+        <head>
+          <title>Test</title>
+      HTML
+
+      case @format
+      when 'ascii'
+        TextDiagram.set_formatting(TextDiagram::PARTS_ASCII)
+      when 'unicode'
+        TextDiagram.set_formatting(TextDiagram::PARTS_UNICODE)
+      when 'svg', 'standalone'
+        TextDiagram.set_formatting(TextDiagram::PARTS_UNICODE)
+        puts <<~CSS
+          <style>
+            #{Style.default_style}
+            .blue text { fill: blue; }
+          </style>
+        CSS
+      end
+
+      puts '</head><body>'
+
+      File.open('test.rb', 'r:utf-8') do |fh|
+        eval(fh.read, binding, 'test.rb')
+      end
+
+      puts '</body></html>'
+    end
+
+    def add(name, diagram)
+      return unless @test_list.empty? || @test_list.include?(name)
+
+      puts "\n<h1>#{RailroadDiagrams.escape_html(name)}</h1>"
+
+      case @format
+      when 'svg'
+        diagram.write_svg(STDOUT.method(:write))
+      when 'standalone'
+        diagram.write_standalone(STDOUT.method(:write))
+      when 'ascii', 'unicode'
+        puts "\n<pre>"
+        diagram.write_text(STDOUT.method(:write))
+        puts "\n</pre>"
+      end
+
+      puts "\n"
+    end
+  end
+end

data/lib/railroad_diagrams/comment.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RailroadDiagrams
+  class Comment < DiagramItem
+    def initialize(text, href = nil, title = nil, cls: '')
+      super('g', attrs: { 'class' => "non-terminal #{cls}" })
+      @text = text
+      @href = href
+      @title = title
+      @cls = cls
+      @width = (text.length * COMMENT_CHAR_WIDTH) + 10
+      @up = 8
+      @down = 8
+      @needs_space = true
+    end
+
+    def to_s
+      "Comment(#{@text}, href=#{@href}, title=#{@title}, cls=#{@cls})"
+    end
+
+    def format(x, y, _width)
+      left_gap, right_gap = determine_gaps(width, @width)
+
+      # Hook up the two sides if self is narrower than its stated width.
+      Path.new(x, y).h(left_gap).add(self)
+      Path.new(x + left_gap + @width, y).h(right_gap).add(self)
+
+      text = DiagramItem.new(
+        'text',
+        attrs: { 'x' => x + left_gap + (@width / 2), 'y' => y + 4, 'class' => 'comment' },
+        text: @text
+      )
+      if @href
+        a = DiagramItem.new('a', attrs: { 'xlink:href' => @href }, text:).add(self)
+        text.add(a)
+      else
+        text.add(self)
+      end
+      DiagramItem.new('title', attrs: {}, text: @title).add(self) if @title
+      self
+    end
+
+    def text_diagram
+      # NOTE: href, title, and cls are ignored for text diagrams.
+      TextDiagram.new(0, 0, @text)
+    end
+  end
+end