smp_tool 0.1.0

data/lib/smp_tool/virtual_volume/volume_data.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module VirtualVolume
+    #
+    # Provides set of methods to work with volume's data.
+    #
+    class VolumeData < SimpleDelegator
+      def initialize(obj, extra_word)
+        @obj = obj
+        @extra_word = extra_word
+
+        super(obj)
+      end
+
+      def snapshot
+        map(&:snapshot)
+      end
+
+      #
+      # Rename file on the virtual volume.
+      #
+      # @param [SMPTool::Filename] old_id
+      # @param [SMPTool::Filename] new_id
+      #
+      # @return [Array<String>]
+      #   Old and new ASCII filenames of a renamed file.
+      #
+      # @raise [ArgumentError]
+      #   - Can't assign name `new_id` to the file since another file with
+      #   the same name already exists;
+      #   - File `old_id` not found.
+      #
+      def f_rename(old_id, new_id)
+        _raise_already_exists(new_id.print_ascii) if _already_exists?(new_id.radix50)
+
+        idx = _find_idx(old_id.radix50)
+
+        _raise_file_not_found(old_id.print_ascii) unless idx
+
+        self[idx].rename(new_id.radix50)
+
+        [old_id.print_ascii, new_id.print_ascii]
+      end
+
+      #
+      # Delete file from the virtual volume.
+      #
+      # @param [SMPTool::Filename] file_id
+      #
+      # @return [String]
+      #   ASCII filename of a deleted file.
+      #
+      # @raise [ArgumentError]
+      #   - File with `file_id` not found.
+      #
+      def f_delete(file_id)
+        idx = _find_idx(file_id.radix50)
+
+        _raise_file_not_found(file_id.print_ascii) unless idx
+
+        self[idx].clean
+
+        file_id.print_ascii
+      end
+
+      #
+      # Consolidate all free space at the end of the volume.
+      #
+      # @return [Integer] n_free_clusters
+      #   Number of free clusters that were joined.
+      #
+      def squeeze
+        n_free_clusters = calc_n_free_clusters
+
+        return n_free_clusters if n_free_clusters.zero?
+
+        reject!(&:empty_entry?)
+
+        push_empty_entry(n_free_clusters)
+
+        n_free_clusters
+      end
+
+      #
+      # Calculate total number of free clusters.
+      #
+      # @return [Integer]
+      #
+      def calc_n_free_clusters
+        self.select(&:empty_entry?)
+            .sum(&:n_clusters)
+      end
+
+      #
+      # Append a file.
+      #
+      # @param [SMPTool::VirtualVolume::DataEntry] file
+      #
+      # @return [String] file.print_ascii_filename
+      #   ASCII filename of the pushed file.
+      #
+      def f_push(file)
+        _raise_already_exists(file.print_ascii_filename) if _already_exists?(file.filename)
+
+        # We're starting from the end of the array, since free space tend to locate
+        # at the end of the volume (esp. after the 'squeeze' command).
+        idx = index(reverse_each.detect { |e| e.n_clusters >= file.n_clusters && e.empty_entry? })
+
+        unless idx
+          raise ArgumentError,
+                "no free space found to fit the file (try to squeeze, delete files or allocate more clusters)"
+        end
+
+        _f_push(file, idx)
+
+        file.print_ascii_filename
+      end
+
+      def push_empty_entry(n_free_clusters)
+        push(_new_empty_entry(n_free_clusters))
+
+        self
+      end
+
+      #
+      # <Description>
+      #
+      # @param [Integer] n_clusters
+      #   Number of clusters to add (pos. int.) or to trim (neg. int.).
+      #
+      # @return [Integer] n_clusters
+      #   Number of clusters that were added/trimmed.
+      #
+      def resize(n_clusters)
+        n_free_clusters = calc_n_free_clusters
+        diff = n_free_clusters + n_clusters
+
+        if reject(&:empty_entry?).empty? && diff < 1
+          raise ArgumentError, "Can't trim: volume should keep at least one empty/file entry"
+        end
+
+        reject!(&:empty_entry?)
+        push_empty_entry(diff) unless diff.zero?
+
+        n_clusters
+      end
+
+      private
+
+      def _new_empty_entry(n_free_clusters)
+        DataEntry.new(
+          header: DataEntryHeader.new(
+            _free_entry_header_params(n_free_clusters)
+          ),
+          data: PAD_CHR * (n_free_clusters * CLUSTER_SIZE)
+        )
+      end
+
+      def _f_push(file, idx)
+        n_clusters_left = self[idx].n_clusters - file.n_clusters
+
+        insert(idx, file)
+        delete_at(idx + 1)
+
+        return if n_clusters_left.zero?
+
+        insert(-idx, _new_empty_entry(n_clusters_left))
+      end
+
+      def _free_entry_header_params(n_clusters)
+        {
+          status: EMPTY_ENTRY,
+          filename: [PAD_WORD, PAD_WORD, PAD_WORD],
+          n_clusters: n_clusters,
+          ch_job: DEF_CH_JOB,
+          date: DEF_DATE,
+          extra_word: @extra_word
+        }
+      end
+
+      def _raise_file_not_found(filename)
+        raise ArgumentError, "File '#{filename}' not found on the volume"
+      end
+
+      def _raise_already_exists(filename)
+        raise ArgumentError, "File with the filename '#{filename}' already exists on the volume"
+      end
+
+      #
+      # Check if file with the Radix-50 filename `file_id` already exists.
+      #
+      # @param [Array<Integer>] file_id
+      #   RADIX-50 filename.
+      #
+      # @return [Boolean]
+      #
+      def _already_exists?(file_id)
+        idx = _find_idx(file_id)
+        idx.nil? ? false : true
+      end
+
+      #
+      # Find index of a file with the Radix-50 filename `file_id`.
+      #
+      # @param [Array<Integer>] file_id
+      #   RADIX-50 filename.
+      #
+      # @return [Integer, nil]
+      #
+      def _find_idx(file_id)
+        find_index { |e| e.filename == file_id }
+      end
+    end
+  end
+end

data/lib/smp_tool/virtual_volume/volume_params.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module VirtualVolume
+    #
+    # Virtual volume parameters.
+    #
+    class VolumeParams
+      attr_accessor :n_clusters_allocated
+
+      attr_reader :n_extra_bytes_per_entry, :n_dir_segs,
+                  :n_clusters_per_dir_seg, :extra_word, :n_max_entries_per_dir_seg,
+                  :n_max_entries
+
+      def initialize(
+        n_clusters_allocated:,
+        n_extra_bytes_per_entry:,
+        n_dir_segs:,
+        n_clusters_per_dir_seg:,
+        extra_word:
+      )
+        @n_clusters_allocated = n_clusters_allocated
+        @n_extra_bytes_per_entry = n_extra_bytes_per_entry
+        @n_dir_segs = n_dir_segs
+        @n_clusters_per_dir_seg = n_clusters_per_dir_seg
+        @extra_word = extra_word
+
+        _validate_input
+
+        @n_max_entries_per_dir_seg = _calc_n_max_entries_per_dir_seg
+        @n_max_entries = @n_dir_segs * @n_max_entries_per_dir_seg
+      end
+
+      def snapshot
+        {
+          n_clusters_allocated: @n_clusters_allocated,
+          n_extra_bytes_per_entry: @n_extra_bytes_per_entry,
+          n_dir_segs: @n_dir_segs,
+          n_clusters_per_dir_seg: @n_clusters_per_dir_seg,
+          extra_word: @extra_word,
+          n_max_entries_per_dir_seg: @n_max_entries_per_dir_seg,
+          n_max_entries: @n_max_entries
+        }
+      end
+
+      private
+
+      def _validate_input
+        result = VolumeParamsContract.new.call(_input_snapshot)
+
+        raise ArgumentError, result.errors.to_h.to_a.join(": ") unless result.success?
+      end
+
+      def _input_snapshot
+        {
+          n_clusters_allocated: @n_clusters_allocated,
+          n_extra_bytes_per_entry: @n_extra_bytes_per_entry,
+          n_dir_segs: @n_dir_segs,
+          n_clusters_per_dir_seg: @n_clusters_per_dir_seg,
+          extra_word: @extra_word
+        }
+      end
+
+      def _calc_n_max_entries_per_dir_seg
+        entry_size = ENTRY_BASE_SIZE + @n_extra_bytes_per_entry
+        (((@n_clusters_per_dir_seg * CLUSTER_SIZE) - HEADER_SIZE - FOOTER_SIZE) / entry_size).floor
+      end
+    end
+  end
+end

data/lib/smp_tool/virtual_volume/volume_params_contract.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module VirtualVolume
+    #
+    # Virtual volume params contract.
+    #
+    class VolumeParamsContract < Dry::Validation::Contract
+      config.messages.default_locale = :en
+
+      json do
+        required(:n_clusters_allocated).value(
+          :integer,
+          lteq?: N_CLUSTERS_MAX
+        )
+
+        required(:n_extra_bytes_per_entry).value(
+          :integer,
+          included_in?: [0, 2]
+        )
+
+        required(:n_dir_segs).value(
+          :integer,
+          gteq?: 1,
+          lteq?: 2
+        )
+
+        required(:n_clusters_per_dir_seg).value(
+          :integer,
+          gteq?: 1,
+          lteq?: 2
+        )
+
+        required(:extra_word).value(
+          :integer
+        )
+      end
+
+      rule(:n_dir_segs, :n_clusters_per_dir_seg) do
+        msg = "Can't use :n_dir_segs => #{values[:n_dir_segs]}" \
+              "& :n_clusters_per_dir_seg => #{values[:n_clusters_per_dir_seg]}"
+
+        key.failure(msg) if values[:n_dir_segs] == 2 && values[:n_clusters_per_dir_seg] == 1
+      end
+
+      rule(:n_clusters_allocated, :n_clusters_per_dir_seg, :n_dir_segs) do
+        n_min_clusters = N_SYS_CLUSTERS + values[:n_clusters_per_dir_seg] * values[:n_dir_segs] + 1
+        msg = "Min. number of clusters for the configuration is: #{n_min_clusters}"
+        key.failure(msg) if values[:n_clusters_allocated] < n_min_clusters
+      end
+    end
+  end
+end

data/lib/smp_tool/virtual_volume.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SMPTool
+  #
+  # Namespace for the virtual volume.
+  #
+  module VirtualVolume; end
+end

data/lib/smp_tool/volume_io/bootloader.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module VolumeIO
+    #
+    # Bootloader.
+    #
+    class Bootloader < BinData::Record
+      endian :little
+
+      array :bytes, initial_length: -> { CLUSTER_SIZE } do
+        uint8
+      end
+
+      string :padding, length: -> { CLUSTER_SIZE - padding.rel_offset }, pad_byte: PAD_BYTE
+    end
+  end
+end

data/lib/smp_tool/volume_io/data.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module VolumeIO
+    #
+    # Volume data.
+    #
+    class Data < BinData::Array
+      default_parameter read_until: -> { index == all_entries.length - 1 }
+
+      file_content
+    end
+  end
+end

data/lib/smp_tool/volume_io/dir_entry.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module VolumeIO
+    #
+    # A single directory entry.
+    #
+    class DirEntry < BinData::Record
+      endian :little
+
+      virtual :ascii_filename, value: -> { _radix_to_ascii(filename) }, onlyif: -> { status != DIR_SEG_FOOTER }
+
+      # Status word: empty area/permanent file/end-of-segment:
+      uint16le :status
+
+      # RADIX-50 filename (6 bytes):
+      array :filename, onlyif: -> { status != DIR_SEG_FOOTER }, initial_length: RAD50_FN_SIZE do
+        uint16le initial_value: PAD_WORD
+      end
+
+      # Number of clusters occupied by the file:
+      uint16le :n_clusters, onlyif: -> { status != DIR_SEG_FOOTER }
+
+      # Job & channel, unused in the MK90:
+      uint16le :ch_job, onlyif: -> { status != DIR_SEG_FOOTER }, initial_value: DEF_CH_JOB
+
+      # Creation date, unused in the MK90:
+      uint16le :date, onlyif: -> { status != DIR_SEG_FOOTER }, initial_value: DEF_DATE
+
+      # Extra word is unused in the BASIC v.1.0, but it is required in the BASIC v.2.0.
+      # The use in the v.2.0 is unknown, probably it was reserved for a checksum.
+      # BASIC v.2.0 always sets it to 0x00A0.
+      uint16le :extra_word,
+               onlyif: lambda {
+                         status != DIR_SEG_FOOTER && header.n_extra_bytes_per_entry.positive?
+                       }
+
+      private
+
+      def _radix_to_ascii(int_arr)
+        DECRadix50.decode(DECRadix50::MK90_CHARSET, int_arr)
+      end
+    end
+  end
+end

data/lib/smp_tool/volume_io/dir_seg.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "dir_seg_header"
+require_relative "dir_entry"
+
+module SMPTool
+  module VolumeIO
+    #
+    # A single segment from the directory.
+    #
+    class DirSeg < BinData::Record
+      endian :little
+      hide :padding
+
+      dir_seg_header :header
+
+      array :dir_seg_entries, read_until: -> { element.status == DIR_SEG_FOOTER } do
+        dir_entry :dir_entry
+      end
+
+      virtual :n_clusters_per_dir_seg, initial_value: -> { header.data_offset == 3 ? 1 : N_CLUSTERS_PER_DIR_SEG }
+      virtual :entry_size, initial_value: -> { ENTRY_BASE_SIZE + header.n_extra_bytes_per_entry }
+      virtual :n_max_entries, initial_value: lambda {
+        (((n_clusters_per_dir_seg * CLUSTER_SIZE) - header.num_bytes - FOOTER_SIZE) / entry_size).floor
+      }
+
+      string :padding, length: -> { n_clusters_per_dir_seg * CLUSTER_SIZE - padding.rel_offset }, pad_byte: PAD_BYTE
+
+      # Number of entries in this dirseg:
+      virtual :n_entries, initial_value: -> { dir_seg_entries.reject { |e| e.status == DIR_SEG_FOOTER }.length }
+    end
+  end
+end

data/lib/smp_tool/volume_io/dir_seg_header.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module VolumeIO
+    #
+    # Directory segment header. See Table 1-2: Directory Segment Header Words [DEC].
+    #
+    # Notes:
+    # - word #4 should be set to 0x0000 for the BASIC v.1.0, 0x0002 for the BASIC v.2.0.
+    # - word #5 allows to use only one cluster for the entire directory.
+    #
+    class DirSegHeader < BinData::Record
+      endian :little
+
+      uint16le :n_dir_segs                    # The total number of segments in this directory.
+      uint16le :i_next_seg                    # The index of the next logical directory segment.
+      uint16le :i_high_seg,                   # The index of the highest segment currently in use.
+               initial_value: 1
+      uint16le :n_extra_bytes_per_entry       # The number of extra bytes per directory entry, an even number.
+      uint16le :data_offset                   # The block number where the actual stored data begins.
+    end
+  end
+end

data/lib/smp_tool/volume_io/directory.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "dir_seg"
+
+module SMPTool
+  module VolumeIO
+    #
+    # From the DEC's manual [DEC]:
+    #
+    # The directory consists of a series of two-block segments. Each segment is 512 words
+    # long and contains information about files such as name, length, and creation date.
+    #
+    class Directory < BinData::Record
+      endian :little
+
+      # Last dirseg should set 'i_next_seg' word in the header to 0,
+      # so that indicates the last segment in the directory.
+      array :segments, read_until: -> { element.header.i_next_seg.zero? } do
+        dir_seg
+      end
+
+      # Total number of entries (from all dirsegs) in this dir.
+      virtual :n_entries, initial_value: -> { segments.to_ary.sum(&:n_entries) }
+    end
+  end
+end

data/lib/smp_tool/volume_io/file_content.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module VolumeIO
+    #
+    # Content of a single entry (file).
+    #
+    class FileContent < BinData::String
+      default_parameter read_length: -> { all_entries.to_a[index].n_clusters * CLUSTER_SIZE }
+      default_parameter pad_byte: PAD_BYTE
+    end
+  end
+end

data/lib/smp_tool/volume_io/home_block.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module VolumeIO
+    #
+    # Home block.
+    #
+    class HomeBlock < BinData::Record
+      endian :little
+
+      array :bytes, initial_length: -> { CLUSTER_SIZE } do
+        uint8
+      end
+
+      string :padding, length: -> { CLUSTER_SIZE - padding.rel_offset }, pad_byte: PAD_BYTE
+    end
+  end
+end

data/lib/smp_tool/volume_io/volume_io.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "bootloader"
+require_relative "home_block"
+require_relative "directory"
+require_relative "file_content"
+require_relative "data"
+
+module SMPTool
+  module VolumeIO
+    #
+    # MK90 BASIC volume.
+    #
+    class VolumeIO < BinData::Record
+      hide :bootloader
+      hide :home_block
+
+      bootloader :bootloader
+      home_block :home_block
+      directory :directory
+      data :data
+
+      virtual :n_clusters_allocated, initial_value: -> { num_bytes / CLUSTER_SIZE }
+
+      # Empty and permanent entries.
+      virtual :all_entries,
+              initial_value: lambda {
+                directory.segments.flat_map(&:dir_seg_entries)
+                         .reject { |e| e.status == DIR_SEG_FOOTER }
+              }
+
+      # Permanent entries (i.e. files) only.
+      virtual :file_only_entries,
+              initial_value: lambda {
+                directory.segments.flat_map(&:dir_seg_entries)
+                         .reject { |e| e.status == DIR_SEG_FOOTER }
+                         .reject { |e| e.status == EMPTY_ENTRY }
+              }
+
+      virtual :n_extra_bytes_per_entry,
+              initial_value: -> { directory.segments.first.header.n_extra_bytes_per_entry }
+
+      virtual :n_max_entries_per_dir_seg,
+              initial_value: -> { directory.segments.first.n_max_entries }
+
+      virtual :n_dir_segs,
+              initial_value: -> { directory.segments.length }
+
+      virtual :n_clusters_per_dir_seg,
+              initial_value: -> { directory.segments.first.n_clusters_per_dir_seg }
+    end
+  end
+end

data/lib/smp_tool/volume_io.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module SMPTool
+  #
+  # Namespace for the classes that handle volume IO operations,
+  # e.g. reading/parsing volume from a 'raw' binary string, and
+  # writing it back to a binary string.
+  #
+  module VolumeIO; end
+end

data/lib/smp_tool.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "bindata"
+require "delegate"
+require "dec_radix_50"
+require "dry/validation"
+require "forwardable"
+require "injalid_dejice"
+require "zeitwerk"
+
+require_relative "smp_tool/autoloader"
+require_relative "smp_tool/version"
+
+SMPTool::Autoloader.setup
+
+#
+# Lib to work with Elektronika MK90 bin volumes.
+#
+module SMPTool
+  class Error < StandardError; end
+
+  #
+  # Documentation sources:
+  #
+  # 1. [DEC] http://www.bitsavers.org/pdf/dec/pdp11/rt11/v5.6_Aug91/AA-PD6PA-TC_RT-11_Volume_and_File_Formats_Manual_Aug91.pdf
+  #
+
+  PAD_BYTE = 0x20
+  PAD_CHR = PAD_BYTE.chr.freeze
+  PAD_WORD = 0x2020
+
+  # Sizes, in clusters:
+  N_SYS_CLUSTERS = 2 # Bootloader + home block.
+  N_CLUSTERS_PER_DIR_SEG = 2
+  N_CLUSTERS_MAX = 127
+
+  # Sizes, in bytes:
+  CLUSTER_SIZE = 512
+  HEADER_SIZE = 10
+  FOOTER_SIZE = 2
+  ENTRY_BASE_SIZE = 14
+
+  # Sizes, in 16-bit words:
+  RAD50_FN_SIZE = 3 # RADIX-50 filename size.
+
+  # Directory entry status codes.
+  EMPTY_ENTRY = 0x0200    # Empty entry.
+  PERM_ENTRY = 0x0400     # Permanent file (occupied entry).
+  DIR_SEG_FOOTER = 0x0800 # Directory segment footer, a.k.a. end-of-segment marker.
+
+  # Default entry attributes:
+  DEF_CH_JOB = 0x0000
+  DEF_DATE = 0xFFFF
+end

data/sig/smp_tool.rbs

@@ -0,0 +1,4 @@
+module SMPTool
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end