aoc_rb_helpers 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87b50db9a3acbc96dbf8cb70e3a3fa2f3e1341166616c3e9c29a53b6d9994201
-  data.tar.gz: 109fc954d7f8ec4d396ee76f51f22bb0289aed2ee68c2e605898c7204049c079
+  metadata.gz: e9049a2637e249afd1d2670f1b4ca3616aa21ef94ae10efb271178693ff16f63
+  data.tar.gz: 485a04d7594ef25fbec3fb2ca19060c8f5699a30fb0845ec9c985a899aae5be4
 SHA512:
-  metadata.gz: c03ddeaafa12bb07fd9c87a2d23f11d18edf593ba3ea4390dbea32d5322d0e77e1d0662e08062729f978c1cfc4e77c7437f3b9a06bb46b61bb3a876865577dbd
-  data.tar.gz: 204a9d87b4eb34b6b9ae37875d2e2b22235e585180522eae6a25dd100f326e682a3d68e0967ea9bfc258ab39fa53376322c24457b68093718a9ff93a0e26fdc5
+  metadata.gz: 6343e8180d5ab30baecad403c7765b4a666562a713154541c70ee6a602ecaa3253c08a25f89db76d36e4e86371901564b34eb7ba779fbbaa2e011cb543edf10a
+  data.tar.gz: dade32999ee76bbda52f4615cad719ab2dc4ab2209dccf88b6756b0f63d125d7dfe40b76d61e85245c599b472b29e426c5dd110b91c5c3eb46bd8ffd1ab96f84

data/CHANGELOG.md

@@ -7,11 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 - No unreleased changes!
 
+## [0.0.3]
+### Added
+- Characters `I` and `T` now supported by DotMatrix
+- Updated README with links to documentation
+- Added documentation link to gemspec
+
+## [0.0.2]
+### Added
+- DotMatrix class for decoding printed puzzle output
+
 ## [0.0.1]
 Initial release.
 
 ### Added
 - Created `AocInput` class with initial helper methods
 
-[Unreleased]: https://github.com/pacso/aoc_rb_helpers/compare/v0.0.1...HEAD
+[Unreleased]: https://github.com/pacso/aoc_rb_helpers/compare/v0.0.2...HEAD
+[0.0.2]: https://github.com/pacso/aoc_rb_helpers/compare/v0.0.1...v0.0.2
 [0.0.1]: https://github.com/pacso/aoc_rb_helpers

data/Gemfile

@@ -5,3 +5,5 @@ gemspec
 
 gem "rake", "~> 13.0"
 gem "puts_debuggerer"
+gem "yard"
+gem "webrick"

data/README.md

@@ -35,6 +35,29 @@ pd some_object
 
 You can read more on how you can use `pd` in their [README](https://github.com/AndyObtiva/puts_debuggerer/blob/master/README.md).
 
+## Provided Helper Classes
+
+All documentation is available here - https://rubydoc.info/github/pacso/aoc_rb_helpers.
+
+The provided helper classes are as follows:
+
+### [AocInput](https://rubydoc.info/github/pacso/aoc_rb_helpers/AocInput)
+Provides input manipulation helper methods. Methods are chainable, and directly modify the parsed view of the input data within the `@data` instance variable.
+
+### [DotMatrix](https://rubydoc.info/github/pacso/aoc_rb_helpers/DotMatrix)
+Parses and decodes ASCII art text from puzzles. Can output to STDOUT or return the result to your code.
+
+Will turn an input like:
+```ruby
+ XX  XXXX X    XXXX X     XX  X   XXXXX  XX   XXX
+X  X X    X    X    X    X  X X   XX    X  X X   
+X    XXX  X    XXX  X    X  X  X X XXX  X    X   
+X    X    X    X    X    X  X   X  X    X     XX 
+X  X X    X    X    X    X  X   X  X    X  X    X
+ XX  X    XXXX XXXX XXXX  XX    X  X     XX  XXX 
+```
+Into the string `CFLELOYFCS`.
+
 ## Examples
 
 Below are some examples of how you can use the features of this gem.
@@ -71,3 +94,19 @@ module Year2024
   end
 end
 ```
+
+### Decoding printed text
+
+```ruby
+text_input = <<~EOF
+  X  X XXXX X    X     XX  
+  X  X X    X    X    X  X 
+  XXXX XXX  X    X    X  X 
+  X  X X    X    X    X  X 
+  X  X X    X    X    X  X 
+  X  X XXXX XXXX XXXX  XX  
+EOF
+
+input_array = text_input.lines(chomp: true).map(&:chars)
+DotMatrix.decode(input_array) # returns the string "HELLO"
+```

data/aoc_rb_helpers.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = Gem::Requirement.new("~> 3.1", ">= 3.1.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/pacso/aoc_rb_helpers"
+  spec.metadata["documentation_uri"] = "https://rubydoc.info/github/pacso/aoc_rb_helpers"
   spec.metadata["changelog_uri"] = "https://github.com/pacso/aoc_rb_helpers/blob/main/CHANGELOG"
 
   spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
@@ -24,5 +24,5 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "aoc_rb", "~> 0.2", ">= 0.2.6"
-  spec.add_dependency "puts_debuggerer"
+  spec.add_dependency "puts_debuggerer", '~> 1.0', '>= 1.0.1'
 end

data/lib/aoc_rb_helpers/aoc_input.rb

@@ -1,35 +1,79 @@
 # frozen_string_literal: true
 
+# Provides input manipulation helper methods.
+# Methods are chainable, and directly modify the parsed view of the input data within the @data instance variable.
+#
+# Once manipulated as required, the input is accessable from #data
 class AocInput
-  def initialize(input)
-    @raw_input = input
+  # Returns a new AocInput initialized with the given puzzle input.
+  #
+  # @param puzzle_input [String] the puzzle input as a single string with embedded newline characters
+  def initialize(puzzle_input)
+    @raw_input = puzzle_input
     configure_method_access
   end
 
+  # Returns the parsed puzzle input.
+  #
+  # If the data has not been parsed yet, it defaults to the raw input provided in {initialize}.
+  #
+  # @return [Object] the parsed puzzle input
   def data
     @data ||= @raw_input
   end
 
+  # Splits the input string into an array of lines.
+  #
+  # This method processes `@data` by splitting the input string into multiple lines,
+  # removing trailing newline characters. It modifies `@data` directly and returns `self`
+  # to enable method chaining.
+  #
+  # @return [AocInput] self
   def multiple_lines
     @data = data.lines(chomp: true)
     allow(:columns_of_numbers)
+    revoke(:multiple_lines)
     self
   end
 
-  def columns_of_numbers(divider = nil)
+  # Splits each string in the data array into an array of numbers.
+  #
+  # This method processes `@data` by splitting each string in the array using the specified delimiter,
+  # then converting each resulting element to an integer. It modifies `@data` directly and enables
+  # chaining by returning `self`.
+  #
+  # @param delimiter [String, nil] the delimiter to be passed to `String#split`
+  # @raise [RuntimeError] if {#multiple_lines} has not been called
+  # @return [AocInput] self
+  def columns_of_numbers(delimiter = nil)
     can_call?(:columns_of_numbers, "call .multiple_lines first")
-    @data = data.map { |line| line.split(divider).map(&:to_i) }
+    @data = data.map { |line| line.split(delimiter).map(&:to_i) }
     allow(:sort_arrays)
     allow(:transpose)
+    revoke(:columns_of_numbers)
     self
   end
 
+  # Transposes the data array.
+  #
+  # This method can only be called after {columns_of_numbers}.
+  # It directly modifies `@data` by transposing it and returns `self` to allow method chaining.
+  #
+  # @raise [RuntimeError] if {columns_of_numbers} has not been called.
+  # @return [AocInput] self
   def transpose
     can_call?(:transpose, "call .columns_of_numbers first")
     @data = data.transpose
     self
   end
 
+  # Sorts each array within the `@data` array.
+  #
+  # This method processes `@data` by sorting each nested array in ascending order.
+  # It directly modifies `@data` and returns `self` to enable method chaining.
+  #
+  # @raise [RuntimeError] if {#columns_of_numbers} has not been called
+  # @return [AocInput] self
   def sort_arrays
     can_call?(:sort_arrays, "call .columns_of_numbers first")
     @data = data.map { |ary| ary.sort }
@@ -40,6 +84,7 @@ class AocInput
   def configure_method_access
     @can_call = {
       columns_of_numbers: false,
+      multiple_lines: true,
       sort_arrays: false,
       transpose: false
     }
@@ -49,6 +94,10 @@ class AocInput
     @can_call[method_name.to_sym] = true
   end
 
+  def revoke(method_name)
+    @can_call[method_name.to_sym] = false
+  end
+
   def can_call?(method_name, msg = "operation not permitted")
     raise RuntimeError, msg unless @can_call[method_name.to_sym]
   end

data/lib/aoc_rb_helpers/dot_matrix.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+# Parses and decodes ASCII art text from puzzles. Can output to STDOUT or return the result to your code.
+class DotMatrix
+  DICTIONARY = {
+    a: [
+      " XX ",
+      "X  X",
+      "X  X",
+      "XXXX",
+      "X  X",
+      "X  X"
+    ],
+    b: [
+      "XXX ",
+      "X  X",
+      "XXX ",
+      "X  X",
+      "X  X",
+      "XXX "
+    ],
+    c: [
+      " XX ",
+      "X  X",
+      "X   ",
+      "X   ",
+      "X  X",
+      " XX "
+    ],
+    d: [
+      "XXX ",
+      "X  X",
+      "X  X",
+      "X  X",
+      "X  X",
+      "XXX "
+    ],
+    e: [
+      "XXXX",
+      "X   ",
+      "XXX ",
+      "X   ",
+      "X   ",
+      "XXXX"
+    ],
+    f: [
+      "XXXX",
+      "X   ",
+      "XXX ",
+      "X   ",
+      "X   ",
+      "X   "
+    ],
+    g: [
+      " XX ",
+      "X  X",
+      "X   ",
+      "X XX",
+      "X  X",
+      " XXX"
+    ],
+    h: [
+      "X  X",
+      "X  X",
+      "XXXX",
+      "X  X",
+      "X  X",
+      "X  X",
+    ],
+    i: [
+      "XXX",
+      " X ",
+      " X ",
+      " X ",
+      " X ",
+      "XXX"
+    ],
+    j: [
+      "  XX",
+      "   X",
+      "   X",
+      "   X",
+      "X  X",
+      " XX ",
+    ],
+    k: [
+      "X  X",
+      "X X ",
+      "XX  ",
+      "X X ",
+      "X X ",
+      "X  X",
+    ],
+    l: [
+      "X   ",
+      "X   ",
+      "X   ",
+      "X   ",
+      "X   ",
+      "XXXX",
+    ],
+    o: [
+      " XX ",
+      "X  X",
+      "X  X",
+      "X  X",
+      "X  X",
+      " XX "
+    ],
+    p: [
+      "XXX ",
+      "X  X",
+      "X  X",
+      "XXX ",
+      "X   ",
+      "X   ",
+    ],
+    r: [
+      "XXX ",
+      "X  X",
+      "X  X",
+      "XXX ",
+      "X X ",
+      "X  X",
+    ],
+    s: [
+      " XXX",
+      "X   ",
+      "X   ",
+      " XX ",
+      "   X",
+      "XXX ",
+    ],
+    t: [
+      "XXX",
+      " X ",
+      " X ",
+      " X ",
+      " X ",
+      " X "
+    ],
+    u: [
+      "X  X",
+      "X  X",
+      "X  X",
+      "X  X",
+      "X  X",
+      " XX ",
+    ],
+    y: [
+      "X   X",
+      "X   X",
+      " X X ",
+      "  X  ",
+      "  X  ",
+      "  X  "
+    ],
+    z: [
+      "XXXX",
+      "   X",
+      "  X ",
+      " X  ",
+      "X   ",
+      "XXXX",
+    ]
+  }
+
+  # Returns the decoded input using the specified characters for printed text (on) and whitespace (off).
+  # @param [Array<Array<String>>] input a two-dimensional array of characters
+  # @param on [String] specifies the character representing the "on" state, or printed text
+  # @param off [String] specifies the character representing the "off" state, or whitespace
+  # @return [String] the decoded string
+  def self.decode(input, on: "X", off: " ")
+    new(input, on, off).to_s
+  end
+
+  # @param [Array<Array<String>>] input a two-dimensional array of characters
+  # @param on [String] specifies the character representing the "on" state, or printed text
+  # @param off [String] specifies the character representing the "off" state, or whitespace
+  def initialize(input, on = "X", off = " ")
+    @input = input
+    @on = on
+    @off = off
+
+    convert_characters
+  end
+
+  # Prints the input array to STDOUT and returns self.
+  # @return [DotMatrix] self
+  def print(input = @input)
+    input.each do |row|
+      puts row.is_a?(String) ? row : row.join
+    end
+    self
+  end
+
+  # Prints the decoded input to STDOUT and returns self.
+  # @return [DotMatrix] self
+  def print_decoded
+    puts to_s
+    self
+  end
+
+  # Returns the decoded input.
+  # @return [String] the decoded input
+  def to_s
+    cursor = 0
+    decoded = ""
+    while cursor < max_cursor
+      begin
+        cursor += 1 while @input.all? { |row| row[cursor] == ' ' }
+        cursor_end = cursor_range(cursor)
+        char_map = @input.map do |row|
+          row[cursor...cursor_end].join
+        end
+        cursor = cursor_end
+
+        decoded += DICTIONARY.find { |_, map| map == char_map }[0].to_s.upcase
+      rescue NoMethodError
+        puts "ERROR: Missing character in dictionary:\n\n"
+        print(char_map)
+        puts "\nReverting to ASCII:\n\n"
+        print
+        break
+      end
+    end
+
+    decoded
+  end
+
+  private
+
+  def convert_characters
+    unless @on == "X" && @off == " "
+      @input = @input.map do |row|
+        row.map do |cell|
+          cell == @on ? "X" : " "
+        end
+      end
+    end
+  end
+
+  def cursor_range(cursor)
+    c = cursor
+    c += 1 while @input.any? { |row| row[c] != ' ' } && c - cursor < max_cursor_range
+    c
+  end
+
+  def max_cursor
+    @input.first.length - 4
+  end
+
+  def max_cursor_range
+    DICTIONARY.values.map { |v| v.first.length }.max
+  end
+end

data/lib/aoc_rb_helpers/version.rb

@@ -1,3 +1,3 @@
 module AocRbHelpers
-  VERSION = "0.0.1"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: aoc_rb_helpers
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Jon Pascoe
@@ -34,16 +34,22 @@ dependencies:
   name: puts_debuggerer
   requirement: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.1
 description: Enhances the aoc_rb gem with tools for parsing puzzle input, and handling
   various data manipulations within Advent of Code puzzle solutions.
 email:
@@ -63,6 +69,7 @@ files:
 - aoc_rb_helpers.gemspec
 - lib/aoc_rb_helpers.rb
 - lib/aoc_rb_helpers/aoc_input.rb
+- lib/aoc_rb_helpers/dot_matrix.rb
 - lib/aoc_rb_helpers/solution/input_handling.rb
 - lib/aoc_rb_helpers/version.rb
 homepage: https://github.com/pacso/aoc_rb_helpers
@@ -70,7 +77,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/pacso/aoc_rb_helpers
-  source_code_uri: https://github.com/pacso/aoc_rb_helpers
+  documentation_uri: https://rubydoc.info/github/pacso/aoc_rb_helpers
   changelog_uri: https://github.com/pacso/aoc_rb_helpers/blob/main/CHANGELOG
 post_install_message:
 rdoc_options: []