badline 0.6.0 → 0.7.0

data/lib/badline/media/queue.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Badline
+  module Media
+    # An ordered list of media files to go through one at a time, such as
+    # the tunes of a player. Each entry is a file and the part of it to
+    # start on, counting from 1, out of the parts the file holds: a .sid
+    # tune's subtunes, say, or 1 of 1 for media with no parts.
+    #
+    # #next_entry and #previous_entry step through the entries, and
+    # #next_part and #previous_part through the current entry's parts,
+    # stopping at its ends. Each returns the entry it moved to, or nil
+    # where it stays put. With #loop? the entry steps wrap around at
+    # either end, and with #shuffle? they follow a shuffled order that
+    # starts from the current entry. #all_parts? decides where #advance
+    # goes once a part has played out: on through the entry's parts, or
+    # to the next entry. An entry stepped to starts on its first part
+    # with #all_parts?, otherwise on its own.
+    #
+    # `shuffle`, if given, returns the entry indices it's given in a new
+    # order in place of Array#shuffle. `build`, if given, turns the paths
+    # #add is given into entries.
+    class Queue
+      # A file and the part of it to start on.
+      class Entry
+        attr_reader :path, :part, :parts
+
+        def initialize(path, part: 1, parts: 1)
+          @path = path
+          @part = part
+          @parts = parts
+        end
+      end
+
+      attr_reader :part
+
+      # The files `paths` name, in order: a file as given, and a directory
+      # as every file below it with the extension, in path order.
+      def self.files(paths, extension)
+        paths.flat_map { |path| File.directory?(path) ? below(path, extension).sort : [path] }
+      end
+
+      def self.below(directory, extension)
+        paths = []
+        Dir.children(directory).each do |name|
+          path = File.join(directory, name)
+          if File.directory?(path)
+            paths.concat(below(path, extension))
+          elsif File.extname(name).casecmp?(extension)
+            paths << path
+          end
+        end
+        paths
+      end
+      private_class_method :below
+
+      def initialize(entries, all_parts: false, shuffle: nil, build: nil)
+        @entries = entries
+        @shuffler = shuffle
+        @builder = build
+        @order = (0...entries.size).to_a
+        @position = 0
+        @part = entries.empty? ? 0 : entries.first.part
+        @all_parts = all_parts
+        @shuffle = false
+        @loop = false
+      end
+
+      def size = @entries.size
+
+      def empty? = @entries.empty?
+
+      # Where the current entry stands in the order played, from 1.
+      def position = empty? ? 0 : @position + 1
+
+      def entry = empty? ? nil : @entries[@order[@position]]
+
+      def all_parts? = @all_parts
+
+      def shuffle? = @shuffle
+
+      def loop? = @loop
+
+      # Puts the entries `build` makes of the paths at the end of the order,
+      # shuffled or not. An empty queue starts on the first of them.
+      def add(paths)
+        return if @builder.nil?
+
+        started = empty?
+        first = @entries.size
+        @entries.concat(@builder.call(paths))
+        @order.concat((first...@entries.size).to_a)
+        @part = entry.part if started && !empty?
+      end
+
+      def toggle_all_parts = @all_parts = !@all_parts
+
+      def toggle_loop = @loop = !@loop
+
+      def toggle_shuffle
+        return @shuffle = !@shuffle if empty?
+
+        current = @order[@position]
+        @shuffle = !@shuffle
+        @order = (0...size).to_a
+        @order = [current] + shuffled(@order - [current]) if @shuffle
+        @position = @order.index(current)
+        @shuffle
+      end
+
+      def next_entry
+        return if empty?
+
+        move(@position + 1)
+      end
+
+      def previous_entry
+        return if empty?
+
+        move(@position - 1)
+      end
+
+      def next_part
+        return if empty? || @part >= entry.parts
+
+        @part += 1
+        entry
+      end
+
+      def previous_part
+        return if empty? || @part <= 1
+
+        @part -= 1
+        entry
+      end
+
+      # Where to go once the current part has played to its end: the
+      # entry's next part with #all_parts?, otherwise the next entry.
+      def advance
+        return next_part if @all_parts && !empty? && @part < entry.parts
+
+        next_entry
+      end
+
+      private
+
+      def move(position)
+        return unless position.between?(0, size - 1) || @loop
+
+        @position = position % size
+        @part = @all_parts ? 1 : entry.part
+        entry
+      end
+
+      def shuffled(indices) = @shuffler ? @shuffler.call(indices) : indices.shuffle
+    end
+  end
+end

data/lib/badline/media.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "badline/media/true_drive"
+require "badline/media/queue"
 
 module Badline
   module Media
@@ -25,7 +26,7 @@ module Badline
       # A .g64 plugs in a true drive as device 8 (TrueDrive), and with one
       # there, a .d64 goes into it instead of the KERNAL traps too. The
       # autostart then loads through it.
-      def attach(computer, path, autostart: true, song: nil, **options)
+      def attach(computer, path, autostart: true, subtune: nil, **options)
         if TrueDrive.takes?(computer, path)
           attach_true_drive(computer, path, options.fetch(:disk, {}), autostart:)
         elsif File.directory?(path)
@@ -34,7 +35,7 @@ module Badline
         elsif File.extname(path).downcase == ".crt"
           attach_cartridge(computer, path, options.fetch(:cartridge, {}))
         elsif File.extname(path).downcase == ".sid"
-          attach_sid(computer, path, autostart:, song:)
+          attach_sid(computer, path, autostart:, subtune:)
         elsif File.extname(path).downcase == ".tap"
           attach_tape(computer, path, autostart:)
         elsif MOUNT_TYPES.key?(File.extname(path).downcase)
@@ -91,18 +92,22 @@ module Badline
         "Attached cartridge #{path}"
       end
 
-      def attach_sid(computer, path, autostart:, song:)
+      def attach_sid(computer, path, autostart:, subtune:)
         tune = Storage::SIDFile.new(path)
-        song = (song || tune.start_song).clamp(1, tune.songs)
-        computer.on_init { start_tune(computer, tune, autostart:, song:) }
+        if tune.sids > 1
+          raise Storage::SIDFile::FormatError, "Written for #{tune.sids} SIDs, which only the SID player plays"
+        end
+
+        subtune = (subtune || tune.start_subtune).clamp(1, tune.subtunes)
+        computer.on_init { start_tune(computer, tune, autostart:, subtune:) }
         title = tune.name.empty? ? path : tune.name
-        title += " (song #{song})" if tune.songs > 1
+        title += " (subtune #{subtune})" if tune.subtunes > 1
         autostart ? "Playing #{title}" : "Loaded #{title}"
       end
 
-      def start_tune(computer, tune, autostart:, song:)
+      def start_tune(computer, tune, autostart:, subtune:)
         computer.ram.write(tune.load_address, tune.data)
-        tune.boot_memory(song:).each { |address, bytes| computer.ram.write(address, bytes) }
+        tune.boot_memory(subtune:).each { |address, bytes| computer.ram.write(address, bytes) }
         computer.type_text(tune.boot_command) if autostart
       end
 

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,107 @@
+# 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 = [@sid_command ? sid_banner : 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
+               #{@program} sid [options] FILE|DIR...
+
+        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. A .sid tune opens in the SID player, as `sid` plays it,
+        unless an option of the emulator's window asks for the machine.
+
+        --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, → and ← step between the tune's subtunes, n and p between
+        tunes, , and . seek, space pauses and q quits. s shuffles the tunes,
+        l loops them, and a, or --all-subtunes, plays on through each tune's
+        subtunes instead of just the one. `#{@program} sid` plays many tunes, and whole
+        directories of them, the same way.
+
+        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, or
+        until it has been silent for #{SILENCE_SECONDS.to_i}.
+
+        #{@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
+
+    def sid_banner
+      <<~BANNER
+        Usage: #{@program} sid [options] FILE|DIR...
+
+        Plays .sid tunes in the SID player's window, or in the terminal with
+        --headless, one after another in the order given. A directory adds
+        every .sid tune below it, in path order. → and ← step between a
+        tune's subtunes, n and p between tunes, , and . seek 10 seconds back
+        and forward, space pauses and q quits. s shuffles the tunes, l loops
+        them, and a, or --all-subtunes, plays on through each tune's subtunes
+        instead of just the one. The window has buttons for all of these,
+        and for switching the SID between the tune's own, the 6581 and the
+        8580. --subtune picks the first tune's subtune, and each tune after
+        it starts on its own. Without tunes, the window opens with an empty
+        queue, and .sid files or folders dropped on the window join it.
+
+        Each tune gets the SID its header names unless --sid says otherwise,
+        and its length from HVSC's Songlengths.md5 as #{@program} --help
+        describes. A tune written for 2 or 3 SIDs plays on the one badline
+        emulates, with a notice.
+      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, --subtune 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,64 @@
+# 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, --subtune N", "Subtune of a .sid, from 1 (default: the tune's own)", section: "Options"),
+      Option.new("--sid MODEL", "SID to fit: auto, 6581 or 8580 (default: auto, 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("--all-subtunes", "Play on through each tune's subtunes, not just the one",
+                 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

data/lib/badline/options/validation.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Badline
+  class Options
+    # The checks Options#parse makes once every argument has been read:
+    # the options fit the mode, the numbers are positive and the files
+    # exist.
+    module Validation
+      private
+
+      def validate
+        validate_mode
+        validate_numbers
+        validate_paths
+      end
+
+      def validate_mode
+        if headless?
+          raise Error, "#{@window_only.first} needs the window" unless @window_only.empty?
+          raise Error, "no tune given" if tune_paths.empty? && !player_window?
+
+          tune_paths.each { |path| validate_tune(path) }
+        elsif !@headless_only.empty?
+          raise Error, "#{@headless_only.first} needs --headless or --audio-out"
+        end
+      end
+
+      # `sid` takes directories as well as tunes.
+      def validate_tune(path)
+        return if !File.exist?(path) || File.extname(path).casecmp?(".sid")
+        return if @sid_command && File.directory?(path)
+
+        raise Error, "not a .sid tune: #{path}"
+      end
+
+      def validate_numbers
+        positive("--subtune", @subtune)
+        positive("--seconds", @seconds)
+        positive("--rate", @rate)
+        positive("--filter-chunk", @filter_chunk)
+      end
+
+      def positive(name, value)
+        raise Error, "invalid argument: #{name} #{value}" if !value.nil? && value <= 0
+      end
+
+      def validate_paths
+        missing = tune_paths.find { |path| !File.exist?(path) }
+        raise Error, "no such file or directory: #{missing}" unless missing.nil?
+        raise Error, "no such file or directory: #{@songlengths}" unless @songlengths.nil? || File.exist?(@songlengths)
+      end
+    end
+  end
+end