ascii_pngfy 0.2.0

data/lib/ascii_pngfy/result.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'chunky_png'
+
+module AsciiPngfy
+  # Reponsibilities
+  #   > Provides acces to Result data points, which are
+  #     - generated png as ChunkyPNG::Image instance
+  #     - render width and height
+  #     - settings snapshot that supports only setting getters
+  class Result
+    attr_reader(:png, :render_width, :render_height, :settings)
+
+    def initialize(png, render_width, render_height, settings_snapshot)
+      self.png = png
+      self.render_width = render_width
+      self.render_height = render_height
+      self.settings = settings_snapshot
+    end
+
+    private
+
+    attr_writer(:png, :render_width, :render_height, :settings)
+  end
+end

data/lib/ascii_pngfy/settings.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module AsciiPngfy
+  # Namespace that that contains Setting(s) related functionality
+  module Settings; end
+end

data/lib/ascii_pngfy/settings/color_setting.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module AsciiPngfy
+  module Settings
+    # Reponsibilities
+    #   - Keeps track of the color setting
+    #   - Validated through ColorRGBA implicitly
+    class ColorSetting
+      include SetableGetable
+
+      def initialize(initial_red, initial_green, initial_blue, initial_alpha)
+        self.color = AsciiPngfy::ColorRGBA.new(0, 0, 0, 0)
+
+        set(
+          red: initial_red,
+          green: initial_green,
+          blue: initial_blue,
+          alpha: initial_alpha
+        )
+      end
+
+      def get
+        color.dup
+      end
+
+      def set(red: nil, green: nil, blue: nil, alpha: nil)
+        color.red = red unless red.nil?
+        color.green = green unless green.nil?
+        color.blue = blue unless blue.nil?
+        color.alpha = alpha unless alpha.nil?
+
+        color.dup
+      end
+
+      def initialize_copy(original_color_setting)
+        self.color = original_color_setting.color.dup
+      end
+
+      protected
+
+      attr_accessor(:color)
+    end
+  end
+end

data/lib/ascii_pngfy/settings/font_height_setting.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module AsciiPngfy
+  module Settings
+    # Reponsibilities
+    #   - Keeps track of the font_height setting
+    #   - Validates font_height
+    class FontHeightSetting
+      include SetableGetable
+
+      def initialize(initial_font_height)
+        self.font_height = GLYPH_DESIGN_HEIGHT
+
+        set(initial_font_height)
+      end
+
+      def get
+        font_height
+      end
+
+      def set(desired_font_height)
+        validated_font_height = validate_font_height(desired_font_height)
+
+        new_font_height =
+          if multiple_of_glyph_design_height?(validated_font_height)
+            validated_font_height
+          else
+            lower_bound_distance = (validated_font_height % GLYPH_DESIGN_HEIGHT)
+            determine_bound_font_height(validated_font_height, lower_bound_distance)
+          end
+
+        self.font_height = new_font_height
+      end
+
+      private
+
+      attr_accessor(:font_height)
+
+      def font_height_valid?(some_font_height)
+        some_font_height.is_a?(Integer) && (some_font_height >= GLYPH_DESIGN_HEIGHT)
+      end
+
+      def validate_font_height(some_font_height)
+        return some_font_height if font_height_valid?(some_font_height)
+
+        error_message = String.new
+        error_message << "#{some_font_height} is not a valid font size. "
+        error_message << "Must be an Integer in the range (#{GLYPH_DESIGN_HEIGHT}..)."
+
+        raise AsciiPngfy::Exceptions::InvalidFontHeightError, error_message
+      end
+
+      def multiple_of_glyph_design_height?(number)
+        (number % GLYPH_DESIGN_HEIGHT).zero?
+      end
+
+      def lower_bound_distance?(distance)
+        [1, 2, 3, 4].include?(distance)
+      end
+
+      def higher_bound_distance?(distance)
+        [5, 6, 7, 8].include?(distance)
+      end
+
+      def determine_bound_font_height(validated_font_height, lower_bound_distance)
+        if lower_bound_distance?(lower_bound_distance)
+          (validated_font_height / GLYPH_DESIGN_HEIGHT) * GLYPH_DESIGN_HEIGHT
+        elsif higher_bound_distance?(lower_bound_distance)
+          ((validated_font_height / GLYPH_DESIGN_HEIGHT) + 1) * GLYPH_DESIGN_HEIGHT
+        end
+      end
+    end
+  end
+end

data/lib/ascii_pngfy/settings/horizontal_spacing_setting.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module AsciiPngfy
+  module Settings
+    # Reponsibilities
+    #   - Keeps track of the the horizontal_spacing setting
+    #   - Validates horizontal_spacing
+    class HorizontalSpacingSetting
+      include SetableGetable
+
+      def initialize(initial_spacing)
+        self.horizontal_spacing = 0
+
+        set(initial_spacing)
+      end
+
+      def get
+        horizontal_spacing
+      end
+
+      def set(desired_spacing)
+        validated_horizontal_spacing = validate_horizontal_spacing(desired_spacing)
+
+        self.horizontal_spacing = validated_horizontal_spacing
+      end
+
+      private
+
+      attr_accessor(:horizontal_spacing)
+
+      def horizontal_spacing_valid?(some_spacing)
+        some_spacing.is_a?(Integer) && (some_spacing >= 0)
+      end
+
+      def validate_horizontal_spacing(some_spacing)
+        return some_spacing if horizontal_spacing_valid?(some_spacing)
+
+        error_message = String.new
+        error_message << "#{some_spacing} is not a valid horizontal spacing. "
+        error_message << 'Must be an Integer in the range (0..).'
+
+        raise AsciiPngfy::Exceptions::InvalidHorizontalSpacingError, error_message
+      end
+    end
+  end
+end

data/lib/ascii_pngfy/settings/setable_getable.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module AsciiPngfy
+  module Settings
+    # Provides the interface for all the Setting implementations in a way that
+    # each inclusion of this module forces the including class to override
+    # the behaviour for #set and #get
+    #
+    # If the #get or #set method is called, but it is not overriden by the object
+    # mixing this module in, a NotImplementedError is raised
+    module SetableGetable
+      def get
+        self_class_name = self.class.to_s
+
+        expected_error_message = String.new
+        expected_error_message << "#{self_class_name}#get has not yet been implemented. "
+        expected_error_message << "Must override the #{self_class_name}#get method in order to "
+        expected_error_message << 'function as Setting.'
+
+        raise NotImplementedError, expected_error_message
+      end
+
+      def set
+        self_class_name = self.class.to_s
+
+        expected_error_message = String.new
+        expected_error_message << "#{self_class_name}#set has not yet been implemented. "
+        expected_error_message << "Must override the #{self_class_name}#set method in order to "
+        expected_error_message << 'function as Setting.'
+
+        raise NotImplementedError, expected_error_message
+      end
+    end
+  end
+end

data/lib/ascii_pngfy/settings/setable_getable_settings.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module AsciiPngfy
+  module Settings
+    # Reponsibilities
+    #   - Pipes setter and getter calls to a specific Setting instance
+    #   - Associates supported settings with the respective Setting name
+    #   - Generates a SettingsSnapshot object for the purpose of describing
+    #     a specific set of settings at the time of the snapshot generation
+    class SetableGetableSettings
+      GET = :get
+      SET = :set
+
+      def initialize
+        initialize_supported_settings
+      end
+
+      def respond_to_missing?(method_name, _)
+        setting_name = determine_setting_name_as_symbol(method_name)
+
+        setting_exists?(setting_name) || super
+      end
+
+      def method_missing(method_name, *arguments)
+        super unless respond_to?(method_name)
+
+        setting_operation = determine_operation(method_name)
+        setting_name = determine_setting_name_as_symbol(method_name)
+
+        # call the settings #set or #get method depending on the operation
+        setting(setting_name).public_send(setting_operation, *arguments)
+      end
+
+      def snapshot
+        snapshot_settings = settings.dup
+        snapshot_settings.transform_values!(&:get)
+
+        SettingsSnapshot.new(snapshot_settings)
+      end
+
+      private
+
+      attr_accessor(:settings)
+
+      def add(setting_name, setting_instance)
+        self.settings ||= {}
+
+        settings[setting_name] = setting_instance
+      end
+
+      def initialize_supported_settings
+        add(:font_color, ColorSetting.new(255, 255, 255, 255))
+        add(:background_color, ColorSetting.new(0, 0, 0, 255))
+        add(:font_height, FontHeightSetting.new(9))
+        add(:horizontal_spacing, HorizontalSpacingSetting.new(1))
+        add(:vertical_spacing, VerticalSpacingSetting.new(1))
+        add(:text, TextSetting.new(self))
+      end
+
+      def setting(setting_name)
+        settings[setting_name]
+      end
+
+      def setting_exists?(setting_name)
+        settings.key?(setting_name)
+      end
+
+      def setter?(method_name)
+        method_name.start_with?('set_')
+      end
+
+      def determine_operation(method_name)
+        setter?(method_name) ? SET : GET
+      end
+
+      def determine_setting_name_as_symbol(method_name)
+        if setter?(method_name)
+          method_name[4..]
+        else
+          method_name
+        end.to_sym
+      end
+    end
+  end
+end

data/lib/ascii_pngfy/settings/settings_snapshot.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module AsciiPngfy
+  module Settings
+    # Reponsibilities
+    #   - Keeps track of the setting values at the point of creation
+    #     of this snapshot
+    #   - Dynamic getter for each setting name which simply returns
+    #     the value of the respective setting
+    class SettingsSnapshot
+      def initialize(setting_names_and_values)
+        self.setting_names_and_values = setting_names_and_values
+      end
+
+      def respond_to_missing?(setting_name, _)
+        setting_exists?(setting_name) || super
+      end
+
+      def method_missing(setting_name, *_arguments)
+        super unless respond_to?(setting_name)
+
+        # return that settings value
+        setting_names_and_values[setting_name]
+      end
+
+      private
+
+      def setting_exists?(setting_name)
+        setting_names_and_values.key?(setting_name)
+      end
+
+      attr_accessor(:setting_names_and_values)
+    end
+  end
+end

data/lib/ascii_pngfy/settings/text_setting.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: false
+
+module AsciiPngfy
+  module Settings
+    # Reponsibilities
+    #   - Keeps track of the text and replacement_text setting
+    #   - Replaces unsupported text characters with replacement text
+    #   - Validates text and replacement_text
+    # rubocop: disable Metrics/ClassLength
+    class TextSetting
+      include SetableGetable
+
+      def initialize(settings)
+        self.settings = settings
+        self.text = ''
+
+        set('<3 Ascii-Pngfy <3')
+      end
+
+      def get
+        text.dup
+      end
+
+      # The philosophy behind this method is as follows:
+      # - The desired_text cannot be empty pre replacement. If it is an error is raised
+      #
+      # - When no replacement text is passed, the desired_text is considered as is by
+      #   skipping the replacement procedure
+      #
+      # - When a replacement text is passed though, the replacement text is validated and
+      #   all unsupported text characters are replaced with the replacement text
+      #
+      # - The text is then validated post replacement to make sure it is not empty,
+      #   the same as pre replacement
+      #
+      # - At this point the text is validated to only contain supported ASCII characters
+      #   and has its dimensions checked in terms of the needed png texture size to fit
+      #   the resulting text along with the character spacing previously set.
+      #
+      # - Finally the text setting is updated to the resulting, optionally replaced text
+      def set(desired_text, desired_replacement_text = nil)
+        pre_replacement_text_validation(desired_text, desired_replacement_text)
+
+        if replacement_desired?(desired_replacement_text)
+          desired_replacement_text = validate_replacement_text(desired_replacement_text)
+
+          desired_text = replace_unsupported_characters(from: desired_text, with: desired_replacement_text)
+        end
+
+        post_replacement_text_validation(desired_text)
+        validate_text_contents(desired_text)
+        validate_text_image_dimensions(desired_text)
+
+        # set the text to a duplicate of the original text to avoid string injection
+        self.text = desired_text.dup
+
+        desired_text
+      end
+
+      def initialize_copy(original_text_setting)
+        self.text = original_text_setting.text.dup
+      end
+
+      protected
+
+      attr_accessor(:text)
+
+      private
+
+      attr_accessor(:settings)
+
+      def character_supported?(some_character)
+        SUPPORTED_ASCII_CHARACTERS.include?(some_character)
+      end
+
+      def extract_unsupported_characters(some_string)
+        unsupported_characters = []
+
+        some_string.each_char do |some_char|
+          unsupported_characters << some_char unless character_supported?(some_char)
+        end
+
+        unsupported_characters
+      end
+
+      def string_supported?(some_string)
+        # also returns true when the string is empty, so an undesired empty string must
+        # be handled separately
+        extract_unsupported_characters(some_string).empty?
+      end
+
+      def validate_replacement_text(some_text)
+        return some_text if string_supported?(some_text)
+
+        error_message = "#{some_text.inspect} is not a valid replacement string. "\
+                        "Must contain only characters with ASCII code #{SUPPORTED_ASCII_CODES.min} "\
+                        "or in the range (#{SUPPORTED_ASCII_CODES_WITHOUT_NEWLINE_RANGE})."
+
+        raise AsciiPngfy::Exceptions::InvalidReplacementTextError, error_message
+      end
+
+      def replace_unsupported_characters(from:, with:)
+        text_with_replacements = ''
+
+        from.each_char do |text_character|
+          replacement_text = character_supported?(text_character) ? text_character : with
+          text_with_replacements << replacement_text
+        end
+
+        text_with_replacements
+      end
+
+      def replacement_desired?(replacement_text)
+        !!replacement_text
+      end
+
+      def pre_replacement_text_validation(desired_text, desired_replacement_text)
+        return desired_text unless desired_text.empty?
+
+        error_message = 'Text cannot be empty because that would result in a PNG with a width or height of zero. '\
+                        "Must contain at least one character with ASCII code #{SUPPORTED_ASCII_CODES.min} "\
+                        "or in the range (#{SUPPORTED_ASCII_CODES_WITHOUT_NEWLINE_RANGE})."
+
+        # hint the user that the desired replacement text is also empty
+        if replacement_desired?(desired_replacement_text) && desired_replacement_text.empty?
+          error_message << ' Hint: Both the text and the replacement text are empty.'
+        end
+
+        raise AsciiPngfy::Exceptions::EmptyTextError, error_message
+      end
+
+      def post_replacement_text_validation(desired_text)
+        return desired_text unless desired_text.empty?
+
+        error_message = 'Text cannot be empty because that would result in a PNG with a width or height of zero. '\
+                        "Must contain at least one character with ASCII code #{SUPPORTED_ASCII_CODES.min} "\
+                        "or in the range (#{SUPPORTED_ASCII_CODES_WITHOUT_NEWLINE_RANGE}). "\
+                        'Hint: An empty replacement text causes text with only unsupported characters to end up as '\
+                        'empty string.'
+
+        raise AsciiPngfy::Exceptions::EmptyTextError, error_message
+      end
+
+      def validate_text_contents(some_text)
+        # this method only accounts for non-empty strings that contains unsupported characters
+        # empty strings are handled separately to separate different types of errors more clearly
+        return some_text if string_supported?(some_text)
+
+        un_supported_characters = extract_unsupported_characters(some_text)
+        un_supported_inspected_characters = un_supported_characters.map(&:inspect)
+        un_supported_characters_list = "#{un_supported_inspected_characters[0..-2].join(', ')} and "\
+                                       "#{un_supported_inspected_characters.last}"
+
+        error_message = "#{un_supported_characters_list} are all invalid text characters. "\
+                        "Must contain only characters with ASCII code #{SUPPORTED_ASCII_CODES.min} "\
+                        "or in the range (#{SUPPORTED_ASCII_CODES_WITHOUT_NEWLINE_RANGE})."
+
+        raise AsciiPngfy::Exceptions::InvalidCharacterError, error_message
+      end
+
+      def validate_text_image_width(desired_text, image_width)
+        return desired_text unless image_width > AsciiPngfy::MAX_RESULT_PNG_IMAGE_WIDTH
+
+        longest_text_line = RenderingRules.longest_text_line(desired_text)
+
+        capped_text = cap_string(longest_text_line, '..', 60)
+
+        error_message = "The text line #{capped_text.inspect} is too long to be represented in a "\
+                        "#{AsciiPngfy::MAX_RESULT_PNG_IMAGE_WIDTH} pixel wide png. Hint: Use shorter "\
+                        'text lines and/or reduce the horizontal character spacing.'
+
+        raise AsciiPngfy::Exceptions::TextLineTooLongError, error_message
+      end
+
+      def validate_text_image_height(desired_text, image_height)
+        return desired_text unless image_height > AsciiPngfy::MAX_RESULT_PNG_IMAGE_HEIGHT
+
+        capped_text = cap_string(desired_text, '..', 60)
+
+        error_message = "The text #{capped_text.inspect} contains too many lines to be represented in a "\
+                        "#{MAX_RESULT_PNG_IMAGE_HEIGHT} pixel high png. Hint: Use less text lines and/or "\
+                        'reduce the vertical character spacing.'
+
+        raise AsciiPngfy::Exceptions::TooManyTextLinesError, error_message
+      end
+
+      def validate_text_image_dimensions(desired_text)
+        image_width = AsciiPngfy::RenderingRules.png_width(settings, desired_text)
+        image_height = AsciiPngfy::RenderingRules.png_height(settings, desired_text)
+
+        validate_text_image_width(desired_text, image_width)
+        validate_text_image_height(desired_text, image_height)
+      end
+
+      def cap_string(some_string, desired_separator, desired_cap_length)
+        if some_string.length <= desired_cap_length
+          some_string
+        else
+          half_cap_length = (desired_cap_length - desired_separator.length) / 2
+
+          string_beginning_portion = some_string[0, half_cap_length]
+          string_end_portion = some_string[-half_cap_length..]
+
+          "#{string_beginning_portion}#{desired_separator}#{string_end_portion}"
+        end
+      end
+    end
+  end
+  # rubocop: enable Metrics/ClassLength
+end