badline 0.5.1 → 0.6.1

data/lib/badline/memory.rb

@@ -29,6 +29,14 @@ module Badline
       Array(bytes).each_with_index { |b, i| poke(addr + i, b) }
     end
 
+    def save_state(out)
+      out.blob(@storage)
+    end
+
+    def load_state(input)
+      input.blob_into(@storage)
+    end
+
     # Refills the whole memory as if newly built with `initial`
     def clear!(initial = [])
       @storage.replace(zero_fill(initial))

data/lib/badline/options/event.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Badline
+  class Options
+    # One event of --at or --script: what to do, with its argument, once
+    # `frame` frames have run. An event given at several frames becomes
+    # one Event per frame.
+    class Event
+      # The actions, and whether each takes an argument.
+      ACTIONS = {
+        "key" => true, "type" => true, "insert" => true, "eject" => true, "screenshot" => true,
+        "reset" => false, "freeze" => false, "quit" => false
+      }.freeze
+
+      # The frames a key or the freeze button is held for.
+      HOLD = 5
+
+      EJECTABLE = %w[disk tape cartridge].freeze
+
+      # What insert takes: disk images, tapes and cartridges, or a
+      # directory to mount as device 8.
+      INSERTABLE = %w[.d64 .d71 .d81 .g64 .t64 .tap .crt].freeze
+
+      attr_reader :frame, :action, :argument
+
+      def initialize(frame, action, argument)
+        @frame = frame
+        @action = action
+        @argument = argument
+      end
+
+      # The events of --at's value, or of --script's file.
+      def self.given(flag, value)
+        return script(value) if flag == "--script"
+
+        events = parse(value)
+        raise Error, "invalid argument: #{flag} #{value}" if events.empty?
+
+        events
+      end
+
+      # The events of a --script file, one a line in --at's form. Blank
+      # lines and lines starting with # are skipped.
+      def self.script(path)
+        raise Error, "no such file: #{path}" unless File.file?(path)
+
+        events = []
+        File.foreach(path) do |line|
+          text = line.strip
+          events.concat(given("--script #{path}:", text)) unless text.empty? || text.start_with?("#")
+        end
+        events
+      end
+
+      # The events of `FRAME[,FRAME...]:ACTION[=ARGUMENT]`, or an empty list
+      # when the text isn't one.
+      def self.parse(text)
+        colon = text.index(":")
+        numbers = colon.nil? ? [] : frames(text[0, colon])
+        return [] if numbers.empty?
+
+        event = text[colon + 1, text.size - colon - 1]
+        equals = event.index("=")
+        action = equals.nil? ? event : event[0, equals]
+        argument = equals.nil? ? "" : event[equals + 1, event.size - equals - 1]
+        return [] unless valid?(action, argument)
+
+        numbers.map { |frame| new(frame, action, argument) }
+      end
+
+      # The frame numbers of `FRAME[,FRAME...]`, or none unless each is a
+      # positive number.
+      def self.frames(text)
+        numbers = text.split(",")
+        return [] unless !numbers.empty? && numbers.all? { |number| number.match?(/\A\d+\z/) && number.to_i.positive? }
+
+        numbers.map(&:to_i)
+      end
+
+      def self.valid?(action, argument)
+        return false unless ACTIONS.key?(action)
+        return argument.empty? unless ACTIONS[action]
+        return EJECTABLE.include?(argument) if action == "eject"
+        return insertable?(argument) if action == "insert"
+
+        !argument.empty?
+      end
+
+      def self.insertable?(path)
+        File.directory?(path) || (File.exist?(path) && INSERTABLE.include?(File.extname(path).downcase))
+      end
+    end
+  end
+end

data/lib/badline/options/help.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Badline
+  class Options
+    # How fast the headless player runs, which the builds' help tells apart.
+    NATIVE_SPEED = <<~TEXT.chomp
+      Without the window, PSID tunes run on a bare CPU and SID, and RSID
+      tunes boot the whole machine. --filter-chunk 1 runs the filter
+      cycle by cycle, which is exact but slower.
+    TEXT
+
+    RUBY_SPEED = <<~TEXT.chomp
+      Without the window, PSID tunes run on a bare CPU and SID, faster than
+      real time. RSID tunes boot the whole machine and run at about half
+      real time, so they stutter when played. --filter-chunk 1 runs the
+      filter cycle by cycle, which is exact but takes about twice as long.
+    TEXT
+
+    # What --help prints: the usage, then the options this build takes,
+    # section by section, laid out as OptionParser did.
+    def help
+      lines = [banner]
+      SECTIONS.each do |section|
+        options = TABLE.select { |option| option.section == section && takes?(option) }
+        next if options.empty?
+
+        lines << "" if lines.size > 1
+        lines << "#{section}:"
+        options.each { |option| lines << "    #{option.usage.ljust(32)} #{describe(option)}" }
+      end
+      "#{lines.join("\n")}\n"
+    end
+
+    private
+
+    def describe(option) = @native && option.name == "--sound" ? "#{option.text} (default)" : option.text
+
+    def banner
+      <<~BANNER
+        Usage: #{@program} [options] [media]
+               #{@program} --headless [options] tune.sid
+               #{@program} [options] tune.sid --audio-out FILE
+
+        Media can be a .prg/.p00 program, a .d64/.d71/.d81 disk image, a
+        .g64 disk image for the true 1541, a .t64 tape archive, a .tap
+        tape, a .crt cartridge, a .sid tune, a .vsf snapshot, or a directory
+        to mount as device 8. It opens in the emulator window, where F11
+        saves a snapshot and F12 restores it. Device 8 answers through
+        traps on the KERNAL's disk routines, unless --true-drive puts an
+        emulated 1541 there, which runs its own DOS and reads .d64 and .g64
+        images only.
+
+        --headless plays a .sid tune on the host's audio device without the
+        window, and --audio-out renders it to 16-bit PCM instead. The
+        container follows the file's extension, .wav or .aiff. Played on a
+        terminal, n or → skips to the next song, p or ← to the previous one,
+        space pauses and q quits.
+
+        A .sid file carries no length of its own. Without --seconds the tune is
+        looked up by MD5 in HVSC's Songlengths.md5, taken from --songlengths, from
+        the DOCUMENTS directory of an HVSC collection above the tune, or from
+        $HVSC_BASE. Failing all of those it runs for #{FALLBACK_SECONDS.to_i} seconds.
+
+        #{@native ? NATIVE_SPEED : RUBY_SPEED}
+
+        --at and --script run events once a number of frames has run, as
+        in --at 3500:key=space or --at 250,500:screenshot=shot%05d.bmp.
+        key=NAME presses a C64 key (space, return, a, f1, run_stop, restore)
+        or a joystick's direction or fire (joy1-up, joy2-fire) for #{Event::HOLD}
+        frames. type=TEXT types it, with \\n for RETURN. insert=FILE swaps
+        in a disk, tape or cartridge, and eject=disk, tape or cartridge
+        takes one out. screenshot=FILE saves the frame as a .bmp, with the
+        frame's number in place of %d. reset, freeze and quit take no
+        argument.
+      BANNER
+    end
+  end
+end

data/lib/badline/options/option.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Badline
+  class Options
+    # One option of the table: its flags and value as the help shows them
+    # (`-s, --song N`), what it does, the help section it's listed in, the
+    # mode it needs (:window, :headless or :either), and the build that
+    # takes it (:native, :ruby or :both).
+    class Option
+      attr_reader :usage, :name, :short, :value, :text, :section, :needs, :build
+
+      def initialize(usage, text, section:, needs: :either, build: :both)
+        @usage = usage.start_with?("--") ? "    #{usage}" : usage
+        words = usage.split
+        @short = words.size > 1 && words[1].start_with?("--") ? words[0].delete_suffix(",") : ""
+        @name = @short.empty? ? words[0] : words[1]
+        @value = words.last.start_with?("-") ? "" : words.last
+        @text = text
+        @section = section
+        @needs = needs
+        @build = build
+      end
+
+      def valued? = !@value.empty?
+
+      def named?(flag) = flag == @name || (!@short.empty? && flag == @short)
+    end
+  end
+end

data/lib/badline/options/table.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Badline
+  class Options
+    DEFAULT_RATE = 44_100
+
+    SECTIONS = ["Options", "Window options", "Options without the window", "Testing options"].freeze
+
+    # Every option of both builds, in the order the help lists them.
+    TABLE = [
+      Option.new("-s, --song N", "Subtune of a .sid, from 1 (default: the tune's own)", section: "Options"),
+      Option.new("--sid MODEL", "SID to fit: 6581 or 8580 (default: a .sid tune's own, else 6581)",
+                 section: "Options"),
+      Option.new("--disable-jit", "Run without enabling YJIT", section: "Options", build: :ruby),
+      Option.new("-h, --help", "Show this help", section: "Options"),
+      Option.new("--version", "Show the version and what built it", section: "Options", build: :native),
+      Option.new("--no-autostart", "Boot to READY. instead of running the program",
+                 section: "Window options", needs: :window),
+      Option.new("--read-only", "Mount a disk image write-protected, leaving its file unchanged",
+                 section: "Window options", needs: :window),
+      Option.new("--sound", "Play the SID through the host's audio device (F10 mutes)",
+                 section: "Window options", needs: :window),
+      Option.new("--no-sound", "Don't play the SID", section: "Window options", needs: :window, build: :native),
+      Option.new("--true-drive", "Put a true 1541 on device 8 instead of the KERNAL traps",
+                 section: "Window options", needs: :window),
+      Option.new("--reu SIZE", "Plug in an REU of SIZE K: 128, 256, 512 (a 1750) or up to 16384",
+                 section: "Window options", needs: :window),
+      Option.new("--ntsc", "Run an NTSC C64, with the 6567R8 VIC-II, instead of a PAL one",
+                 section: "Window options", needs: :window),
+      Option.new("--no-vsync", "Pace frames by the timer or the sound instead of the display",
+                 section: "Window options", needs: :window),
+      Option.new("--verbose", "Print the display, sound and gamepad setup and the frame timing",
+                 section: "Window options", needs: :window),
+      Option.new("--headless", "Play a .sid tune in the terminal instead of the window",
+                 section: "Options without the window"),
+      Option.new("--audio-out FILE", "Render a .sid tune to a .wav or .aiff file",
+                 section: "Options without the window"),
+      Option.new("--seconds N", "Length to play (default: the tune's own)",
+                 section: "Options without the window", needs: :headless),
+      Option.new("--songlengths PATH", "HVSC Songlengths.md5 to take the length from",
+                 section: "Options without the window", needs: :headless),
+      Option.new("--rate HZ", "Sample rate (default: #{DEFAULT_RATE}, or the audio device's own)",
+                 section: "Options without the window", needs: :headless),
+      Option.new("--filter-chunk N", "Filter step in cycles, 1 is exact (default: 4)",
+                 section: "Options without the window", needs: :headless),
+      Option.new("--quiet", "Don't report progress", section: "Options without the window", needs: :headless),
+      Option.new("--no-tui", "Play without the interactive display, even on a terminal",
+                 section: "Options without the window", needs: :headless),
+      Option.new("--frames N", "Quit after N frames", section: "Testing options", needs: :window),
+      Option.new("--unpaced", "Run as fast as it can, without vsync or pacing",
+                 section: "Testing options", needs: :window),
+      Option.new("--screenshot FILE", "Save the last frame as a .bmp",
+                 section: "Testing options", needs: :window),
+      Option.new("--save-snapshot FILE", "Save the machine as a .vsf snapshot after the last frame",
+                 section: "Testing options", needs: :window),
+      Option.new("--at FRAME:EVENT", "Run EVENT once FRAME frames have run (see above)",
+                 section: "Testing options", needs: :window),
+      Option.new("--script FILE", "Run the events in FILE, one FRAME:EVENT a line",
+                 section: "Testing options", needs: :window)
+    ].freeze
+  end
+end