badline 0.13.0 → 0.15.0

data/lib/badline/snapshot/keyed/cursor.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Keyed
+      # Reads BER numbers and byte runs from a module's payload, or from one
+      # record's value, failing on anything cut short.
+      class Cursor
+        def initialize(bytes, name)
+          @bytes = bytes
+          @name = name
+          @pos = 0
+        end
+
+        def done? = @pos >= @bytes.bytesize
+
+        def remaining = @bytes.bytesize - @pos
+
+        def ber
+          value = 0
+          loop do
+            raise FormatError, "#{@name} holds a number too large for a snapshot" if value >= (1 << 56)
+
+            byte = take(1).getbyte(0).to_i
+            value = (value << 7) | (byte & 0x7f)
+            return value if byte < 0x80
+          end
+        end
+
+        def int = Keyed.unzigzag(ber)
+
+        def take(count)
+          raise FormatError, "#{@name} ends early, at byte #{@bytes.bytesize}" if count > remaining
+
+          @bytes.byteslice(@pos, count).to_s.tap { @pos += count }
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/keyed/modules.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Keyed
+      # A snapshot's BL-* modules by name, which a family reads in its own
+      # fixed order, whatever order the file has them in. Each module is
+      # parsed once, and its Reader kept for the Report.
+      #
+      # A `detached` load restores a machine that opens no host file and
+      # writes none: a disk image comes from the bytes the snapshot holds,
+      # write-protected, and a directory device 8 serves is left out.
+      class Modules
+        attr_reader :readers
+
+        def initialize(sections, detached: false)
+          @sections = {}
+          sections.each { |section| @sections[section.name] = section }
+          @parsed = {}
+          @readers = []
+          @detached = detached
+        end
+
+        def detached? = @detached
+
+        # BL-MACHINE, which every family writes first.
+        def machine = required("BL-MACHINE")
+
+        # The module a family always writes, or a Reader standing in for it,
+        # reported missing.
+        def required(name)
+          reader = @parsed[name]
+          return reader if reader
+
+          section = @sections[name]
+          keep(name, section.nil? ? missing(name) : parse(section))
+        end
+
+        # The module, or nil when the snapshot has none, as it has none for a
+        # cartridge or a drive that isn't there.
+        def optional(name)
+          reader = @parsed[name]
+          return reader if reader
+
+          section = @sections[name]
+          section.nil? ? nil : keep(name, parse(section))
+        end
+
+        # The BL-* modules no family read, from a later badline.
+        def unread = @sections.keys.select { |name| name.start_with?("BL-") && !@parsed.key?(name) }
+
+        private
+
+        def parse(section) = Reader.parse(section)
+
+        def missing(name) = Reader.missing(name)
+
+        def keep(name, reader)
+          @parsed[name] = reader
+          @readers << reader
+          reader
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/keyed/reader.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Keyed
+      # Parses a module's records into one Hash per type, so every value
+      # read has a single type in Spinel. Each read takes the current value
+      # as its default, which in a machine built for the load is power-on,
+      # and returns it when the record is missing or of another type.
+      #
+      # A Reader with no records stands in for a module the snapshot
+      # doesn't have, so every load takes the same path.
+      class Reader
+        # The tag of each key the module's records hold.
+        attr_reader :name, :tags
+
+        # Whether it stands in for a module the snapshot doesn't have.
+        def missing? = @missing
+
+        # The records in `section`, which must be in this encoding.
+        def self.parse(section)
+          unless section.major == MAJOR
+            raise FormatError, "#{section.name} #{section.version} was written by a newer badline's encoding, " \
+                               "and this one reads #{MAJOR}.#{MINOR}"
+          end
+
+          new(section.name, Zlib.inflate(section.data))
+        rescue Zlib::Error => e
+          raise FormatError, "#{section.name} is damaged: #{e.message}"
+        end
+
+        # Stands in for a module the snapshot doesn't have.
+        def self.missing(name) = new(name, "".b, missing: true)
+
+        def initialize(name, payload = "".b, missing: false)
+          @name = name
+          @missing = missing
+          @ints = {}
+          @bools = {}
+          @bytes = {}
+          @lists = {}
+          @texts = {}
+          @tags = {}
+          @read = {}
+          @adjusted = []
+          @unknown_tags = 0
+          parse(Cursor.new(payload, name))
+        end
+
+        def int(key, default) = fetch_int(key, default)
+
+        def word(key, default) = fetch_masked(key, default, 0xffff)
+
+        def byte(key, default) = fetch_masked(key, default, 0xff)
+
+        # An int cut to the bits a latch holds, reported if it was wider.
+        def masked(key, default, mask) = fetch_masked(key, default, mask)
+
+        def bool(key, default) = present?(key, "a bool", @bools.key?(key)) ? @bools.fetch(key) : default
+
+        # Nil when the record is missing.
+        def optional_int(key) = present?(key, "an int", @ints.key?(key)) ? @ints.fetch(key) : nil
+
+        def ints(key, default) = present?(key, "a list of ints", @lists.key?(key)) ? @lists.fetch(key) : default
+
+        # A binary String.
+        def bytes(key, default) = fetch_bytes(key, default)
+
+        # Reads a hardware array into `array` in place. A shorter list
+        # leaves the rest as it was and a longer one is cut, and both are
+        # reported.
+        def ints_into(key, array)
+          return array unless present?(key, "a list of ints", @lists.key?(key))
+
+          fill(key, array, @lists.fetch(key))
+        end
+
+        def bytes_into(key, array)
+          return array unless present?(key, "bytes", @bytes.key?(key))
+
+          fill(key, array, @bytes.fetch(key).bytes)
+        end
+
+        def text(key, default) = fetch_text(key, default)
+
+        # The text, if it is one of `names`, and otherwise `default`,
+        # reported.
+        def choice(key, names, default)
+          value = fetch_text(key, default)
+          return value if names.include?(value)
+
+          @adjusted << "#{key} #{value.inspect} is not one of #{names.join(', ')}, left at #{default}"
+          default
+        end
+
+        # Reports something a unit's load left out or changed beyond one
+        # field, such as a line batch from another renderer.
+        def adjust(line)
+          @adjusted << line
+          self
+        end
+
+        # The keys of records nothing read.
+        def unknown = @tags.keys.reject { |key| @read.key?(key) }
+
+        def report
+          Report.new(name:, missing: @missing, unknown:, adjusted: @adjusted.dup, unknown_tags: @unknown_tags)
+        end
+
+        private
+
+        def fetch_int(key, default) = present?(key, "an int", @ints.key?(key)) ? @ints.fetch(key) : default
+
+        def fetch_masked(key, default, mask)
+          value = fetch_int(key, default)
+          return value if value & mask == value
+
+          @adjusted << "#{key} #{value} is wider than its latch, masked to #{value & mask}"
+          value & mask
+        end
+
+        def fetch_bytes(key, default) = present?(key, "bytes", @bytes.key?(key)) ? @bytes.fetch(key) : default
+
+        def fetch_text(key, default) = present?(key, "text", @texts.key?(key)) ? @texts.fetch(key) : default
+
+        # Whether the key has a record of the type read, `there`. A record
+        # of another type counts as missing, and is reported.
+        def present?(key, type, there)
+          @read[key] = true if there || @tags.key?(key)
+          @adjusted << "#{key} is not #{type}, left at its default" if !there && @tags.key?(key)
+          there
+        end
+
+        def fill(key, array, values)
+          unless values.length == array.length
+            what = values.length < array.length ? "the rest left as they were" : "the rest cut"
+            @adjusted << "#{key} holds #{values.length} values where #{array.length} fit, #{what}"
+          end
+          [values.length, array.length].min.times { |index| array[index] = values[index] }
+          array
+        end
+
+        def parse(cursor)
+          until cursor.done?
+            key = cursor.take(cursor.ber)
+            tag = cursor.take(1).getbyte(0).to_i
+            store(key, tag, cursor.take(cursor.ber))
+          end
+        end
+
+        def store(key, tag, value)
+          unless tag.between?(INT, TEXT)
+            @unknown_tags += 1
+            return
+          end
+
+          forget(key)
+          @tags[key] = tag
+          case tag
+          when INT then @ints[key] = Cursor.new(value, "#{@name} #{key}").int
+          when BOOL then @bools[key] = value.getbyte(0).to_i != 0
+          when BYTES then @bytes[key] = value
+          when INTS then @lists[key] = list(Cursor.new(value, "#{@name} #{key}"))
+          else @texts[key] = value.force_encoding(Encoding::UTF_8)
+          end
+        end
+
+        def forget(key)
+          return unless @tags.key?(key)
+
+          @adjusted << "#{key} appears more than once, the last one counts"
+          @ints.delete(key)
+          @bools.delete(key)
+          @bytes.delete(key)
+          @lists.delete(key)
+          @texts.delete(key)
+        end
+
+        def list(cursor)
+          count = cursor.ber
+          raise FormatError, "#{@name} ends early, in a list of #{count}" if count > cursor.remaining
+
+          Array.new(count) { cursor.int }
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/keyed/recorder.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Keyed
+      # A Reader that notes every read: the module, the key, the type read
+      # and the default passed. Loading a machine at power-on through
+      # Recorders lists each module's fields with their power-on values
+      # (FieldDoc).
+      class Recorder < Reader
+        Field = Data.define(:module_name, :key, :type, :default)
+
+        attr_reader :fields
+
+        def initialize(name, payload = "".b, missing: false)
+          super
+          @fields = []
+        end
+
+        def int(key, default)
+          note(key, "int", default)
+          super
+        end
+
+        def word(key, default)
+          note(key, "word", default)
+          super
+        end
+
+        def byte(key, default)
+          note(key, "byte", default)
+          super
+        end
+
+        def masked(key, default, mask)
+          note(key, "int & 0x#{mask.to_s(16)}", default)
+          super
+        end
+
+        def bool(key, default)
+          note(key, "bool", default)
+          super
+        end
+
+        def optional_int(key)
+          note(key, "int, optional", nil)
+          super
+        end
+
+        def ints(key, default)
+          note(key, "ints", default.dup)
+          super
+        end
+
+        def bytes(key, default)
+          note(key, "bytes", default.dup)
+          super
+        end
+
+        def ints_into(key, array)
+          note(key, "ints", array.dup)
+          super
+        end
+
+        def bytes_into(key, array)
+          note(key, "bytes", array.dup)
+          super
+        end
+
+        def text(key, default)
+          note(key, "text", default)
+          super
+        end
+
+        def choice(key, names, default)
+          note(key, "text: #{names.join(' ')}", default)
+          super
+        end
+
+        private
+
+        def note(key, type, default)
+          @fields << Field.new(module_name: name, key:, type:, default:)
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/keyed/report.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Keyed
+      # What reading a module left out or changed: whether the snapshot
+      # had the module at all, the keys nothing read, a line for each value
+      # read other than as written, and how many records had a tag this
+      # badline doesn't know.
+      Report = Data.define(:name, :missing, :unknown, :adjusted, :unknown_tags) do
+        # Lines for the user. A missing module and adjusted values always
+        # get one, and unknown keys and tags only when `verbose`, since a
+        # snapshot from a later badline has them on every load.
+        def lines(verbose: false)
+          lines = missing ? ["#{name} is missing, left at power-on"] : []
+          lines.concat(adjusted.map { |line| "#{name}: #{line}" })
+          return lines unless verbose
+
+          lines << "#{name}: #{unknown.length} unknown field(s): #{unknown.join(', ')}" unless unknown.empty?
+          lines << "#{name}: #{unknown_tags} field(s) of an unknown type, skipped" if unknown_tags.positive?
+          lines
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/keyed/writer.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Keyed
+      # Appends records to a module's payload. Each method returns self.
+      class Writer
+        def initialize
+          @out = String.new(encoding: Encoding::BINARY)
+        end
+
+        # Raises TypeError unless `value` is an Integer, and RangeError
+        # outside VALUES.
+        def int(key, value) = record(key, INT, Keyed.ber(fold(key, value)))
+
+        def bool(key, value) = record(key, BOOL, value ? "\x01".b : "\x00".b)
+
+        # An Array of 0..255, or a binary String.
+        def bytes(key, values) = record(key, BYTES, values.is_a?(String) ? values.b : values.pack("C*"))
+
+        def ints(key, values)
+          value = Keyed.ber(values.length)
+          values.each { |number| value << Keyed.ber(fold(key, number)) }
+          record(key, INTS, value)
+        end
+
+        def text(key, value) = record(key, TEXT, value.b)
+
+        # Writes nothing for nil, which a reader reads back as nil.
+        def optional_int(key, value) = value.nil? ? self : int(key, value)
+
+        # The records written so far.
+        def to_s = @out.dup
+
+        def section(name) = Section.new(name:, major: MAJOR, minor: MINOR, data: Zlib.deflate(@out))
+
+        private
+
+        def fold(key, value)
+          raise TypeError, "#{key} is not an Integer: #{value.inspect}" unless value.is_a?(Integer)
+          raise RangeError, "#{key} #{value} is too large for a snapshot" unless VALUES.cover?(value)
+
+          Keyed.zigzag(value)
+        end
+
+        def record(key, tag, value)
+          raise ArgumentError, "#{key.inspect} is not a snapshot key" unless key.match?(KEY)
+
+          @out << Keyed.ber(key.bytesize) << key.b << [tag].pack("C") << Keyed.ber(value.bytesize) << value
+          self
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/keyed.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "zlib"
+require "badline/snapshot/container"
+
+module Badline
+  module Snapshot
+    # A snapshot module as keyed, typed records, which a later badline
+    # reads by name: one it doesn't know is skipped, and one that isn't
+    # there leaves the value a freshly built machine has.
+    #
+    # The payload is deflated. Inside, each record is the key's length and
+    # the key (ASCII, lower snake case with dots between sub-units), a
+    # one-byte type tag, then the value's length and the value. Lengths are
+    # BER-compressed (Ruby's pack "w"), and so are integers, each folded to
+    # a natural number (0, -1, 1, -2 ... as 0, 1, 2, 3 ...). The value's
+    # length lets a reader skip a tag it doesn't know.
+    #
+    # A module's header version is MAJOR.MINOR. The major number is this
+    # record encoding, and a reader refuses another one. Fields carry no
+    # version: a changed meaning gets a new key.
+    module Keyed
+      MAJOR = 1
+      MINOR = 0
+
+      INT = 0x01
+      BOOL = 0x02
+      BYTES = 0x03
+      INTS = 0x04
+      TEXT = 0x05
+
+      KEY = /\A[a-z0-9_]+(\.[a-z0-9_]+)*\z/
+
+      # The values an int record holds: what a 64-bit integer holds once
+      # zigzag doubles it, which a native build's integers can't exceed.
+      VALUES = (-(1 << 62))..((1 << 62) - 1)
+
+      module_function
+
+      def ber(number) = [number].pack("w")
+
+      # Folds an Integer in VALUES to a natural number, as a
+      # native build's 64-bit integers hold it.
+      def zigzag(value) = value.negative? ? ((-value - 1) << 1) | 1 : value << 1
+
+      def unzigzag(folded) = folded.odd? ? -(folded >> 1) - 1 : folded >> 1
+
+      # The module `name`, with the records the block writes to the Writer
+      # it yields.
+      def section(name)
+        out = Writer.new
+        yield out
+        out.section(name)
+      end
+    end
+  end
+end
+
+require "badline/snapshot/keyed/cursor"
+require "badline/snapshot/keyed/writer"
+require "badline/snapshot/keyed/report"
+require "badline/snapshot/keyed/reader"
+require "badline/snapshot/keyed/recorder"
+require "badline/snapshot/keyed/modules"

data/lib/badline/snapshot/machine_state.rb

@@ -2,83 +2,36 @@
 
 module Badline
   module Snapshot
-    # The BADLINE module: a State from C64#snapshot, which restores the
-    # machine exactly where it was saved. VICE skips a module it doesn't
-    # know.
+    # The BADLINE module badline 0.13 and earlier saved the machine in, a
+    # positional layout only the version that wrote it reads. All that is
+    # left of it is reading which version that was, for the refusal
+    # (Image#load).
     #
     # The payload is deflated. Inside, a little-endian 32-bit length leads
     # a run of BER-compressed integers (Ruby's pack "w"): the number of
-    # values and of strings, each string's length, then the values, each
-    # folded to a natural number (0, -1, 1, -2 ... as 0, 1, 2, 3 ...). The
-    # strings follow, one after another.
-    #
-    # A State only restores in the badline version that wrote it, since
-    # each chip writes its fields as it holds them.
+    # values and of strings, each string's length, then the values. The
+    # strings follow, one after another: the family's marker first, then
+    # the badline version.
     module MachineState
       NAME = "BADLINE"
-      MAJOR = 2
-      MINOR = 0
-
-      # The values a 64-bit integer holds once encode doubles them, which a
-      # native build's integers can't exceed.
-      VALUES = (-(1 << 62))..((1 << 62) - 1)
 
       module_function
 
-      def section(state)
-        Section.new(name: NAME, major: MAJOR, minor: MINOR, data: Zlib.deflate(encode(state)))
-      end
-
-      def state(section)
-        unless section.major == MAJOR
-          raise FormatError, "#{NAME} #{section.version} was written by another badline version, " \
-                             "and this one reads #{MAJOR}.#{MINOR}"
-        end
-
-        decode(Zlib.inflate(section.data))
-      rescue Zlib::Error => e
-        raise FormatError, "#{NAME} is damaged: #{e.message}"
-      end
-
-      def encode(state)
-        values = state.values
-        strings = state.strings
-        numbers = [values.length, strings.length]
-        strings.each { |string| numbers << string.bytesize }
-        values.each do |value|
-          raise RangeError, "#{value} is too large for a snapshot" unless VALUES.cover?(value)
-
-          numbers << (value.negative? ? (-2 * value) - 1 : 2 * value)
-        end
-        index = numbers.pack("w*")
-        [index.bytesize].pack("V") + index + strings.join
-      end
-
-      def decode(bytes)
-        raise FormatError, "#{NAME} ends early" if bytes.bytesize < 4
+      # The badline version that saved the module, or an empty string when
+      # it is too damaged to say.
+      def written_by(section)
+        bytes = Zlib.inflate(section.data)
+        return "" if bytes.bytesize < 4
 
         length = bytes.byteslice(0, 4).unpack1("V").to_i
         numbers = bytes.byteslice(4, length).to_s.unpack("w*").map(&:to_i)
-        value_count = numbers.fetch(0, 0)
         string_count = numbers.fetch(1, 0)
-        raise FormatError, "#{NAME} ends early" if numbers.length != 2 + string_count + value_count
-
-        State.new(values(numbers, 2 + string_count), strings(bytes, 4 + length, numbers.slice(2, string_count)))
-      end
-
-      def values(numbers, from)
-        Array.new(numbers.length - from) do |i|
-          folded = numbers[from + i]
-          folded.odd? ? -((folded + 1) / 2) : folded / 2
-        end
-      end
-
-      def strings(bytes, pos, lengths)
-        lengths.map do |length|
-          raise FormatError, "#{NAME} ends early" if pos + length > bytes.bytesize
+        return "" if string_count < 2 || numbers.length < 4
 
-          bytes.byteslice(pos, length).to_s.tap { pos += length }
-        end
+        pos = 4 + length + numbers[2]
+        bytes.byteslice(pos, numbers[3]).to_s
+      rescue Zlib::Error
+        ""
       end
     end
   end

data/lib/badline/snapshot/plus4_setup.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    # How a 264 series machine was built: its model's name, one of
+    # Plus4::Model::ALL, which also says whether the Plus/4's function ROMs
+    # are fitted, its RAM in K, and whether a 1551's TCBM interface is
+    # plugged in, the arguments Plus4.new takes.
+    Plus4Setup = Data.define(:model, :ram_kb, :tcbm)
+
+    class Plus4Setup
+      MODELS = Plus4::Model::ALL.map(&:name).freeze
+
+      # The setup of `machine`.
+      def self.of(machine) = new(model: machine.model.name, ram_kb: machine.ram_kb, tcbm: !machine.tias.empty?)
+
+      # The model by name, the RAM and the TCBM interface, in a keyed
+      # snapshot module.
+      def write_fields(out)
+        out.text("model", model).int("ram_kb", ram_kb).bool("tcbm", tcbm)
+      end
+
+      def self.read_fields(input)
+        model = input.choice("model", MODELS, "plus4")
+        ram_kb = input.int("ram_kb", Plus4::Model.named(model).ram_kb)
+        unless Plus4::Model::RAM_SIZES.include?(ram_kb)
+          raise FormatError, "the snapshot is of a Plus/4 with #{ram_kb}K of RAM, which badline doesn't build"
+        end
+
+        new(model:, ram_kb:, tcbm: input.bool("tcbm", false))
+      end
+
+      # A machine built this way, at power-on.
+      def build = Plus4.new(model:, ram: ram_kb, tcbm:)
+
+      def to_s = "#{model} with #{ram_kb}K#{' and a TCBM interface' if tcbm}"
+    end
+  end
+end