badline 0.12.1 → 0.14.0

data/lib/badline/roms/README

@@ -20,7 +20,7 @@ The character generator ROM.
 kernal-sx64.rom
 ---------------
 The SX-64's KERNAL, 251104-04. It boots with the SX-64's banner and
-colours, and loads from device 8 rather than tape. Computer.new(kernal:
+colours, and loads from device 8 rather than tape. C64.new(kernal:
 :sx64) fits it, as --model sx64 does.
 
 Downloaded from
@@ -32,7 +32,7 @@ kernal-pet64.rom
 The KERNAL of the PET 64, 4064 and Educator 64, 901246-01. It boots
 with the "**** COMMODORE 4064  BASIC V2.0 ****" banner and a white
 cursor, and its interrupt routine keeps the border, background and
-sprite colours black unless bit 7 of $0286 is set. Computer.new(kernal:
+sprite colours black unless bit 7 of $0286 is set. C64.new(kernal:
 :pet64) fits it, as --model pet64 does.
 
 Downloaded from
@@ -45,7 +45,7 @@ The C64GS's BASIC and KERNAL, 390852-01, 16 KB: BASIC for $A000-$BFFF
 followed by the KERNAL for $E000-$FFFF. Its BASIC is 901226-01's but
 for 30 unused bytes. Its KERNAL is 901227-03's with most changes in
 $F72C-$FC92, the cassette routines' place, and many jumps redirected to
-I/O error 5. Computer.new(kernal: :gs) fits both, as --model c64gs does.
+I/O error 5. C64.new(kernal: :gs) fits both, as --model c64gs does.
 
 Downloaded from
 https://www.zimmers.net/anonftp/pub/cbm/firmware/computers/c64/64gs.390852-01.bin
@@ -54,7 +54,7 @@ MD5 049e657afafbdd802e8c6a4f88f3d730.
 dos1541.rom
 -----------
 The 1541 disk drive's DOS 2.6, 16 KB for $C000-$FFFF: 325302-01
-($C000-$DFFF) followed by 901229-05 ($E000-$FFFF). Drive1541 loads it.
+($C000-$DFFF) followed by 901229-05 ($E000-$FFFF). Drives::Model1541 loads it.
 
 Both halves downloaded from
 https://www.zimmers.net/anonftp/pub/cbm/firmware/drives/new/1541/
@@ -64,7 +64,7 @@ SHA-1 ab16f56989b27d89babe5f89c5a8cb3da71a82f0.
 dos1571.rom
 -----------
 The 1571 disk drive's DOS 3.0, 310654-05, 32 KB for $8000-$FFFF.
-Drive1571 loads it.
+Drives::Model1571 loads it.
 
 Downloaded from
 https://www.zimmers.net/anonftp/pub/cbm/firmware/drives/new/1571/1571-rom.310654-05.bin
@@ -73,7 +73,7 @@ SHA-1 f1be619c106641a685f6609e4d43d6fc9eac1e70.
 dos1581.rom
 -----------
 The 1581 disk drive's DOS, 318045-02, 32 KB for $8000-$FFFF.
-Drive1581 loads it.
+Drives::Model1581 loads it.
 
 Downloaded from
 https://www.zimmers.net/anonftp/pub/cbm/firmware/drives/new/1581/1581-rom.318045-02.bin
@@ -132,3 +132,41 @@ c128/character.rom
 The character generator ROM, 390059-01 (characters.390059-01.bin),
 8 KB: the C64's set, the same as character.rom, followed by the C128's.
 SHA-1 29ed066d513f2d5c09ff26d9166ba23c2afb2b3f.
+
+Commodore 264 series ROMs
+=========================
+
+Downloaded from
+https://www.zimmers.net/anonftp/pub/cbm/firmware/computers/plus4/
+for the Plus/4, the C16 and the C116, which share BASIC and the KERNAL.
+Nothing maps them yet.
+
+plus4/basic.rom
+---------------
+BASIC 3.5, 318006-01 (basic.318006-01.bin), for $8000-$BFFF in ROM
+bank 0.
+SHA-1 161c96b4ad20f3a4f2321808e37a5ded26a135dd.
+
+plus4/kernal-pal.rom
+--------------------
+The PAL KERNAL, 318004-05 (kernal.318004-05.bin), for $C000-$FFFF in
+ROM bank 0, with the character set from $D000.
+SHA-1 7c7e07f016391174a557e790c4ef1cbe33512cdb.
+
+plus4/kernal-ntsc.rom
+---------------------
+The NTSC KERNAL, 318005-05 (kernal.318005-05.bin), for $C000-$FFFF in
+ROM bank 0.
+SHA-1 a3d9e5be091b98de39a046ab167fb7632d053682.
+
+plus4/function-low.rom
+----------------------
+The Plus/4's 3-plus-1 function ROM, low half, 317053-01
+(3-plus-1.317053-01.bin), for $8000-$BFFF in ROM bank 1.
+SHA-1 3b69f6e7cb4c18bb08e203fb18b7dabfa853390f.
+
+plus4/function-high.rom
+-----------------------
+The Plus/4's 3-plus-1 function ROM, high half, 317054-01
+(3-plus-1.317054-01.bin), for $C000-$FFFF in ROM bank 1.
+SHA-1 0ad7ac2db7da692d972e586ca0dfd747d82c7693.

data/lib/badline/sdl.rb

@@ -58,6 +58,7 @@ module Badline
     ffi_func :SDL_ClearQueuedAudio, [:uint32], :void
     ffi_func :SDL_PushEvent, [:ptr], :int
     ffi_func :SDL_GetKeyName, [:int], :str
+    ffi_func :SDL_StopTextInput, [], :void
 
     ffi_buffer :rect, 16
     ffi_write_i32 :rect_x, 0

data/lib/badline/{storage/sid_file.rb → sid_tune/file.rb}

@@ -3,10 +3,10 @@
 require "digest"
 
 module Badline
-  module Storage
+  module SIDTune
     # PSID/RSID tunes: a memory image plus the addresses of the routines
     # that initialise it and produce one frame of music.
-    class SIDFile
+    class File
       include IntegerHelper
 
       class FormatError < StandardError; end
@@ -147,7 +147,7 @@ module Badline
       attr_reader :format
 
       def initialize(path)
-        @bytes = File.binread(path).bytes
+        @bytes = ::File.binread(path).bytes
         @format = @bytes[0, 4].pack("C*")
         raise FormatError, "Missing PSID or RSID signature" unless %w[PSID RSID].include?(@format)
         raise FormatError, "Truncated header" if truncated?

data/lib/badline/{storage → sid_tune}/hvsc.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Badline
-  module Storage
+  module SIDTune
     # The layout of an HVSC collection: tunes in directories under its root,
     # and databases about them in `DOCUMENTS`. A tune's HVSC path is its path
     # from the root, as `/MUSICIANS/H/Hubbard_Rob/Commando.sid`.
@@ -10,15 +10,15 @@ module Badline
         # The named file in the DOCUMENTS directory of a collection above the
         # tune, or else of the one `$HVSC_BASE` points at.
         def document(tune_path, name)
-          candidates(tune_path).map { |dir| File.join(dir, "DOCUMENTS", name) }
-                               .find { |path| File.file?(path) }
+          candidates(tune_path).map { |dir| ::File.join(dir, "DOCUMENTS", name) }
+                               .find { |path| ::File.file?(path) }
         end
 
         # The tune's HVSC path in the collection that holds the document, or
         # nil when the tune lies outside it.
         def path(tune_path, document)
-          root = File.dirname(File.expand_path(document), 2)
-          tune = File.expand_path(tune_path)
+          root = ::File.dirname(::File.expand_path(document), 2)
+          tune = ::File.expand_path(tune_path)
           tune.start_with?("#{root}/") ? tune[root.length..] : nil
         end
 
@@ -26,10 +26,10 @@ module Badline
 
         def candidates(tune_path)
           dirs = []
-          dir = File.dirname(File.expand_path(tune_path))
+          dir = ::File.dirname(::File.expand_path(tune_path))
           until dirs.last == dir
             dirs << dir
-            dir = File.dirname(dir)
+            dir = ::File.dirname(dir)
           end
           base = ENV.fetch("HVSC_BASE", nil)
           dirs << base if base

data/lib/badline/{storage → sid_tune}/song_lengths.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Badline
-  module Storage
+  module SIDTune
     # HVSC's subtune length database. Each tune gets a comment naming its path
     # and a line keyed by the MD5 of the whole `.sid` file, holding one
     # `m:ss` time per subtune, optionally down to milliseconds:
@@ -23,7 +23,7 @@ module Badline
       # The tune's per-subtune lengths in seconds, or nil when it isn't listed.
       def lengths(md5)
         prefix = "#{md5.downcase}="
-        File.foreach(@path) do |line|
+        ::File.foreach(@path) do |line|
           next unless line.start_with?(prefix)
 
           return line[prefix.length..].split.map { |time| seconds(time) }

data/lib/badline/{storage → sid_tune}/stil/credit.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Badline
-  module Storage
+  module SIDTune
     class STIL
       # A TITLE in a STIL entry, the tune a subtune covers, with the ARTIST
       # after it, and the stretch of the subtune it covers when the title

data/lib/badline/{storage → sid_tune}/stil.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require "badline/storage/stil/credit"
+require "badline/sid_tune/stil/credit"
 
 module Badline
-  module Storage
+  module SIDTune
     # HVSC's SID Tune Information List, `DOCUMENTS/STIL.txt`: covers,
     # subtune names and composers' comments, keyed by each tune's HVSC path.
     # An entry holds fields for the whole file, then a block per subtune
@@ -89,7 +89,7 @@ module Badline
       def entry(hvsc_path) = entries[hvsc_path]
 
       def entries
-        @entries ||= parse(Storage.latin1(File.binread(@path).bytes))
+        @entries ||= parse(Storage.latin1(::File.binread(@path).bytes))
       end
 
       private

data/lib/badline/sid_tune.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "badline/sid_tune/file"
+require "badline/sid_tune/hvsc"
+require "badline/sid_tune/song_lengths"
+require "badline/sid_tune/stil"

data/lib/badline/snapshot/c128_setup.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    # How a C128 was built: its model's name, its SID's model and the
+    # mode it resets into, the arguments C128.new takes.
+    C128Setup = Data.define(:model, :sid_model, :mode)
+
+    class C128Setup
+      SID_MODELS = %i[mos6581 mos8580].freeze
+      MODES = %i[c64 c128].freeze
+
+      # The model, the SID and the mode by name, in a keyed snapshot module.
+      def write_fields(out)
+        out.text("model", model).text("sid_model", sid_model.to_s).text("mode", mode.to_s)
+      end
+
+      def self.read_fields(input)
+        model = input.choice("model", C128::Model::ALL.map(&:name), "c128")
+        sid = input.choice("sid_model", SID_MODELS.map(&:to_s), "mos6581")
+        mode = input.choice("mode", MODES.map(&:to_s), "c64")
+        new(model:, sid_model: SID_MODELS.find { |name| name.to_s == sid } || :mos6581,
+            mode: MODES.find { |name| name.to_s == mode } || :c64)
+      end
+
+      # A machine built this way, at power-on.
+      def build = C128.new(model:, sid_model:, mode:)
+
+      def to_s = [model, sid_model, mode].join(" with a ")
+    end
+  end
+end

data/lib/badline/snapshot/c64_setup.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    # How a C64 was built: its VIC, CIA and SID models, its region, its
+    # RAM expansion, the size of its REU, its KERNAL, whether it has a
+    # datasette and its board, the arguments C64.new takes.
+    C64Setup = Data.define(:vic_model, :cia_model, :sid_model, :region, :ram_expansion, :reu, :kernal, :datasette,
+                           :board)
+
+    class C64Setup
+      SID_MODELS = %i[mos6581 mos8580].freeze
+      REGIONS = [Region::PAL, Region::NTSC, Region::NTSC_OLD, Region::DREAN].freeze
+      RAM_EXPANSIONS = [:none, *C64::BankedRAM::TYPES.keys].freeze
+      KERNALS = C64::Bus::ROMs::KERNALS.keys.freeze
+      BOARDS = C64::Bus::Fittings::BOARDS
+
+      def self.of(address_bus)
+        new(vic_model: address_bus.vic.model, cia_model: address_bus.cia1.model, sid_model: address_bus.sid.model,
+            region: address_bus.region, ram_expansion: address_bus.ram_expansion.type, reu: address_bus.reu&.size_kb,
+            kernal: address_bus.kernal, datasette: address_bus.datasette.connected?, board: address_bus.board)
+      end
+
+      def self.ram_expansion(name) = name == :none ? nil : name
+
+      # An REU's size in K, written as 0 for none.
+      def self.reu(size_kb)
+        return nil if size_kb.zero?
+        return size_kb if C64::REU::SIZES_KB.include?(size_kb)
+
+        raise FormatError, "the snapshot names a #{size_kb}K REU, which badline doesn't build"
+      end
+
+      # The setup in a keyed snapshot module (Snapshot::Keyed), with each
+      # model, the region, the RAM expansion, the KERNAL and the board by
+      # name.
+      def write_fields(out)
+        out.text("vic_model", vic_model.to_s).text("cia_model", cia_model.to_s).text("sid_model", sid_model.to_s)
+        out.text("region", region.name.to_s).text("ram_expansion", (ram_expansion || :none).to_s)
+        out.int("reu_kb", reu || 0).text("kernal", kernal.to_s).bool("datasette", datasette)
+        out.text("board", board.to_s)
+      end
+
+      # The setup a keyed snapshot module names, a C64's at power-on for
+      # anything it leaves out or names that badline doesn't build.
+      def self.read_fields(input)
+        region = named(input, "region", REGIONS.map(&:name), :pal)
+        new(vic_model: named(input, "vic_model", Chips::VIC::MODELS, :mos6569),
+            cia_model: named(input, "cia_model", Chips::CIA::MODELS, :mos6526),
+            sid_model: named(input, "sid_model", SID_MODELS, :mos6581),
+            region: REGIONS.find { |each| each.name == region } || Region::PAL,
+            ram_expansion: ram_expansion(named(input, "ram_expansion", RAM_EXPANSIONS, :none)),
+            reu: reu(input.int("reu_kb", 0)), kernal: named(input, "kernal", KERNALS, :c64),
+            datasette: input.bool("datasette", true), board: named(input, "board", BOARDS, :c64))
+      end
+
+      # The Symbol of `names` the text at `key` names.
+      def self.named(input, key, names, default)
+        text = input.choice(key, names.map(&:to_s), default.to_s)
+        names.find { |name| name.to_s == text } || default
+      end
+
+      # A machine built this way, at power-on.
+      def build
+        C64.new(vic_model:, cia_model:, sid_model:, region:, ram_expansion:, reu:, kernal:, datasette:, board:)
+      end
+
+      # The chips, led by the model's name when they make one of
+      # Badline::Model's.
+      def to_s
+        model = Model.of(self)
+        parts = [vic_model, cia_model, sid_model, region.name]
+        parts.unshift(model.name) if model
+        parts << ram_expansion if ram_expansion
+        parts << "a #{reu}K REU" if reu
+        parts << "the #{kernal} KERNAL" unless kernal == :c64
+        parts << "no datasette" unless datasette
+        parts << "the #{board} board" unless board == :c64
+        parts.join(", ")
+      end
+    end
+  end
+end

data/lib/badline/snapshot/container.rb

@@ -4,6 +4,10 @@ require "zlib"
 
 module Badline
   module Snapshot
+    # A file that isn't a snapshot badline reads, is cut short, or is of a
+    # machine built another way.
+    class FormatError < StandardError; end
+
     # One module of a snapshot: its name, its version and its payload,
     # without the 22-byte module header.
     Section = Data.define(:name, :major, :minor, :data) do

data/lib/badline/snapshot/field_doc/markdown.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module FieldDoc
+      # The doc's markdown: one table per module, of each key, its type and
+      # its default, with keys that differ only in a unit's number, such as
+      # voice1 to voice3, on one row.
+      class Markdown
+        NAMES = { "c64" => "C64", "vic20" => "VIC-20", "c128" => "C128" }.freeze
+        TAG_TYPES = { Keyed::INT => "int", Keyed::BOOL => "bool", Keyed::BYTES => "bytes", Keyed::INTS => "ints",
+                      Keyed::TEXT => "text" }.freeze
+
+        # A row: the key, the type, and the defaults each family whose
+        # machines read or write it reads it with.
+        Row = Struct.new(:key, :type, :defaults)
+
+        INTRO = <<~MARKDOWN
+          # Snapshot format
+
+          This file is generated by `rake snapshot:fields` from the code that
+          loads a snapshot. Don't edit it by hand. doc/snapshots.md covers
+          what a snapshot holds and which versions load.
+
+          A snapshot is a VICE `.vsf` container. The machine is in modules
+          named `BL-` plus a unit, each a deflated list of records: a key, a
+          type and a value. The types are `int` (a zigzag BER integer), `bool`,
+          `bytes`, `ints` (a list of integers) and `text`. A load skips a key
+          it doesn't know, and a key that isn't there leaves the value a
+          machine built afresh has: the default below. `word`, `byte` and
+          `int & 0x..` are ints cut to the latch's width. A text that lists
+          its values takes one of them. An optional int is absent when the
+          latch holds nothing. A true drive's modules are named from its
+          device number, `BL-D8` to `BL-D11`. Keys with `<N>` stand for each
+          numbered unit. A default of "written only" is a key the load
+          doesn't read, or reads only when the snapshot has it. Where the
+          machines differ, the default is given for each, and a key only
+          some of them have names them.
+        MARKDOWN
+
+        def initialize(loads)
+          @modules = {}
+          loads.each { |load| add(load) }
+        end
+
+        def to_s
+          sections = @modules.map do |name, rows|
+            families = rows.values.flat_map { |row| row.defaults.keys }.uniq
+            ["## #{name}", "", "Written by the #{families.map { |family| NAMES.fetch(family) }.join(', ')}.", "",
+             "| Key | Type | Default |", "| --- | --- | --- |",
+             *rows.values.map { |row| line(row, families) }].join("\n")
+          end
+          "#{INTRO}\n#{sections.join("\n\n")}\n"
+        end
+
+        private
+
+        def add(load)
+          load.fields.each do |name, fields|
+            numbered = numbered_keys(load.written[name].keys + fields.map(&:key))
+            fields.each { |field| note(name, numbered.fetch(field.key, field.key), field.type, load.family, field) }
+            read = fields.to_set(&:key)
+            load.written[name].each do |key, tag|
+              next if read.include?(key)
+
+              note(name, numbered.fetch(key, key), TAG_TYPES.fetch(tag, "?"), load.family, nil)
+            end
+          end
+        end
+
+        def note(name, key, type, family, field)
+          row = (@modules[name] ||= {})[key] ||= Row.new(key, type, {})
+          (row.defaults[family] ||= []) << (field ? brief(field.default, field.type) : "written only")
+        end
+
+        # Keys that differ only in a number, as the same key with <N>: each
+        # key whose number another key in the module shares the rest of.
+        def numbered_keys(keys)
+          groups = keys.uniq.group_by { |key| key.gsub(/(?<=[a-z])\d+(?=\.|\z)/, "<N>") }
+          groups.each_with_object({}) do |(general, members), numbered|
+            members.each { |key| numbered[key] = general } if members.length > 1
+          end
+        end
+
+        def line(row, families)
+          each = row.defaults.transform_values { |defaults| summary(defaults.uniq) }
+          default = if each.values.uniq.length == 1 && each.length == families.length then each.values.first
+                    else each.map { |family, value| "#{NAMES.fetch(family)}: #{value}" }.join("; ")
+                    end
+          "| `#{row.key}` | #{row.type} | #{default} |"
+        end
+
+        def summary(defaults) = defaults.length > 3 ? "varies" : defaults.join(" or ")
+
+        def brief(value, type)
+          case value
+          when nil then "absent"
+          when Array then list(value)
+          when String then type.start_with?("bytes") ? list(value.bytes) : value.inspect
+          else value.to_s
+          end
+        end
+
+        def list(values)
+          return values.inspect if values.length <= 8
+
+          values.uniq.length == 1 ? "#{values.length} × #{values.first}" : "#{values.length} values"
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/field_doc.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "badline"
+require "badline/c128"
+
+module Badline
+  module Snapshot
+    # doc/snapshot-format.md, written by running the code: each family's
+    # machine is saved with its attachments, and its modules loaded into a
+    # machine built the same way at power-on through Keyed::Recorders,
+    # which note every key read with its type and the value the new machine
+    # had, its default. `rake snapshot:fields` writes it, and a spec checks
+    # that the file matches.
+    module FieldDoc
+      PATH = File.expand_path("../../../doc/snapshot-format.md", __dir__)
+
+      # Modules read through Recorders.
+      class RecordingModules < Keyed::Modules
+        private
+
+        def parse(section) = Keyed::Recorder.parse(section)
+
+        def missing(name) = Keyed::Recorder.missing(name)
+      end
+
+      # One machine saved and loaded: the family it belongs to, and for
+      # each module the keys its records hold, with their tags, and the fields the load read.
+      Load = Data.define(:family, :written, :fields)
+
+      # The machines the doc is made from: each family at power-on, and the
+      # C64 with each kind of expansion, cartridge and media.
+      def self.machines
+        {
+          "c64" => [C64.new, C64.new(ram_expansion: :plus256k), C64.new(reu: 512), with_cartridge, with_trap_dos,
+                    with_tape, with_drive(:d64), with_drive(:d81)],
+          "vic20" => [Vic20.new, with_rom],
+          "c128" => [C128.new(mode: :c128), with_drive(:d71)]
+        }
+      end
+
+      def self.blank(length) = Array.new(length, 0)
+
+      def self.with_cartridge
+        chips = [0x8000, 0xa000].map do |address|
+          Storage::CRTFile::Chip.new(chip_type: 2, bank: 0, address:, data: blank(0x2000))
+        end
+        image = Storage::CRTFile::Image.new(hardware_type: 32, subtype: 0, exrom: 1, game: 0, name: "DOC", chips:)
+        C64.new.tap do |machine|
+          machine.attach_cartridge(C64::Cartridge.from_crt(Storage::CRTFile.new(bytes: Storage::CRTFile.encode(image))))
+        end
+      end
+
+      def self.with_trap_dos
+        C64.new.tap { |machine| machine.mount(Storage::D64Image.new("", read_only: true, bytes: blank(174_848))) }
+      end
+
+      def self.with_tape
+        bytes = "C64-TAPE-RAW".bytes + [1, 0, 0, 0, 4, 0, 0, 0, 0x30, 0x30, 0x30, 0x30]
+        C64.new.tap { |machine| machine.datasette.insert(Storage::TAP.new("", bytes:)) }
+      end
+
+      def self.with_drive(kind)
+        case kind
+        when :d81
+          C64.new.tap do |machine|
+            machine.plug_drive1581.insert(Drives::Model1581::Disk.new(Storage::D81Image.new("", bytes: blank(819_200))))
+          end
+        when :d71
+          C128.new(mode: :c128).tap do |machine|
+            image = Storage::D71Image.new("", bytes: blank(349_696))
+            machine.plug_true_drive.insert(Drives::Model1541::Disk.decode(image))
+          end
+        else
+          C64.new.tap do |machine|
+            image = Storage::D64Image.new("", bytes: blank(174_848))
+            machine.plug_true_drive.insert(Drives::Model1541::Disk.decode(image))
+          end
+        end
+      end
+
+      def self.with_rom
+        Vic20.new.tap { |machine| machine.bus.map_rom(0xa000, blank(0x2000)) }
+      end
+
+      # Saves `machine` and loads it into a new one through Recorders.
+      def self.load(family, machine)
+        modules = RecordingModules.new(Image.of(machine).sections)
+        Image.setup(modules.machine).build.load_modules(modules)
+        modules.machine.text("written_by", "")
+        written = {}
+        fields = {}
+        modules.readers.each do |reader|
+          written[reader.name] = reader.tags
+          fields[reader.name] = reader.fields
+        end
+        Load.new(family:, written:, fields:)
+      end
+
+      def self.loads = machines.flat_map { |family, list| list.map { |machine| load(family, machine) } }
+
+      # The doc, as markdown.
+      def self.markdown(loads = self.loads) = Markdown.new(loads).to_s
+
+      def self.write(path = PATH) = File.write(path, markdown)
+    end
+  end
+end
+
+require "badline/snapshot/field_doc/markdown"