bitgram 0.1.0

data/lib/bitgram/renderers/ascii.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "../text/fitter"
+require_relative "ascii/box_chars"
+
+module Bitgram
+  module Renderers
+    # @api private
+    class Ascii
+      attr_reader :issues
+
+      def initialize(result, **options)
+        @result = result
+        @document = result.document
+        @config = @document.ascii.merge(options.transform_keys(&:to_s))
+        @width = @document.layout.fetch("row_bits")
+        @unicode = @config["style"].to_s == "unicode"
+        @measurer = Text::AsciiMeasurer.new(ambiguous: @config["ambiguous_width"])
+        @offset_width = @result.rows.map { |row| @result.offset_label(row).size }.max || 0
+        @issues = []
+      end
+
+      def render
+        @fitter = Text::Fitter.new(measurer: @measurer, footnote_marker: @config["footnote_marker"])
+        lines = []
+        lines << @document.title if @document.title && @config["title"].to_s == "top"
+        lines.concat(header.map { |line| gutter + line }) if @document.layout["bit_numbers"]
+        lines.concat(table_lines)
+        lines.concat(@fitter.footnotes).concat(@document.notes)
+        lines << @document.title if @document.title && @config["title"].to_s == "bottom"
+        @issues = @fitter.issues
+        indented = lines.flat_map { |line| line.split("\n") }
+                        .map { |line| ((" " * @config["indent"]) + line).rstrip }
+        "#{indented.join("\n")}\n"
+      end
+
+      private
+
+      def table_lines
+        lines = []
+        @result.rows.each_with_index do |row, index|
+          lines << (gutter + border(@result.rows[index - 1], row, top: index.zero?))
+          row_lines(row).each_with_index do |line, inner_index|
+            offset = inner_index.zero? ? @result.offset_label(row) : ""
+            lines << (gutter(offset) + line)
+          end
+        end
+        lines << (gutter + border(@result.rows.last, nil))
+        lines
+      end
+
+      def gutter(offset = "")
+        @offset_width.positive? ? "#{offset.rjust(@offset_width)} " : ""
+      end
+
+      def border(above, below, top: false)
+        BoxChars.border(@width, above: top ? nil : above, below: below, unicode: @unicode)
+      end
+
+      def header
+        tens = Array.new((2 * @width) + 1, " ")
+        ones = Array.new((2 * @width) + 1, " ")
+        @width.times do |column|
+          number = @document.layout["bit_order"] == "lsb0" ? @width - 1 - column : column
+          tens[(2 * column) + 1, (number / 10).to_s.size] = (number / 10).to_s.chars if (number % 10).zero?
+          ones[(2 * column) + 1] = (number % 10).to_s
+        end
+        [tens.join.rstrip, ones.join.rstrip]
+      end
+
+      def row_lines(row)
+        fits = row.cells.map { |cell| fit_cell(cell) }
+        height = [fits.map { |fit| fit.lines.size }.max, minimum_height(row)].max
+        Array.new(height) do |index|
+          edge = edge_for(row, index)
+          content = row.cells.zip(fits).map do |cell, fit|
+            cell_line(cell, fit, index, height) + edge
+          end.join
+          remaining = @width - row.cells.sum(&:bits)
+          content += (" " * ((2 * remaining) - 1)) + edge if remaining.positive?
+          edge + content
+        end
+      end
+
+      def cell_line(cell, fit, index, height)
+        line_index = index - ((height - fit.lines.size) / 2)
+        label = line_index >= 0 ? fit.lines[line_index].to_s : ""
+        center(label, (2 * cell.bits) - 1)
+      end
+
+      def minimum_height(row)
+        return (2 * row.span) - 1 if row.kind == :block
+        return @unicode ? 1 : 3 if row.kind == :variable
+
+        1
+      end
+
+      def edge_for(row, index)
+        if row.kind == :variable
+          return "┊" if @unicode
+
+          return index == 1 ? "\\" : "/" if @config["variable_edge"].to_s == "slash"
+
+          return @config["variable_edge"].to_s == "colon" ? ":" : "."
+        end
+        return @unicode ? "│" : "+" if row.kind == :block && index.odd?
+
+        @unicode ? "│" : "|"
+      end
+
+      def fit_cell(cell)
+        width = (2 * cell.bits) - 1
+        label = @result.cell_label(cell)
+        if cell.part != :whole && @document.layout["split_label"] == "range" && @measurer.width(label) > width
+          label = cell.field.name
+        end
+        label += " (=#{cell.field.value})" unless cell.field.value.nil?
+        @fitter.fit(text: label, short: cell.field.short, inner_width: width,
+                    max_lines: @config["max_label_lines"], order: @config["fit_order"],
+                    description: cell.field.description || cell.field.name,
+                    path: "$.fields[#{@document.fields.index(cell.field)}].name")
+      end
+
+      def center(text, width)
+        padding = [width - @measurer.width(text), 0].max
+        (" " * (padding / 2)) + text + (" " * (padding - (padding / 2)))
+      end
+    end
+  end
+end

data/lib/bitgram/renderers/svg/cells.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Bitgram
+  module Renderers
+    class Svg
+      # @api private
+      module Cells
+        private
+
+        def draw_cell(cell, row, y, height, fits)
+          field = cell.field
+          x = @geometry.x + (cell.col * @options["bit_width"])
+          width = cell.bits * @options["bit_width"]
+          attributes = { class: (["bg-field"] + field.classes).join(" "), "data-field-id": field.id,
+                         "data-bits": field.variable? ? "variable" : field.bits, "data-part": cell.part }
+          @output << "<g #{XmlBuilder.attributes(attributes)}>"
+          label = "#{field.name} (#{field.variable? ? 'variable' : field.bits} bits)"
+          label += ": #{field.description}" if field.description
+          emit("title", {}, label)
+          draw_rectangle(field, row, x: x, y: y, width: width, height: height)
+          draw_label(fits, x + (width / 2.0), y + (height / 2.0))
+          @output << "</g>"
+        end
+
+        def draw_rectangle(field, row, x:, y:, width:, height:)
+          rectangle = { class: "bg-cell", x: x, y: y, width: width, height: height,
+                        fill: @theme.field_fill(field, @field_indexes.fetch(field.id)),
+                        stroke: @theme["stroke"], "stroke-width": 1 }
+          rectangle["stroke-dasharray"] = "4 3" if field.optional
+          if row.kind == :variable
+            rectangle[:stroke] = "none"
+            rectangle[:class] += " bg-variable-cell"
+          end
+          emit("rect", rectangle)
+          if field.reserved
+            emit("rect",
+                 { class: "bg-hatch-overlay", x: x, y: y, width: width, height: height, fill: "url(##{@prefix}-hatch)",
+                   "pointer-events": "none" })
+          end
+          draw_variable_edges(field, x, y, width, height) if row.kind == :variable
+        end
+
+        def draw_variable_edges(field, x, y, width, height)
+          emit("line", { class: "bg-edge", x1: x, y1: y, x2: x + width, y2: y, stroke: @theme["stroke"] })
+          emit("line",
+               { class: "bg-edge", x1: x, y1: y + height, x2: x + width, y2: y + height, stroke: @theme["stroke"] })
+          [x, x + width].each do |edge|
+            steps = 6
+            path = "M #{fmt(edge)} #{fmt(y)}"
+            (1..steps).each do |index|
+              delta = if index == steps
+                        0
+                      else
+                        (index.odd? ? 2 : -2)
+                      end
+              path += " L #{fmt(edge + delta)} #{fmt(y + (height * index / steps))}"
+            end
+            emit("path",
+                 { class: "bg-edge", d: path, fill: "none", stroke: @theme["stroke"],
+                   "stroke-dasharray": field.optional ? "4 3" : nil })
+          end
+        end
+
+        def draw_label(fits, x, center)
+          sizes = fits.each_with_index.map do |fit, index|
+            fit && ((fit.font_size || @options["font_size"]) * (index.zero? ? 1 : 0.85))
+          end
+          total = fits.each_with_index.sum { |fit, index| fit ? fit.lines.length * sizes[index] * 1.2 : 0 }
+          top = center - (total / 2.0)
+          fits.each_with_index do |fit, index|
+            next unless fit
+
+            size = sizes[index]
+            baseline = top + (size * 0.95)
+            klass = index.zero? ? "bg-label" : "bg-value"
+            draw_label_lines(fit.lines, x, baseline, size, klass)
+            top += fit.lines.length * size * 1.2
+          end
+        end
+
+        def draw_label_lines(lines, x, baseline, size, klass)
+          if lines.length == 1
+            emit("text", text_attributes(klass, size).merge(x: x, y: baseline), lines.first)
+          else
+            @output << "<text #{XmlBuilder.attributes(text_attributes(klass, size))}>"
+            lines.each_with_index { |line, index| emit("tspan", { x: x, y: baseline + (index * size * 1.2) }, line) }
+            @output << "</text>"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bitgram/renderers/svg/decorations.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Bitgram
+  module Renderers
+    class Svg
+      # @api private
+      module Decorations
+        private
+
+        def draw_definitions
+          @output << "<defs>"
+          attributes = { id: "#{@prefix}-hatch", width: 6, height: 6,
+                         patternUnits: "userSpaceOnUse", patternTransform: "rotate(45)" }
+          @output << "<pattern #{XmlBuilder.attributes(attributes)}>"
+          emit("line", { x1: 0, y1: 0, x2: 0, y2: 6, class: "bg-hatch", stroke: @theme["hatch"], "stroke-width": 1 })
+          @output << "</pattern>"
+          @output << "</defs>"
+        end
+
+        def draw_styles
+          css = theme_css(@theme)
+          if @options["theme"] == "auto"
+            css += "\n@media (prefers-color-scheme: dark) {\n#{theme_css(Theme.new('dark'))}\n}"
+          end
+          emit("style", {}, css)
+        end
+
+        def theme_css(theme)
+          selector = %([id="#{@prefix}-diagram"])
+          rules = ["#{selector} { background: #{theme['background']}; }",
+                   "#{selector} text { font-family: #{@options['font_family']}; fill: #{theme['text']}; }",
+                   "#{selector} .bg-cell, #{selector} .bg-edge, #{selector} .bg-tick " \
+                   "{ stroke: #{theme['stroke']}; stroke-width: 1; }",
+                   "#{selector} .bg-hatch { stroke: #{theme['hatch']}; }",
+                   "#{selector} .bg-variable-cell { stroke: none; }",
+                   "#{selector} .bg-bit-numbers text, #{selector} .bg-offset { fill: #{theme['header_text']}; }"]
+          @document.fields.each_with_index do |field, index|
+            rules << %(#{selector} [data-field-id="#{field.id}"] .bg-cell { fill: #{theme.field_fill(field, index)}; })
+          end
+          rules.join("\n")
+        end
+
+        def draw_header
+          margin = @options["margin"]
+          if @geometry.title_height.positive?
+            emit("text", text_attributes("bg-title", @options["font_size"] * 1.2)
+                         .merge(x: width / 2.0, y: margin + (@options["font_size"] * 1.4)), @document.title)
+          end
+          return unless @document.layout["bit_numbers"]
+
+          draw_numbers(margin + @geometry.title_height)
+        end
+
+        def draw_numbers(top)
+          @output << '<g class="bg-bit-numbers">'
+          @document.layout["row_bits"].times do |col|
+            number = @document.layout["bit_order"] == "lsb0" ? @document.layout["row_bits"] - 1 - col : col
+            x = @geometry.x + ((col + 0.5) * @options["bit_width"])
+            attributes = text_attributes("bg-bit-number", 11).merge(x: x, fill: @theme["header_text"])
+            if @options["bit_number_style"] == "rfc"
+              emit("text", attributes.merge(y: top + 12), number / 10) if (number % 10).zero?
+              emit("text", attributes.merge(y: top + 28), number % 10)
+            else
+              emit("text", attributes.merge(y: top + 16), number)
+            end
+          end
+          @output << "</g>"
+        end
+
+        def draw_ticks(row, y, height)
+          width = @document.layout["row_bits"]
+          (1...width).each do |col|
+            x = @geometry.x + (col * @options["bit_width"])
+            emit("line", { class: "bg-tick", x1: x, y1: y, x2: x, y2: y + 4, stroke: @theme["stroke"] })
+          end
+          return unless row.kind == :block
+
+          (1...row.span).each do |index|
+            boundary = y + (height * index / row.span)
+            [@geometry.x, @geometry.x + (width * @options["bit_width"]) - 6].each do |x|
+              emit("line", { class: "bg-tick", x1: x, y1: boundary, x2: x + 6, y2: boundary, stroke: @theme["stroke"] })
+            end
+          end
+        end
+
+        def draw_offset(row, y, height)
+          label = @result.offset_label(row)
+          return if label.empty?
+
+          baseline = y + ([height, @options["row_height"]].min / 2) + (@options["font_size"] * 0.35)
+          attributes = text_attributes("bg-offset").merge(x: @geometry.x - 8, y: baseline,
+                                                          "text-anchor": "end", fill: @theme["header_text"])
+          emit("text", attributes, label)
+        end
+      end
+    end
+  end
+end

data/lib/bitgram/renderers/svg/geometry.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Bitgram
+  module Renderers
+    class Svg
+      # @api private
+      class Geometry
+        attr_reader :width, :height, :gutter, :title_height, :header_height, :row_heights, :x, :y
+
+        def initialize(result, options, fits, footnotes, measurer)
+          @result = result
+          @options = options
+          measure_header(measurer)
+          @row_heights = result.rows.each_with_index.map { |row, index| row_height(row, fits[index]) }
+          @x = options["margin"] + gutter
+          @y = options["margin"] + title_height + header_height
+          @width = (options["margin"] * 2) + gutter + (result.document.layout["row_bits"] * options["bit_width"])
+          @height = (options["margin"] * 2) + title_height + header_height + row_heights.sum + footer_height(footnotes)
+        end
+
+        private
+
+        def footer_height(footnotes)
+          footnotes.empty? ? 0 : 8 + (footnotes.length * @options["font_size"] * 1.4)
+        end
+
+        def measure_header(measurer)
+          result = @result
+          options = @options
+          @title_height = options["show_title"] && result.document.title ? (options["font_size"] * 2) + 2 : 0
+          @header_height = if result.document.layout["bit_numbers"]
+                             options["bit_number_style"] == "rfc" ? 36 : 24
+                           else
+                             0
+                           end
+          @gutter = if result.document.layout["offsets"] == "none"
+                      0
+                    else
+                      result.rows.map { |row| measurer.width(result.offset_label(row)) }.max.to_f + 12
+                    end
+        end
+
+        def row_height(row, fits)
+          content_height = fits.map do |label, value|
+            [label, value].compact.sum { |fit| fit.lines.length * (fit.font_size || @options["font_size"]) * 1.2 } + 8
+          end.max || 0
+          base = @options["row_height"] * (row.kind == :variable ? 1.5 : row.span)
+          [base, content_height].max
+        end
+      end
+    end
+  end
+end

data/lib/bitgram/renderers/svg/theme.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "../../loader"
+
+module Bitgram
+  module Renderers
+    class Svg
+      # @api private
+      class Theme
+        COLORS = %w[background stroke text header_text cell_fill reserved_fill hatch].freeze
+        COLOR = /\A(?:\#[0-9a-fA-F]{3}|\#[0-9a-fA-F]{6}|\#[0-9a-fA-F]{8}|[a-zA-Z]+|rgba?\([0-9., %]+\))\z/
+        DIRECTORY = File.expand_path("../../themes", __dir__)
+
+        attr_reader :data
+
+        def initialize(name)
+          defaults = read(File.join(DIRECTORY, "default.yml"))
+          path = %w[default dark mono].include?(name.to_s) ? File.join(DIRECTORY, "#{name}.yml") : name.to_s
+          @data = defaults.merge(read(path))
+          validate
+        end
+
+        def [](key)
+          data.fetch(key)
+        end
+
+        def field_fill(field, index)
+          classes = field.classes.filter_map { |name| self["classes"][name]&.fetch("fill", nil) }
+          palette = self["palette"]
+          field.fill || classes.last || (palette[index % palette.size] unless palette.empty?) ||
+            self[field.reserved ? "reserved_fill" : "cell_fill"]
+        end
+
+        private
+
+        def read(path)
+          result = Loader.new.load_file(path).data
+          raise RenderError, "theme must be an object" unless result.is_a?(Hash)
+
+          result
+        rescue ParseError => e
+          raise RenderError, "invalid theme: #{e.message}"
+        end
+
+        def validate
+          unknown = data.keys - COLORS - %w[palette classes]
+          raise RenderError, "unknown theme keys: #{unknown.join(', ')}" unless unknown.empty?
+          raise RenderError, "theme palette must be an array" unless self["palette"].is_a?(Array)
+          raise RenderError, "theme classes must be an object" unless self["classes"].is_a?(Hash)
+
+          COLORS.each { |key| validate_color(self[key]) }
+          self["palette"].each { |color| validate_color(color) }
+          self["classes"].each do |name, rules|
+            unless name.is_a?(String) && /\A[a-zA-Z_][a-zA-Z0-9_-]*\z/.match?(name) &&
+                   rules.is_a?(Hash) && (rules.keys - ["fill"]).empty?
+              raise RenderError, "theme class must have a safe name and fill property"
+            end
+
+            rules.each_value { |color| validate_color(color) }
+          end
+        end
+
+        def validate_color(color)
+          raise RenderError, "invalid theme color: #{color.inspect}" unless color.is_a?(String) && COLOR.match?(color)
+        end
+      end
+    end
+  end
+end

data/lib/bitgram/renderers/svg/xml_builder.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Bitgram
+  module Renderers
+    class Svg
+      # @api private
+      module XmlBuilder
+        module_function
+
+        def escape(value)
+          value.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+               .gsub('"', "&quot;").gsub("'", "&apos;")
+        end
+
+        def number(value)
+          rounded = value.round(2)
+          rounded == rounded.round ? rounded.round.to_s : format("%.2f", rounded).sub(/0+\z/, "")
+        end
+
+        def attributes(values)
+          values.compact.map do |key, value|
+            %(#{key}="#{escape(value.is_a?(Numeric) ? number(value) : value)}")
+          end.join(" ")
+        end
+
+        def element(name, attributes = {}, text = nil)
+          attrs = attributes.empty? ? "" : " #{self.attributes(attributes)}"
+          text.nil? ? "<#{name}#{attrs}/>" : "<#{name}#{attrs}>#{escape(text)}</#{name}>"
+        end
+      end
+    end
+  end
+end

data/lib/bitgram/renderers/svg.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require_relative "../text/fitter"
+require_relative "svg/xml_builder"
+require_relative "svg/theme"
+require_relative "svg/geometry"
+require_relative "svg/decorations"
+require_relative "svg/cells"
+
+module Bitgram
+  # @api private
+  module Renderers
+    # @api private
+    class Svg
+      include Decorations
+      include Cells
+
+      attr_reader :issues, :width, :height
+
+      def initialize(result, **options)
+        @result = result
+        @document = result.document
+        @options = @document.svg.merge(options.transform_keys(&:to_s).transform_values do |value|
+          value.is_a?(Symbol) ? value.to_s : value
+        end)
+        @issues = []
+      end
+
+      def render
+        prepare
+        @output = []
+        attributes = { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 #{fmt(width)} #{fmt(height)}",
+                       width: width, height: height, role: "img", "aria-labelledby": "#{@prefix}-title #{@prefix}-desc",
+                       class: "bitgram", id: "#{@prefix}-diagram" }
+        @output << "<svg #{XmlBuilder.attributes(attributes)}>"
+        emit("title", { id: "#{@prefix}-title" }, @document.title || "Bit-field diagram")
+        emit("desc", { id: "#{@prefix}-desc" }, @document.description || "Bit-field layout")
+        draw_definitions
+        draw_styles unless @options["inline_styles"]
+        draw_header
+        draw_rows
+        draw_footer
+        @output << "</svg>"
+        @issues = @fitter.issues
+        "#{@output.join("\n")}\n"
+      end
+
+      private
+
+      def prepare
+        selected_theme = @options["theme"] == "auto" ? "default" : @options["theme"]
+        @theme = Theme.new(selected_theme)
+        @prefix = @options["id_prefix"] || default_prefix
+        @field_indexes = @document.fields.each_with_index.to_h { |field, index| [field.id, index] }
+        @measurer = Text::SvgMeasurer.new(font_size: @options["font_size"], ratio: @options["char_width_ratio"])
+        @fitter = Text::Fitter.new(measurer: @measurer, font_size: @options["font_size"],
+                                   min_font_size: @options["min_font_size"],
+                                   footnote_marker: @document.ascii["footnote_marker"])
+        @fits = @result.rows.map { |row| row.cells.map { |cell| fit_cell(cell) } }
+        @footer = @fitter.footnotes + @document.notes
+        @geometry = Geometry.new(@result, @options, @fits, @footer, @measurer)
+        @width = @geometry.width
+        @height = @geometry.height
+      end
+
+      def fit_cell(cell)
+        inner_width = [(cell.bits * @options["bit_width"]) - 8, 0].max
+        label = @result.cell_label(cell)
+        if cell.part != :whole && @document.layout["split_label"] == "range" && @measurer.width(label) > inner_width
+          label = cell.field.name
+        end
+        arguments = { inner_width: inner_width, max_lines: @document.ascii["max_label_lines"],
+                      order: @options["fit_order"], path: "$.fields[#{@field_indexes.fetch(cell.field.id)}].name" }
+        fit = @fitter.fit(text: label, short: cell.field.short, description: cell.field.description, **arguments)
+        value = cell.field.value
+        value_fit = @fitter.fit(text: "= #{value}", **arguments) unless value.nil?
+        [fit, value_fit]
+      end
+
+      def default_prefix
+        slug = @document.title.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")
+        return slug unless slug.empty?
+
+        content = @document.to_h.merge(fields: @document.fields.map(&:to_h))
+        "bitgram-#{Digest::SHA256.hexdigest(JSON.generate(content))[0, 8]}"
+      end
+
+      def draw_rows
+        @output << '<g class="bg-rows">'
+        y = @geometry.y
+        @result.rows.each_with_index do |row, index|
+          row_height = @geometry.row_heights[index]
+          attributes = { class: "bg-row", "data-row": row.index,
+                         "data-offset": row.offset_bits && (row.offset_bits / 8.0) }
+          @output << "<g #{XmlBuilder.attributes(attributes)}>"
+          row.cells.each_with_index { |cell, col| draw_cell(cell, row, y, row_height, @fits[index][col]) }
+          draw_ticks(row, y, row_height) if @options["ticks"]
+          draw_offset(row, y, row_height)
+          @output << "</g>"
+          y += row_height
+        end
+        @output << "</g>"
+      end
+
+      def draw_footer
+        return if @footer.empty?
+
+        y = @geometry.y + @geometry.row_heights.sum + 8 + @options["font_size"]
+        @output << '<g class="bg-footnotes">'
+        @footer.each do |line|
+          emit("text", text_attributes("bg-footnote").merge(x: @geometry.x, y: y, "text-anchor": "start"), line)
+          y += @options["font_size"] * 1.4
+        end
+        @output << "</g>"
+      end
+
+      def text_attributes(klass, size = @options["font_size"])
+        attributes = { class: klass, "font-size": size, "text-anchor": "middle" }
+        if @options["inline_styles"]
+          attributes[:"font-family"] = @options["font_family"]
+          attributes[:fill] = @theme["text"]
+        end
+        attributes
+      end
+
+      def emit(name, attributes = {}, text = nil)
+        @output << XmlBuilder.element(name, attributes, text)
+      end
+
+      def fmt(value)
+        XmlBuilder.number(value)
+      end
+    end
+  end
+end