img_to_script 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 98fc645a04ddc50a2633b04a8d82d5ba61514d478215908e64b19a66499120fc
+  data.tar.gz: 7a40da06bfb2c9b7fba74bfc2cc6b201b92ea672c27203da20096f0ecb05d347
+SHA512:
+  metadata.gz: aba04a011f62d58441ccd402077de347788629c9eb41975de644674bb389726f367f3f92e167d9680b176561442089088d100f6e9c2c97724926329492f455fa
+  data.tar.gz: 87f2c883e748c07836d2f0b4d24961a34784b7a8932b2682855e929c3c4f8df05e466171a69058937dac744d634e8a40ea834efdda172bac88fe6493373ff4cb

data/.rubocop.yml

@@ -0,0 +1,25 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/MethodLength:
+  Max: 15
+
+Naming/MethodParameterName:
+  AllowedNames:
+    - x
+    - y
+    - x0
+    - x1
+    - y0
+    - y1

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,7 @@
+## [1.0.0] - 2023-12-11
+
+- API change.
+
+## [0.1.0] - 2023-11-26
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 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,271 @@
+# ImgToScript
+
+## Introduction
+
+**img_to_script** is a Ruby gem (a library) that converts images to executable scripts that plot the binary version of the image using the simple commands e.g. “draw a line”, “draw a dot”, etc..
+
+The gem was initially developed to convert binary images to the executable scripts for the build-in BASIC interpreter of the Soviet vintage portable computer **Elektronika MK90**. Yet it is possible to expand the gem to support other similar hardware and script languages (e.g. the build-in TI-BASIC of the Z80-based TI calculators).
+
+![Elektronika MK90 renders an image with the build-in BASIC interpreter](/data/lain-mk90.jpg)
+
+*Vintage Elektronika MK90 renders an image with the build-in BASIC interpreter. The program was generated by the **img_to_script** gem.*
+
+The gem was designed as a library, i.e. it neither provide a user interface, nor validates the input data. It only provides an API, the rest should be handled by the external software. To make a converter you’ll need to build an application around the **img_to_script** gem and provide a user interface, e.g. a command-line interface or a web interface.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "img_to_script"
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install img_to_script
+
+## Modules
+
+Three steps are required to complete the conversion. The gem has a dedicated module (a namespace) for each step: 
+
+- **Generator** reads the image data and creates an array of the abstract tokens. Each token represents a simple command to the interpreter, e.g.: “draw a line”, “draw a dot”, “assign a value to a variable”, “start a loop”, etc..
+
+- **Translator** is a mediator between a generator and a formatter. It translates abstract tokens to the specific statements of the target programming language. Translator chooses keywords, separators and handles other syntax issues.
+
+- **Formatter** takes input from the translator and formats it into the executable script (a target language code). It can serve a function of a prettier or a minificator. Another common formatter’s task is to track down and to label BASIC line numbers.
+
+## Usage
+
+### API
+
+```ruby
+ImgToScript::Task.new(
+  generator: generator,
+  translator: translator,
+  formatter: formatter
+).run(
+  image: image,
+  scr_width: scr_width,
+  scr_height: scr_height
+)
+```
+
+todo...
+
+#### Returns
+Array\<String\>
+
+### Example
+
+1. Require the gem:
+
+```ruby
+require "img_to_script"
+```
+
+2. Read an image using the `rmagick/bin_magick` gem:
+
+```ruby
+require "rmagick/bin_magick"
+
+image = Magick::BinMagick::Image.from_file("my_file.png").to_binary!
+```
+
+3. Create a generator instance. You can also provide options via a configuration block, e.g.:
+
+```ruby
+generator = ImgToScript::Generators::RunLengthEncoding::Horizontal.new.configure do |config|
+  config.x_offset = -10
+  config.y_offset = 15
+  # etc.
+end
+```
+
+4. Create a translator instance, e.g.:
+
+```ruby
+translator = ImgToScript::Languages::MK90Basic::Translators::MK90Basic10.new
+```
+
+5. Create a formatter instance. You can also provide options via a configuration block, e.g.:
+
+```ruby
+formatter = ImgToScript::Languages::MK90Basic::Formatters::Minificator.new.configure do |config|
+  config.line_offset = 10
+  config.line_step = 5
+  config.max_chars_per_line = 60
+  # etc.
+end
+```
+
+6. Create a task instance and pass created instances as the task’s dependencies:
+
+```ruby
+task = ImgToScript::Task.new(
+  generator: generator,
+  translator: translator,
+  formatter: formatter
+)
+```
+
+Note that you can also provide your own custom objects as long as they respond to the required public interface.
+
+In case of the Elektronika MK90 BASIC **only** you can omit any dependency (i.e. skip any step from the 3rd to the 5th), since these are optional arguments. Then a default object with a default configuration will be used.
+
+You can also re-configure any dependency of an existing task object, e.g.:
+
+```ruby
+task.formatter.configure do |config|
+  # your config...
+end
+```
+
+7. Run conversion to get a script. You need to provide the image and the target device resolution:
+
+```ruby
+script = task.run(
+  image: image,
+  scr_width: 120,
+  scr_height: 64
+)
+```
+
+## Build-in classes
+
+### Generators
+
+- **ImgToScript::Generators::Generator**
+
+   Base class all generators inherit from.
+
+   **Public interface**: #generate(image:, scr_width:, scr_height:)
+
+   **Configuration options**:
+
+   - x_offset, default: X_OFFSET (0)
+
+      Offset the X point on the screen.
+
+   - y_offset, default: Y_OFFSET (0)
+
+      Offset the Y point on the screen.
+
+   - clear_screen, default: CLEAR_SCREEN (true)
+
+      Add a statement to clear the screen at the begin of the script.
+
+   - pause_program, default: PAUSE_PROGRAM (true)
+
+      Add a statement to pause the program at the end of the script.
+
+   - program_begin_lbl, default: PRORGAM_BEGIN_LBL (false)
+
+      Add a statement that marks the begin of the program.
+
+   - program_end_lbl, default: PROGRAM_END_LBL (false)
+
+      Add a statement that marks the end of the program.
+
+- **ImgToScript::Generators::HexMask::Default**
+
+   Specific for the Elektronika MK90 BASIC.
+
+   MK90's BASIC has a balanced build-in method to encode and render images. The Elektronika MK90's manual refers to it as the *hex-mask rendering* method. Each 8x1 px block of a binary image is being represented as a hex value (e.g. '00' for a tile of the 8 white pixels in a row, 'FF' for a tile of the 8 black pixels in a row, etc.). Then these hex values are being passed as arguments to the DRAM/M BASIC statement that renders the image according to the provided data.
+
+   Due to the logic of the DRAM/M operator, only vertical scan lines are supported.
+
+- **ImgToScript::Generators::HexMask::Enhanced**
+
+   Specific for the Elektronika MK90 BASIC.
+
+   Hex-mask encoding with modifications what make output BASIC code more compact.
+
+   Due to the logic of the DRAM/M operator, only vertical scan lines are supported.
+
+- **ImgToScript::Generators::RunLengthEncoding::Horizontal**
+
+   RLE, horizontal scan lines.
+
+- **ImgToScript::Generators::RunLengthEncoding::Vertical**
+
+   RLE, vertical scan lines.
+
+- **ImgToScript::Generators::Segmental::DirectDraw::Horizontal**
+
+   Directly plot segments, horizontal scan lines.
+
+- **ImgToScript::Generators::Segmental::DirectDraw::Vertical**
+
+   Directly plot segments, vertical scan lines.
+
+- **ImgToScript::Generators::Segmental::DataReadDraw::Horizontal**
+
+   Store and read segments' coordinates, when use them to plot segments. Horizontal scan lines.
+
+- **ImgToScript::Generators::Segmental::DataReadDraw::Vertical**
+
+   Store and read segments' coordinates, when use them to plot segments. Vertical scan lines.
+
+### Elektronika MK90 BASIC
+
+#### Translators
+
+- **ImgToScript::Languages::MK90Basic::Translators::Translator**
+
+   Base class all MK90 translators inherit from.
+
+   **Public interface**: #translate(abstract_tokens, **kwargs)
+
+- **ImgToScript::Languages::MK90Basic::Translators::MK90Basic10**
+
+   Translates abstract tokens to the MK90 BASIC v1.0 statements.
+
+- **ImgToScript::Languages::MK90Basic::Translators::MK90Basic20**
+
+   Translates abstract tokens to the MK90 BASIC v2.0 statements.
+
+#### Formatters
+
+- **ImgToScript::Languages::MK90Basic::Formatters::Formatter**
+
+   Base class all MK90 formatters inherit from.
+
+   **Public interface**: #format(tokens)
+
+   **Configuration options**:
+
+   - line_offset, default: LINE_OFFSET (1)
+
+      First BASIC line number.
+
+   - line_step, default: LINE_STEP (1)
+
+      Step between two neighbor BASIC lines.
+
+   - max_chars_per_line, default: MAX_CHARS_PER_LINE (80)
+
+      Note: MK90 BASIC doesn’t support more than 80 characters per line.
+
+   - number_lines, default: true
+
+- **ImgToScript::Languages::MK90Basic::Formatters::Minificator**
+
+   The aim of the minificator is to make the output script as compact as possible, and so to save space at the MPO-10 cart.
+
+## 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/img_to_script.rb.
+
+## 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/img_to_script.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "lib/img_to_script/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "img_to_script"
+  spec.version = ImgToScript::VERSION
+  spec.authors = ["8bit-mate"]
+  spec.email = ["you@example.com"]
+
+  spec.summary = "Converts images to executable scripts."
+  spec.homepage = "https://github.com/8bit-mate/img_to_script.rb"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.files -= ["data/lain-mk90.jpg"]
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "dry-system", "~> 1.0", ">= 1.0.1"
+  spec.add_dependency "run_length_encoding_rb", "~> 1.0", ">= 1.0.0"
+  spec.add_dependency "zeitwerk", "~> 2.6", ">= 2.6.12"
+
+  spec.add_development_dependency "rmagick-bin_magick", "~> 0.2", ">= 0.2.0"
+end

data/lib/img_to_script/abs_token_type.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  #
+  # Defines abstract tokens types.
+  #
+  module AbsTokenType
+    ABS_FUNC = :abs_func
+    ASSIGN_VALUE = :assign_value
+    CLEAR_SCREEN = :clear_screen
+    DATA_READ = :data_read
+    DATA_STORE = :data_store
+    DRAW_CHUNK_BY_HEX_VALUE = :draw_chunk_by_hex_value
+    DRAW_LINE_BY_ABS_COORDS = :draw_line_by_abs_coords
+    DRAW_PIXEL_BY_ABS_COORDS = :draw_pixel_by_abs_coords
+    GO_TO = :go_to
+    IF_CONDITION = :if_condition
+    LOOP_BEGIN = :loop_begin
+    LOOP_END = :loop_end
+    MATH_ADD = :math_add
+    MATH_GREATER_THAN = :math_greater_than
+    MATH_MULT = :math_mult
+    MATH_SUB = :math_sub
+    MOVE_POINT_TO_ABS_COORDS = :move_point_to_abs_coords
+    PARENTHESES = :parentheses
+    PROGRAM_BEGIN = :program_begin_lbl
+    PROGRAM_END_LBL = :program_end_lbl
+    REMARK = :remark
+    SIGN_FUNC = :sign_func
+    SIGN_GREATER_THAN = :sign_greater_than
+    WAIT = :wait
+  end
+end

data/lib/img_to_script/abstract_token/abs_func.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module AbstractToken
+    #
+    # Absolute value (modulus).
+    #
+    class AbsFunc < AbstractToken
+      attr_reader :expression
+
+      def initialize(expression:, **)
+        @type = AbsTokenType::ABS_FUNC
+        @expression = expression
+
+        super
+      end
+    end
+  end
+end

data/lib/img_to_script/abstract_token/abstract_token.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module AbstractToken
+    #
+    # Stores single command in an abstract representation.
+    #
+    class AbstractToken
+      attr_reader :type, :require_nl
+
+      #
+      # Init. a new abstract token.
+      #
+      # @option [Boolean] require_nl (false)
+      #   If 'true', the formatter will put the statement, that is
+      #   assotiated with the token, on a new line.
+      #
+      def initialize(require_nl: false, **)
+        @require_nl = require_nl
+      end
+    end
+  end
+end

data/lib/img_to_script/abstract_token/assign_value.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module AbstractToken
+    #
+    # Assign value to a variable.
+    #
+    class AssignValue < AbstractToken
+      attr_reader :left, :right
+
+      def initialize(left:, right:, **)
+        @type = AbsTokenType::ASSIGN_VALUE
+        @left = left
+        @right = right
+
+        super
+      end
+    end
+  end
+end

data/lib/img_to_script/abstract_token/clear_screen.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module AbstractToken
+    #
+    # Clear screen.
+    #
+    class ClearScreen < AbstractToken
+      def initialize(**)
+        @type = AbsTokenType::CLEAR_SCREEN
+
+        super
+      end
+    end
+  end
+end

data/lib/img_to_script/abstract_token/data_read.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module AbstractToken
+    #
+    # Read value(s) from an array of constants.
+    #
+    class DataRead < AbstractToken
+      attr_reader :var_list
+
+      def initialize(var_list:, **)
+        @type = AbsTokenType::DATA_READ
+        @var_list = Array(var_list)
+
+        super
+      end
+    end
+  end
+end

data/lib/img_to_script/abstract_token/data_store.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module AbstractToken
+    #
+    # Store array of contants.
+    #
+    class DataStore < AbstractToken
+      attr_reader :data
+
+      def initialize(data:, **)
+        @type = AbsTokenType::DATA_STORE
+        @data = Array(data)
+
+        super
+      end
+    end
+  end
+end

data/lib/img_to_script/abstract_token/draw_chunk_by_hex_value.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module AbstractToken
+    #
+    # Draw 8x1 px block of pixels encoded by a hex value.
+    #
+    class DrawChunkByHexValue < AbstractToken
+      attr_reader :hex_values
+
+      def initialize(hex_values:, **)
+        @type = AbsTokenType::DRAW_CHUNK_BY_HEX_VALUE
+        @hex_values = Array(hex_values)
+
+        super
+      end
+    end
+  end
+end

data/lib/img_to_script/abstract_token/draw_line_by_abs_coords.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module AbstractToken
+    #
+    # Draw a line by absolute coordinates.
+    #
+    class DrawLineByAbsCoords < AbstractToken
+      attr_reader :x0, :y0, :x1, :y1
+
+      def initialize(x0:, y0:, x1:, y1:, **)
+        @type = AbsTokenType::DRAW_LINE_BY_ABS_COORDS
+        @x0 = x0
+        @y0 = y0
+        @x1 = x1
+        @y1 = y1
+
+        super
+      end
+    end
+  end
+end

data/lib/img_to_script/abstract_token/draw_pixel_by_abs_coords.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module AbstractToken
+    #
+    # Draw a pixel by absolute coordinates.
+    #
+    class DrawPixelByAbsCoords < AbstractToken
+      attr_reader :x, :y
+
+      def initialize(x:, y:, **)
+        @type = AbsTokenType::DRAW_PIXEL_BY_ABS_COORDS
+        @x = x
+        @y = y
+
+        super
+      end
+    end
+  end
+end

data/lib/img_to_script/abstract_token/go_to.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module AbstractToken
+    #
+    # Go to BASIC line.
+    #
+    class GoTo < AbstractToken
+      attr_reader :line
+
+      def initialize(line:, **)
+        @type = AbsTokenType::GO_TO
+        @line = line
+
+        super
+      end
+    end
+  end
+end

data/lib/img_to_script/abstract_token/if_condition.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module AbstractToken
+    #
+    # If condition.
+    #
+    class IfCondition < AbstractToken
+      attr_reader :expression, :consequent
+
+      def initialize(expression:, consequent:, **)
+        @type = AbsTokenType::IF_CONDITION
+        @expression = expression
+        @consequent = consequent
+
+        super
+      end
+    end
+  end
+end