bitgram 0.1.0

data/lib/bitgram/layout/cell.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Bitgram
+  module Layout
+    # A field segment in bit coordinates. Ranges are relative to its field.
+    Cell = Data.define(:field, :col, :bits, :part, :range)
+  end
+end

data/lib/bitgram/layout/engine.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "cell"
+require_relative "row"
+require_relative "result"
+
+module Bitgram
+  module Layout
+    # @api private
+    class Engine
+      def call(document)
+        @document = document
+        @width = document.layout.fetch("row_bits")
+        @rows = []
+        @pending = []
+        @col = @position = @row_position = 0
+        document.fields.each { |field| place(field) }
+        append_row(:normal) unless @pending.empty?
+        Result.new(document, @rows.freeze, [].freeze)
+      end
+
+      private
+
+      def place(field)
+        if @col.zero? && field.variable? && field.display_bits == @width
+          @pending << Cell.new(field, 0, @width, :whole, nil)
+          append_row(:variable)
+          @position = @row_position = nil
+        elsif block?(field)
+          @pending << Cell.new(field, 0, @width, :whole, 0...field.bits)
+          append_row(:block, field.bits / @width)
+          @position += field.bits if @position
+          @row_position = @position
+        else
+          place_segments(field)
+        end
+      end
+
+      def block?(field)
+        @document.layout["merge_rows"] && @col.zero? && !field.variable? &&
+          field.bits >= 2 * @width && (field.bits % @width).zero?
+      end
+
+      def place_segments(field)
+        consumed = 0
+        while consumed < field.width_bits
+          take = [field.width_bits - consumed, @width - @col].min
+          range = field.variable? ? nil : consumed...(consumed + take)
+          @pending << Cell.new(field, @col, take, part_of(consumed, take, field.width_bits), range)
+          @col += take
+          consumed += take
+          next unless @col == @width
+
+          append_row(:normal)
+          @row_position = @position && !field.variable? ? @position + consumed : nil
+        end
+        @position = field.variable? || @position.nil? ? nil : @position + field.bits
+      end
+
+      def append_row(kind, span = 1)
+        @rows << Row.new(@rows.size, kind, @pending.freeze, span, @row_position)
+        @pending = []
+        @col = 0
+      end
+
+      def part_of(consumed, take, total)
+        return :whole if consumed.zero? && take == total
+        return :head if consumed.zero?
+
+        consumed + take == total ? :tail : :middle
+      end
+    end
+  end
+end

data/lib/bitgram/layout/result.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Bitgram
+  module Layout
+    # The shared, format-independent layout used by all renderers.
+    Result = Data.define(:document, :rows, :issues) do
+      # @param cell [Cell] segment whose display label is requested
+      # @return [String] label including a continuation or relative bit range
+      def cell_label(cell)
+        name = cell.field.name
+        return name if cell.part == :whole
+
+        case document.layout["split_label"]
+        when "first" then cell.part == :head ? name : "(cont.)"
+        when "repeat" then name
+        else
+          return name unless cell.range
+
+          name + document.layout["split_suffix"].gsub("{from}", cell.range.begin.to_s)
+                         .gsub("{to}", (cell.range.end - 1).to_s)
+        end
+      end
+
+      # @param row [Row] row whose starting position is requested
+      # @return [String] byte offset, bit offset, or blank if unknown/disabled
+      def offset_label(row)
+        return "" if row.offset_bits.nil? || document.layout["offsets"] == "none"
+        return "#{row.offset_bits}b" unless (row.offset_bits % 8).zero?
+
+        bytes = row.offset_bits / 8
+        document.layout["offsets"] == "hex" ? format("0x%02x", bytes) : bytes.to_s
+      end
+    end
+  end
+end

data/lib/bitgram/layout/row.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Bitgram
+  # Logical rows and cells shared by all output formats.
+  module Layout
+    # A logical row; span counts physical rows in a merged block.
+    Row = Data.define(:index, :kind, :cells, :span, :offset_bits)
+  end
+end

data/lib/bitgram/loader.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module Bitgram
+  # @api private
+  class Loader
+    MAX_BYTES = 1024 * 1024
+    Source = Data.define(:data, :line_map, :filename)
+
+    def load_file(path, format: nil)
+      content = File.open(path, "r:UTF-8") { |file| file.read(MAX_BYTES + 1) }
+      format ||= :json if File.extname(path).downcase == ".json"
+      load_string(content, format: format, filename: path.to_s)
+    end
+
+    def load_string(str, format: nil, filename: nil)
+      raise ParseError, "input too large (> 1 MiB)" if str.bytesize > MAX_BYTES
+      raise ParseError, "input must be valid UTF-8" unless str.dup.force_encoding("UTF-8").valid_encoding?
+
+      str = str.dup.force_encoding("UTF-8")
+      format = (format || (str.lstrip.start_with?("{", "[") ? :json : :yaml)).to_sym
+      case format
+      when :json then Source.new(JSON.parse(str, max_nesting: 20), {}, filename)
+      when :yaml, :yml
+        map = {}
+        ast = Psych.parse_stream(str, filename: filename)
+        raise ParseError, "expected one YAML document" if ast.children.length > 1
+
+        walk(ast.children.first&.root, "$", map, 0)
+        data = YAML.safe_load(str, permitted_classes: [], aliases: false, filename: filename)
+        Source.new(data, map, filename)
+      else raise ArgumentError, "unknown input format: #{format}"
+      end
+    rescue JSON::ParserError, Psych::Exception, EncodingError => e
+      raise ParseError, "#{filename || '<input>'}: #{e.message}"
+    end
+
+    private
+
+    def walk(node, path, map, depth)
+      return unless node
+      raise ParseError, "input nesting exceeds 20 levels" if depth > 20
+
+      map[path] = node.start_line + 1
+      case node
+      when Psych::Nodes::Mapping
+        node.children.each_slice(2) do |key, value|
+          raise ParseError, "YAML mapping keys must be scalar strings" unless key.is_a?(Psych::Nodes::Scalar)
+
+          walk(value, "#{path}.#{key.value}", map, depth + 1)
+        end
+      when Psych::Nodes::Sequence
+        node.children.each_with_index { |child, i| walk(child, "#{path}[#{i}]", map, depth + 1) }
+      end
+    end
+  end
+end

data/lib/bitgram/model/document.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Bitgram
+  module Model
+    # @api private
+    Document = Data.define(:title, :description, :layout, :ascii, :svg, :raster, :fields, :notes)
+  end
+end

data/lib/bitgram/model/field.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Bitgram
+  # @api private
+  module Model
+    # @api private
+    Field = Data.define(:id, :name, :short, :bits, :variable, :display_bits,
+                        :description, :value, :reserved, :optional, :classes, :fill) do
+      def variable? = variable
+      def width_bits = variable ? display_bits : bits
+    end
+  end
+end

data/lib/bitgram/normalizer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Bitgram
+  # @api private
+  class Normalizer
+    def call(raw)
+      data = Config.deep_merge(Config::DEFAULTS, Config.stringify(raw))
+      used = data.fetch("fields").filter_map { |field| field["id"] }.to_h { |id| [id, true] }
+      fields = data["fields"].each_with_index.map do |field, i|
+        normalize_field(field, i, used, data["layout"]["row_bits"])
+      end
+      Config.deep_freeze(data)
+      Model::Document.new(title: data["title"], description: data["description"],
+                          layout: data["layout"], ascii: data["ascii"], svg: data["svg"], raster: data["raster"],
+                          fields: fields.freeze, notes: data.fetch("notes", []).freeze)
+    end
+
+    private
+
+    def normalize_field(field, index, used, row_bits)
+      id = field["id"] || unique_id(field["name"], index, used)
+      variable = field["bits"] == "variable"
+      Config.deep_freeze(field)
+      Model::Field.new(id: id.freeze, name: field["name"], short: field["short"],
+                       bits: variable ? nil : field.fetch("bits") { field["bytes"] * 8 }, variable: variable,
+                       display_bits: field.fetch("display_bits", row_bits), description: field["description"],
+                       value: field["value"], reserved: field.fetch("reserved", false),
+                       optional: field.fetch("optional", false),
+                       classes: Array(field["class"]).flat_map(&:split).map(&:freeze).freeze,
+                       fill: field["fill"])
+    end
+
+    def unique_id(name, index, used)
+      base = Config.slug(name)
+      base = "field-#{index + 1}" if base.empty?
+      id = base
+      suffix = 1
+      while used[id]
+        suffix += 1
+        id = "#{base}-#{suffix}"
+      end
+      used[id] = true
+      id
+    end
+  end
+end

data/lib/bitgram/presets/arp.yml

@@ -0,0 +1,13 @@
+version: 1
+title: ARP Header
+description: RFC 826, Ethernet and IPv4
+fields:
+  - { name: Hardware Type, bits: 16 }
+  - { name: Protocol Type, bits: 16 }
+  - { name: HLEN, bits: 8 }
+  - { name: PLEN, bits: 8 }
+  - { name: Operation, bits: 16 }
+  - { name: Sender Hardware Address, bits: 48 }
+  - { name: Sender Protocol Address, bits: 32 }
+  - { name: Target Hardware Address, bits: 48 }
+  - { name: Target Protocol Address, bits: 32 }

data/lib/bitgram/presets/icmp.yml

@@ -0,0 +1,10 @@
+version: 1
+title: ICMP Echo Header
+description: RFC 792, Echo or Echo Reply
+fields:
+  - { name: Type, bits: 8 }
+  - { name: Code, bits: 8 }
+  - { name: Checksum, bits: 16 }
+  - { name: Identifier, bits: 16 }
+  - { name: Sequence Number, bits: 16 }
+  - { name: Data, bits: variable }

data/lib/bitgram/presets/ipv4.yml

@@ -0,0 +1,20 @@
+version: 1
+title: IPv4 Header
+description: RFC 791, with DSCP and ECN from RFC 2474 and RFC 3168
+fields:
+  - { name: Version, bits: 4 }
+  - { name: IHL, bits: 4 }
+  - { name: DSCP, bits: 6 }
+  - { name: ECN, bits: 2 }
+  - { name: Total Length, bits: 16 }
+  - { name: Identification, bits: 16 }
+  - { name: Flags, bits: 3 }
+  - { name: Fragment Offset, bits: 13 }
+  - { name: Time to Live, bits: 8 }
+  - { name: Protocol, bits: 8 }
+  - { name: Header Checksum, bits: 16 }
+  - { name: Source Address, bits: 32 }
+  - { name: Destination Address, bits: 32 }
+  - { name: Options, bits: variable, display_bits: 24 }
+  - { name: Padding, bits: variable, display_bits: 8 }
+  - { name: Data, bits: variable }

data/lib/bitgram/presets/ipv6.yml

@@ -0,0 +1,12 @@
+version: 1
+title: IPv6 Header
+description: RFC 8200, Section 3
+fields:
+  - { name: Version, bits: 4 }
+  - { name: Traffic Class, bits: 8 }
+  - { name: Flow Label, bits: 20 }
+  - { name: Payload Length, bits: 16 }
+  - { name: Next Header, bits: 8 }
+  - { name: Hop Limit, bits: 8 }
+  - { name: Source Address, bits: 128 }
+  - { name: Destination Address, bits: 128 }

data/lib/bitgram/presets/tcp.yml

@@ -0,0 +1,23 @@
+version: 1
+title: TCP Header
+description: RFC 9293, Section 3.1
+fields:
+  - { name: Source Port, bits: 16 }
+  - { name: Destination Port, bits: 16 }
+  - { name: Sequence Number, bits: 32 }
+  - { name: Acknowledgment Number, bits: 32 }
+  - { name: Data Offset, bits: 4 }
+  - { name: Rsrvd, bits: 4, reserved: true }
+  - { name: CWR, bits: 1, description: Congestion Window Reduced }
+  - { name: ECE, bits: 1, description: ECN-Echo }
+  - { name: URG, bits: 1, description: Urgent pointer field is significant }
+  - { name: ACK, bits: 1, description: Acknowledgment field is significant }
+  - { name: PSH, bits: 1, description: Push function }
+  - { name: RST, bits: 1, description: Reset the connection }
+  - { name: SYN, bits: 1, description: Synchronize sequence numbers }
+  - { name: FIN, bits: 1, description: No more data from sender }
+  - { name: Window, bits: 16 }
+  - { name: Checksum, bits: 16 }
+  - { name: Urgent Pointer, bits: 16 }
+  - { name: Options, bits: variable }
+  - { name: Data, bits: variable }

data/lib/bitgram/presets/udp.yml

@@ -0,0 +1,9 @@
+version: 1
+title: UDP Header
+description: RFC 768
+fields:
+  - { name: Source Port, bits: 16 }
+  - { name: Destination Port, bits: 16 }
+  - { name: Length, bits: 16 }
+  - { name: Checksum, bits: 16 }
+  - { name: Data, bits: variable }

data/lib/bitgram/rasterizers/base.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Bitgram
+  # @api private
+  module Rasterizers
+    # @api private
+    class Base
+      PROBE = '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"/>'
+
+      attr_writer :timeout
+
+      def initialize(timeout: 30)
+        @timeout = timeout
+      end
+
+      def name
+        self.class.name.split("::").last.downcase
+      end
+
+      def available?
+        raise NotImplementedError
+      end
+
+      def supports?(format)
+        %i[png jpeg].include?(format.to_sym)
+      end
+
+      def rasterize(*)
+        raise NotImplementedError
+      end
+
+      def version
+        "unknown"
+      end
+
+      private
+
+      def check_format(format)
+        raise RasterizeError, "#{name} does not support #{format}" unless supports?(format)
+      end
+    end
+  end
+end

data/lib/bitgram/rasterizers/image_magick.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../util/command"
+
+module Bitgram
+  module Rasterizers
+    # @api private
+    class ImageMagick < Base
+      def available?
+        return @available unless @available.nil?
+
+        @binary = Util::Command.which("magick") || Util::Command.which("convert")
+        @available = false
+        return false unless @binary
+
+        Util::Command.run([@binary, "svg:-", "png:-"], stdin_data: PROBE, timeout: @timeout)
+        @available = true
+      rescue RasterizeError
+        false
+      end
+
+      def rasterize(svg, path:, format:, scale:, background:, quality:)
+        check_format(format)
+        raise RasterizerNotFound, "ImageMagick with SVG support is unavailable" unless available?
+
+        color = background == "transparent" ? "none" : background || "none"
+        command = [@binary, "-density", (96 * scale).to_s, "-background", color, "svg:-"]
+        command << "-flatten" unless color == "none"
+        command.push("-quality", quality.to_s, "#{format}:#{File.expand_path(path)}")
+        Util::Command.run(command, stdin_data: svg, timeout: @timeout)
+      end
+
+      def version
+        if available?
+          Util::Command.run([@binary, "-version"], stdin_data: "",
+                                                   timeout: @timeout).lines.first.strip
+        else
+          "unavailable"
+        end
+      end
+    end
+  end
+end

data/lib/bitgram/rasterizers/registry.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "vips"
+require_relative "rsvg"
+require_relative "image_magick"
+
+module Bitgram
+  module Rasterizers
+    # @api private
+    module Registry
+      INSTALL = "Install a rasterizer: macOS: brew install vips librsvg imagemagick; " \
+                "Ubuntu: sudo apt-get install libvips-dev librsvg2-bin imagemagick. " \
+                "For vips, also add gem 'ruby-vips' to your Gemfile."
+
+      module_function
+
+      def all
+        @all ||= { vips: Vips.new, rsvg: Rsvg.new, imagemagick: ImageMagick.new }
+      end
+
+      def select(name = :auto, format:, timeout: 30)
+        candidates = name.to_s == "auto" ? all.values : [all[name.to_sym]].compact
+        converter = candidates.find do |item|
+          item.timeout = timeout
+          item.supports?(format) && item.available?
+        end
+        raise RasterizerNotFound, "No #{name} rasterizer available for #{format}. #{INSTALL}" unless converter
+
+        converter.dup.tap { |selected| selected.timeout = timeout }
+      end
+    end
+  end
+end

data/lib/bitgram/rasterizers/rsvg.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../util/command"
+
+module Bitgram
+  module Rasterizers
+    # @api private
+    class Rsvg < Base
+      def available?
+        return @available unless @available.nil?
+
+        @binary = Util::Command.which("rsvg-convert")
+        @available = !@binary.nil?
+      end
+
+      def supports?(format)
+        format.to_sym == :png
+      end
+
+      def rasterize(svg, path:, format:, scale:, background:, **)
+        check_format(format)
+        raise RasterizerNotFound, "rsvg-convert is unavailable" unless available?
+
+        command = [@binary, "--format", "png", "--zoom", scale.to_s, "--output", File.expand_path(path)]
+        command.push("--background-color", background) if background && background != "transparent"
+        Util::Command.run(command, stdin_data: svg, timeout: @timeout)
+      end
+
+      def version
+        available? ? Util::Command.run([@binary, "--version"], stdin_data: "", timeout: @timeout).strip : "unavailable"
+      end
+    end
+  end
+end

data/lib/bitgram/rasterizers/vips.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Bitgram
+  module Rasterizers
+    # @api private
+    class Vips < Base
+      def available?
+        return @available unless @available.nil?
+
+        @available = false
+        require "vips"
+        ::Vips::Image.svgload_buffer(PROBE)
+        @available = true
+      rescue LoadError, StandardError
+        false
+      end
+
+      def rasterize(svg, path:, format:, scale:, background:, quality:)
+        check_format(format)
+        raise RasterizerNotFound, "ruby-vips with SVG support is unavailable" unless available?
+
+        image = ::Vips::Image.svgload_buffer(svg, scale: scale)
+        image = image.flatten(background: rgb(background)) if background && background != "transparent"
+        if format.to_sym == :png
+          image.pngsave(path)
+        else
+          image.jpegsave(path, Q: quality)
+        end
+      rescue StandardError => e
+        raise if e.is_a?(Bitgram::Error)
+
+        raise RasterizeError, "vips failed: #{e.message}"
+      end
+
+      def version
+        available? ? "libvips #{::Vips.version_string}, svgload: yes" : "unavailable"
+      end
+
+      private
+
+      def rgb(color)
+        # Let the SVG backend interpret the same validated CSS colors as the diagram.
+        swatch = '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1">' \
+                 "<rect width=\"1\" height=\"1\" fill=\"#{color}\"/></svg>"
+        ::Vips::Image.svgload_buffer(swatch).getpoint(0, 0).first(3)
+      end
+    end
+  end
+end

data/lib/bitgram/renderers/ascii/box_chars.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Bitgram
+  module Renderers
+    class Ascii
+      # @api private
+      module BoxChars
+        module_function
+
+        def border(width, above:, below:, unicode:)
+          return "#{'+-' * width}+" unless unicode
+
+          top = above.nil?
+          bottom = below.nil?
+          left, right = if top
+                          %w[┌ ┐]
+                        else
+                          (bottom ? %w[└ ┘] : %w[├ ┤])
+                        end
+          upper = boundaries(above)
+          lower = boundaries(below)
+          middle = (1...(2 * width)).map do |column|
+            next "─" if column.odd?
+
+            up = upper.include?(column / 2)
+            down = lower.include?(column / 2)
+            if up
+              down ? "┼" : "┴"
+            else
+              (down ? "┬" : "─")
+            end
+          end.join
+          left + middle + right
+        end
+
+        def boundaries(row)
+          return [] unless row
+
+          row.cells.flat_map { |cell| [cell.col, cell.col + cell.bits] }
+        end
+      end
+    end
+  end
+end