smp_tool-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: da03ac32fe8ebcf2d0f32f19d49f37b48b7404289bc91cf006e45c4dddc353a1
+  data.tar.gz: 78a43fdd3e6f1f533681e362786ad8059bb07a39703d2e0d6d4dda3f5ffe29da
+SHA512:
+  metadata.gz: a060a0c98f3bef66ef1984f30f0e6098e0219789197009acef2ca157cfa013ee08112df4ef0ea2a0bc6af2fc8b19a690114a7371ae53057c1dd97ad5f7e50c53
+  data.tar.gz: 358a6164fb66b79767900a0f8506304636ce1d67c2201ad2059e39aebe52388dd3dea7fabd34d9e0378c2ab330283a0744b9f6beabd29dd2336c30c5fe61af50

data/.rubocop.yml

@@ -0,0 +1,16 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/.vscode/launch.json

@@ -0,0 +1,21 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "rdbg",
+      "name": "Debug current file with rdbg",
+      "request": "launch",
+      "script": "${file}",
+      "args": [],
+      "askParameters": true
+    },
+    {
+      "type": "rdbg",
+      "name": "Attach with rdbg",
+      "request": "attach"
+    }
+  ]
+}

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [0.1.0] - 2024-03-14
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 8bit-m8
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,83 @@
+# smp_tool/cli
+
+A Ruby command-line application to work with the Elektronika MK90 volume images.
+
+## Key features
+
+* **Supports all common operations**:
+  * creating new volumes;
+  * adding BASIC files to a volume;
+  * deleting BASIC files from a volume;
+  * renaming BASIC files on a volume;
+  * extracting BASIC files from a volume;
+  * changing volume size.
+
+* **Supports variable volume size: from 4 up to 127 clusters (2048 – 65024 bytes)**
+
+  A standard MPO-10 cartridge has capacity of 20 clusters (10240 bytes), but the tool can create volumes of smaller or larger size. Such volumes can be loaded into a real machine with a modern cartridge such as [azya52/STMP](https://github.com/azya52/STMP) (not tested) or [azya52/PIMP](https://github.com/azya52/PIMP) (seems to work only on BASIC v.1.0 systems, see below). The emulator by Piotr Piatek also supports such volumes.
+
+* **Supports Elektronika MK90 BASIC v.1.0 and v.2.0 volumes**
+
+  The tool automatically detects the volume version while loading the volume. Manual specification of the target BASIC version requires only to create an empty volume.
+
+* **Allows to create volumes with the auto-loader**
+
+  Create a volume with the `--bootloader="auto"` option. Then add the `AUTO.BAS` file to the volume files. Mount the volume to the MK90, and select the slot in the main menu. This will automagically load and run any BASIC script defined in the `AUTO.BAS` file. Auto loaders were developed by Piotr Piatek.
+
+* **Has a special mode that can free one more cluster (512 bytes) to store data**
+
+  Create a volume with the `--n-cls-per-dir-seg=1` option. This will create a volume with a "trimmed" directory segment, allowing to use one more cluster to store data.
+
+## Known bugs and limitations
+
+* PIMP cartridge seems to be incompatible with the BASIC v.2.0 system. While the cartridge can run binary code on both version of the system, the access to the volume from the BASIC environment seems to work only on the v.1.0 systems. This is not a bug in the **smp_tool** software but rather a limitation caused by the PIMP design.
+
+## Prerequisites
+
+* Ruby ver. >= 3.0.0.
+
+## Installation
+
+    $ gem install smp_tool-cli
+
+## Usage
+
+General syntax is:
+
+    $ smp_tool <command> [options]
+    
+Use the `-h` flag to get the list of available commands:
+
+    $ smp_tool -h
+
+Call a command with the `-h` flag to get help information about the command:
+
+    $ smp_tool <command> -h
+
+## Tips
+
+* To load a program in BASIC 1.0 simply provide a filename in quotes, e.g.: `LOAD "FILE.BAS"`. To load a program in BASIC 2.0 add the parameter `A`, e.g.: `LOAD "FILE.BAS", A`.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/8bit-mate/smp_tool-cli.rb.
+
+## Special thanks to
+
+- **[Piotr Piatek](http://www.pisi.com.pl/piotr433/index.htm)**: the indisputable master of the MK90 who developed lots of great software tools and hardware devices for the machine;
+
+- **[azya52](https://github.com/azya52/)**: the developer of the PIMP cartridge. This device made possible to load large volumes on a real MK90;
+
+- **[flint-1979](https://phantom.sannata.org/memberlist.php?mode=viewprofile&u=6909)**: testing on the real machines with both BASIC v.1.0 and v.2.0;
+
+- **[BitSavers project](http://www.bitsavers.org/)**: the largest source of the DEC PDP-11 / RT-11 and other legacy systems documentation.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/exe/smp_tool

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "./../lib/smp_tool/cli"
+
+# DEBUG:
+# ARGV = "z -i exe/smp0.bin -c -5".split(" ")
+
+begin
+  Dry::CLI.new(SMPTool::CLI::Commands).call
+  exit 0
+rescue StandardError => e
+  logger = SMPTool::CLI::Logger.new
+  logger.error(e.message)
+  exit 1
+end

data/lib/smp_tool/cli/autoloader.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module SMPTool
+  module CLI
+    #
+    # Gem's autoloader.
+    #
+    class Autoloader
+      class << self
+        def setup
+          loader = Zeitwerk::Loader.new
+          loader.push_dir(Pathname(__dir__).join("../../")) # lib
+          loader.inflector.inflect(
+            "smp_tool" => "SMPTool",
+            "cli" => "CLI"
+          )
+          loader.setup
+        end
+      end
+    end
+  end
+end

data/lib/smp_tool/cli/commands/base_command.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module CLI
+    module Commands
+      #
+      # Base class for all commands.
+      #
+      class BaseCommand < Dry::CLI::Command
+        option :verbosity,
+               type: :string,
+               required: false,
+               default: "brief",
+               desc: "Verbosity level: { quiet | brief | verbose | debug }"
+
+        def call(**); end
+
+        private
+
+        def _logger(level)
+          Logger.new(level: level)
+        end
+      end
+    end
+  end
+end

data/lib/smp_tool/cli/commands/delete.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module CLI
+    module Commands
+      #
+      # Delete a file from the volume.
+      #
+      class Delete < VolumeOperation
+        desc "Delete a file from the volume"
+
+        option :filename,
+               required: true,
+               desc: "File to delete",
+               aliases: ["-f"]
+
+        def call(input:, filename:, **options)
+          Executor::Deleter.new(
+            input: input,
+            filename: filename,
+            logger: _logger(options[:verbosity]),
+            **options
+          ).call
+        end
+      end
+    end
+  end
+end

data/lib/smp_tool/cli/commands/extract.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module CLI
+    module Commands
+      #
+      # Command to extract individual files from the volume.
+      #
+      class Extract < InputCommand
+        desc "Extract individual files from the volume"
+
+        option :dir,
+               required: false,
+               default: Dry::Files.new.pwd,
+               desc: "Output directory",
+               aliases: ["-d"]
+
+        option :f_list,
+               type: :array,
+               required: true,
+               desc: "File(s) to extract",
+               aliases: ["-f"]
+
+        def call(input:, f_list:, **options)
+          Executor::ExtracterTxt.new(
+            input: input,
+            f_list: f_list,
+            logger: _logger(options[:verbosity]),
+            **options
+          ).call
+        end
+      end
+    end
+  end
+end

data/lib/smp_tool/cli/commands/extract_all.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module CLI
+    module Commands
+      #
+      # Command to extract all files from the volume.
+      #
+      class ExtractAll < InputCommand
+        desc "Extract all files from the volume"
+
+        option :dir,
+               required: false,
+               default: Dry::Files.new.pwd,
+               desc: "Output directory",
+               aliases: ["-d"]
+
+        def call(input:, **options)
+          Executor::ExtracterTxtAll.new(
+            input: input,
+            logger: _logger(options[:verbosity]),
+            **options
+          ).call
+        end
+      end
+    end
+  end
+end

data/lib/smp_tool/cli/commands/info.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module CLI
+    module Commands
+      #
+      # Command to print info about the volume.
+      #
+      class Info < InputCommand
+        desc "Print info about the volume"
+
+        def call(input:, **options)
+          Executor::Informer.new(
+            input: input,
+            logger: _logger(options[:verbosity]),
+            **options
+          ).call
+        end
+      end
+    end
+  end
+end

data/lib/smp_tool/cli/commands/input_command.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module CLI
+    module Commands
+      #
+      # A command with input.
+      #
+      class InputCommand < BaseCommand
+        option :input,
+               required: true,
+               desc: "Input filename",
+               aliases: ["-i"]
+      end
+    end
+  end
+end

data/lib/smp_tool/cli/commands/new.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module CLI
+    module Commands
+      #
+      # Command to create a new volume.
+      #
+      class New < BaseCommand
+        desc "Create a new volume"
+
+        option :output,
+               default: "smp0.bin",
+               required: false,
+               desc: "Output filename",
+               aliases: ["-o"]
+
+        option :basic,
+               required: true,
+               desc: "Target Basic version { 1 | 2 }",
+               aliases: ["-b"]
+
+        option :n_clusters,
+               default: DEF_N_CLUSTERS,
+               required: false,
+               desc: "Number of clusters allocated to the volume",
+               aliases: ["-c"]
+
+        option :n_dir_segs,
+               default: DEF_N_DIR_SEGS,
+               required: false,
+               desc: "Number of directory segments { 1 | 2 }",
+               aliases: ["-d"]
+
+        option :n_cls_per_dir_seg,
+               default: DEF_N_CLS_PER_DIR_SEG,
+               required: false,
+               desc: "Number of clusters per directory segment { 1 | 2 }",
+               aliases: ["-s"]
+
+        option :bootloader,
+               default: DEF_BOOTLOADER,
+               required: false,
+               desc: "Bootloader type { default | auto }",
+               aliases: ["-l"]
+
+        example [
+          "-b 1                   # Create a BASIC v.1.0 volume with the default parameters, " \
+                                  "save result to the `smp0.bin` file (default path)",
+          "-b 2 -o /dir/smp.bin   # Create a BASIC v.1.0 volume with the default parameters, " \
+                                  "save result to the `/dir/smp.bin` file (custom path)",
+          "-b 2 -l auto           # Create a BASIC v.2.0 volume with the auto-loader",
+          "-b 1 -c 127 -d 2       # Create the largest possible BASIC v.1.0 volume",
+          "-b 1 -s 1              # Create a BASIC v.1.0 volume with the 'trimmed' directory"
+        ]
+
+        def call(output:, basic:, **options)
+          Executor::Creator.new(
+            output: output,
+            volume_specs: _parse_vol_specs(basic, options),
+            logger: _logger(options[:verbosity]),
+            **options
+          ).call
+        end
+
+        private
+
+        def _parse_vol_specs(basic, options)
+          VolumeSpecsInterface.new(
+            basic: basic,
+            bootloader: options[:bootloader],
+            n_clusters: options[:n_clusters],
+            n_dir_segs: options[:n_dir_segs],
+            n_cls_per_dir_seg: options[:n_cls_per_dir_seg]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/smp_tool/cli/commands/push.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module CLI
+    module Commands
+      #
+      # Command to push a file to the volume.
+      #
+      class Push < VolumeOperation
+        desc "Push a list of files to the volume"
+
+        option :f_list,
+               type: :array,
+               required: true,
+               desc: "File(s) to push",
+               aliases: ["-f"]
+
+        def call(input:, f_list:, **options)
+          Executor::Pusher.new(
+            input: input,
+            f_list: f_list,
+            logger: _logger(options[:verbosity]),
+            **options
+          ).call
+        end
+      end
+    end
+  end
+end

data/lib/smp_tool/cli/commands/rename.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module CLI
+    module Commands
+      #
+      # Command to rename a file on the volume.
+      #
+      class Rename < VolumeOperation
+        desc "Rename a file on the volume"
+
+        option :old_fn,
+               required: true,
+               desc: "File to rename",
+               aliases: ["-o"]
+
+        option :new_fn,
+               required: true,
+               desc: "New filename for the file",
+               aliases: ["-n"]
+
+        def call(input:, new_fn:, old_fn:, **options)
+          Executor::Renamer.new(
+            input: input,
+            old_fn: old_fn,
+            new_fn: new_fn,
+            logger: _logger(options[:verbosity]),
+            **options
+          ).call
+        end
+      end
+    end
+  end
+end

data/lib/smp_tool/cli/commands/resize.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module CLI
+    module Commands
+      #
+      # Command to change volume size.
+      #
+      class Resize < VolumeOperation
+        desc "Change volume size"
+
+        option :n_clusters,
+               required: true,
+               desc: "Number of clusters to add/trim",
+               aliases: ["-c"]
+
+        def call(input:, n_clusters:, **options)
+          Executor::Resizer.new(
+            input: input,
+            n_clusters: n_clusters,
+            logger: _logger(options[:verbosity]),
+            **options
+          ).call
+        end
+      end
+    end
+  end
+end

data/lib/smp_tool/cli/commands/squeeze.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module CLI
+    module Commands
+      #
+      # Command to consolidate all free space at the end of a volume.
+      #
+      class Squeeze < VolumeOperation
+        desc "Consolidate all free space at the end of the volume"
+
+        def call(input:, **options)
+          Executor::Squeezer.new(
+            input: input,
+            logger: _logger(options[:verbosity]),
+            **options
+          ).call
+        end
+      end
+    end
+  end
+end

data/lib/smp_tool/cli/commands/version.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module CLI
+    module Commands
+      #
+      # Print version.
+      #
+      class Version < Dry::CLI::Command
+        desc "Print version"
+
+        def call(*)
+          puts "CLI (smp_tool-cli) version: #{SMPTool::CLI::VERSION}"
+          puts "Core lib (smp_tool) version: #{SMPTool::VERSION}"
+        end
+      end
+    end
+  end
+end

data/lib/smp_tool/cli/commands/volume_operation.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module CLI
+    module Commands
+      #
+      # Base class for all commands that do some operation on the volume itself.
+      #
+      class VolumeOperation < InputCommand
+        option :output,
+               required: false,
+               desc: "Output filename",
+               aliases: ["-o"]
+
+        option :apply,
+               type: :boolean,
+               required: false,
+               desc: "Apply result to the input *.bin file",
+               aliases: ["-a"]
+      end
+    end
+  end
+end

data/lib/smp_tool/cli/commands.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SMPTool
+  module CLI
+    #
+    # CLI commands.
+    #
+    module Commands
+      extend Dry::CLI::Registry
+
+      register "new", New, aliases: ["n"]
+
+      register "delete", Delete, aliases: %w[d del]
+      register "extract", Extract, aliases: ["e"]
+      register "extract-all", ExtractAll, aliases: ["x"]
+      register "info", Info, aliases: ["i"]
+      register "push", Push, aliases: ["p"]
+      register "rename", Rename, aliases: ["r"]
+      register "resize", Resize, aliases: ["z"]
+      register "squeeze", Squeeze, aliases: ["s"]
+
+      register "version", Version, aliases: ["-v", "--version"]
+    end
+  end
+end