slideck 0.1.0

data/lib/slideck/margin.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+module Slideck
+  # Responsible for accessing margin configuration
+  #
+  # @api private
+  class Margin
+    # The pattern to validate input contains only integers
+    #
+    # @return [Regexp]
+    #
+    # @api private
+    INTEGERS_ONLY_PATTERN = /^[\d, ]+$/.freeze
+    private_constant :INTEGERS_ONLY_PATTERN
+
+    # The pattern to detect integers separator
+    #
+    # @return [Regexp]
+    #
+    # @api private
+    INTEGERS_SEPARATOR = /[ ,]+/.freeze
+    private_constant :INTEGERS_SEPARATOR
+
+    # The allowed margin side names
+    #
+    # @return [Array<Symbol>]
+    #
+    # @api private
+    SIDE_NAMES = %i[top right bottom left].freeze
+    private_constant :SIDE_NAMES
+
+    # Create a Margin instance from a value
+    #
+    # @example
+    #   Slideck::Margin.from(1)
+    #
+    # @example
+    #   Slideck::Margin.from([1, 2])
+    #
+    # @example
+    #   Slideck::Margin.from({top: 1, left: 2})
+    #
+    # @example
+    #   Slideck::Margin.from("1, 2")
+    #
+    # @param [Object] value
+    #   the value to create a margin from
+    #
+    # @raise [Slideck::InvalidArgumentError]
+    #
+    # @return [Slideck::Margin]
+    #
+    # @api public
+    def self.from(value)
+      if value.is_a?(Hash)
+        from_hash(value)
+      elsif (converted = convert_to_array(value))
+        from_array(converted)
+      else
+        raise_invalid_margin_error(value)
+      end
+    end
+
+    # Create a Margin instance with an array-like initialiser
+    #
+    # @example
+    #   Slideck::Margin[1, 2]
+    #
+    # @example
+    #   Slideck::Margin[1, 2, 3, 4]
+    #
+    # @param [Array<Integer>] values
+    #   the values to convert to a margin
+    #
+    # @return [Slideck::Margin]
+    #
+    # @api public
+    def self.[](*values)
+      from_array(values)
+    end
+
+    # Create a Margin instance from an array
+    #
+    # @example
+    #   Slideck::Margin.from_array([1, 2])
+    #
+    # @param [Array] value
+    #   the value to convert to a margin
+    #
+    # @raise [Slideck::InvalidArgumentError]
+    #
+    # @return [Slideck::Margin]
+    #
+    # @api public
+    def self.from_array(value)
+      case value.size
+      when 1 then new(*(value * 4))
+      when 2 then new(*(value * 2))
+      when 3 then new(*value, value[1])
+      when 4 then new(*value)
+      else raise_invalid_margin_as_array_error(value)
+      end
+    end
+
+    # Create a Margin instance from a hash
+    #
+    # @example
+    #   Slideck::Margin.from_hash{top: 1, left: 2})
+    #
+    # @param [Hash] value
+    #   the hash value to convert to a margin
+    #
+    # @raise [Slideck::InvalidArgumentError]
+    #
+    # @return [Slideck::Margin]
+    #
+    # @api public
+    def self.from_hash(value)
+      unless (invalid = (value.keys - SIDE_NAMES)).empty?
+        raise_invalid_margin_as_hash_error(invalid)
+      end
+
+      new(*value.values_at(*SIDE_NAMES).map { |val| val.nil? ? 0 : val })
+    end
+
+    # Convert a value into an array
+    #
+    # @param [Object] value
+    #   the value to convert into an array
+    #
+    # @return [Array<Integer>, nil]
+    #
+    # @api private
+    def self.convert_to_array(value)
+      if value.is_a?(Numeric)
+        [value]
+      elsif value.is_a?(String) && value =~ INTEGERS_ONLY_PATTERN
+        value.split(INTEGERS_SEPARATOR).map(&:to_i)
+      elsif value.is_a?(Array)
+        value
+      end
+    end
+    private_class_method :convert_to_array
+
+    # Raise an error when the value is invalid
+    #
+    # @param [Object] value
+    #   the invalid value
+    #
+    # @raise [Slideck::InvalidArgumentError]
+    #
+    # @return [void]
+    #
+    # @api private
+    def self.raise_invalid_margin_error(value)
+      raise InvalidArgumentError,
+            "invalid value for margin: #{value.inspect}.\n" \
+            "The margin needs to be an integer, a string of " \
+            "integers, an array of integers or " \
+            "a hash of side names and integer values."
+    end
+    private_class_method :raise_invalid_margin_error
+
+    # Raise an error when the array has a wrong number of values
+    #
+    # @param [Array<Integer>] values
+    #   the margin values
+    #
+    # @raise [Slideck::InvalidArgumentError]
+    #
+    # @return [void]
+    #
+    # @api private
+    def self.raise_invalid_margin_as_array_error(values)
+      raise InvalidArgumentError,
+            "wrong number of integers for margin: " \
+            "#{values.join(", ").inspect}.\n" \
+            "The margin needs to be specified with one, two, three " \
+            "or four integers."
+    end
+    private_class_method :raise_invalid_margin_as_array_error
+
+    # Raise an error when the hash has an invalid side name
+    #
+    # @param [Array] invalid_sides
+    #   the invalid side names
+    #
+    # @raise [Slideck::InvalidArgumentError]
+    #
+    # @return [void]
+    #
+    # @api private
+    def self.raise_invalid_margin_as_hash_error(invalid_sides)
+      raise InvalidArgumentError,
+            "unknown name#{"s" if invalid_sides.size > 1} for margin: " \
+            "#{invalid_sides.map(&:inspect).join(", ")}.\n" \
+            "Valid names are: top, left, right and bottom."
+    end
+    private_class_method :raise_invalid_margin_as_hash_error
+
+    # The bottom margin
+    #
+    # @example
+    #   margin.bottom
+    #
+    # @return [Integer]
+    #
+    # @api public
+    attr_reader :bottom
+
+    # The left margin
+    #
+    # @example
+    #   margin.left
+    #
+    # @return [Integer]
+    #
+    # @api public
+    attr_reader :left
+
+    # The right margin
+    #
+    # @example
+    #   margin.right
+    #
+    # @return [Integer]
+    #
+    # @api public
+    attr_reader :right
+
+    # The top margin
+    #
+    # @example
+    #   margin.top
+    #
+    # @return [Integer]
+    #
+    # @api public
+    attr_reader :top
+
+    # Create a Margin instance
+    #
+    # @param [Integer] top
+    #   the top margin
+    # @param [Integer] right
+    #   the right margin
+    # @param [Integer] bottom
+    #   the bottom margin
+    # @param [Integer] left
+    #   the left margin
+    #
+    # @api private
+    def initialize(top, right, bottom, left)
+      @top = validate_margin_side(:top, top)
+      @right = validate_margin_side(:right, right)
+      @bottom = validate_margin_side(:bottom, bottom)
+      @left = validate_margin_side(:left, left)
+
+      freeze
+    end
+    private_class_method :new
+
+    # Determine equivalence with another object
+    #
+    # @example
+    #   margin == other
+    #
+    # @param [Object] other
+    #   the other object to determine equivalence with
+    #
+    # @return [Boolean]
+    #   true if this object is equivalent to the other, false otherwise
+    #
+    # @api public
+    def ==(other)
+      other.is_a?(self.class) &&
+        top == other.top && right == other.right &&
+        bottom == other.bottom && left == other.left
+    end
+
+    # Determine for equality with another object
+    #
+    # @example
+    #   margin.eql?(other)
+    #
+    # @param [Object] other
+    #   the other object to determine equality with
+    #
+    # @return [Boolean]
+    #   true if this object is equal to the other, false otherwise
+    #
+    # @api public
+    def eql?(other)
+      instance_of?(other.class) &&
+        top.eql?(other.top) && right.eql?(other.right) &&
+        bottom.eql?(other.bottom) && left.eql?(other.left)
+    end
+
+    # Generate hash value of this margin
+    #
+    # @example
+    #   margin.hash
+    #
+    # @return [Integer]
+    #
+    # @api public
+    def hash
+      [self.class, top, right, bottom, left].hash
+    end
+
+    # An array representation of all margin sides
+    #
+    # @example
+    #   margin = Slideck::Margin[1, 2, 3, 4]
+    #   margin.to_a # => [1, 2, 3, 4]
+    #
+    # @return [Array<Integer, Integer, Integer, Integer>]
+    #
+    # @api public
+    def to_a
+      [top, right, bottom, left]
+    end
+
+    private
+
+    # Validate margin side
+    #
+    # @param [Symbol] side
+    #   the margin side
+    # @param [Object] value
+    #   the value to validate
+    #
+    # @raise [Slideck::InvalidArgumentError]
+    #
+    # @return [Integer]
+    #
+    # @api private
+    def validate_margin_side(side, value)
+      return value if value.is_a?(Integer)
+
+      raise InvalidArgumentError,
+            "#{side} margin needs to be an integer, got: #{value.inspect}"
+    end
+  end # Margin
+end # Slideck

data/lib/slideck/metadata.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Slideck
+  # Responsible for accessing metadata configuration
+  #
+  # @api private
+  class Metadata
+    # Create a Metadata instance from slides configuration
+    #
+    # @param [Slideck::MetadataConverter] metadata_converter
+    #   the metadata converter
+    # @param [Hash{Symbol => Object}] custom_metadata
+    #   the custom metadata
+    # @param [MetadataDefaults] metadata_defaults
+    #   the metadata defaults
+    #
+    # @raise [Slideck::InvalidMetadataKeyError]
+    #
+    # @return [Slideck::Metadata]
+    #
+    # @api public
+    def self.from(metadata_converter, custom_metadata, metadata_defaults)
+      validate_keys(custom_metadata.keys)
+
+      new(metadata_defaults.merge(metadata_converter.convert(custom_metadata)))
+    end
+
+    # Check for unknown metadata keys
+    #
+    # @param [Array<Symbol>] custom_metadata_keys
+    #   the custom metadata keys
+    #
+    # @raise [Slideck::InvalidMetadataKeyError]
+    #
+    # @return [nil]
+    #
+    # @api private
+    def self.validate_keys(custom_metadata_keys)
+      unknown_keys = custom_metadata_keys - @metadata_keys
+      return if unknown_keys.empty?
+
+      raise InvalidMetadataKeyError.new(@metadata_keys, unknown_keys)
+    end
+    private_class_method :validate_keys
+
+    # Define a method to access metadata
+    #
+    # @param [Symbol] key
+    #   the metadata key name
+    #
+    # @return [void]
+    #
+    # @api private
+    def self.define_meta(key)
+      define_method(key) { @metadata[key] }
+      (@metadata_keys ||= []) << key
+    end
+    private_class_method :define_meta
+
+    # The alignment configuration
+    #
+    # @return [Slideck::Alignment]
+    define_meta :align
+
+    # The footer configuration
+    #
+    # @return [Hash{Symbol => Slideck::Alignment,String}]
+    define_meta :footer
+
+    # The margin configuration
+    #
+    # @return [Slideck::Margin]
+    define_meta :margin
+
+    # The pager configuration
+    #
+    # @return [Hash{Symbol => Slideck::Alignment,String}]
+    define_meta :pager
+
+    # The symbols configuration
+    #
+    # @return [Hash, String, Symbol]
+    define_meta :symbols
+
+    # The theme configuration
+    #
+    # @return [Hash{Symbol => Array, String, Symbol}]
+    define_meta :theme
+
+    # Create a Metadata instance
+    #
+    # @param [Hash{Symbol => Object}] metadata
+    #   the metadata configuration
+    #
+    # @api private
+    def initialize(metadata)
+      @metadata = metadata
+
+      freeze
+    end
+    private_class_method :new
+
+    # Determine equivalence with another object
+    #
+    # @example
+    #   metadata == other
+    #
+    # @param [Object] other
+    #   the other object to determine equivalence with
+    #
+    # @return [Boolean]
+    #   true if this object is equivalent to the other, false otherwise
+    #
+    # @api public
+    def ==(other)
+      other.is_a?(self.class) &&
+        @metadata.keys.all? do |name|
+          send(name) == other.send(name)
+        end
+    end
+
+    # Determine equality with another object
+    #
+    # @example
+    #   metadata.eql?(other)
+    #
+    # @param [Object] other
+    #   the other object to determine equality with
+    #
+    # @return [Boolean]
+    #   true if this object is equal to the other, false otherwise
+    #
+    # @api public
+    def eql?(other)
+      instance_of?(other.class) &&
+        @metadata.keys.all? do |name|
+          send(name).eql?(other.send(name))
+        end
+    end
+
+    # Generate hash value of this metadata
+    #
+    # @example
+    #   metadata.hash
+    #
+    # @return [Integer]
+    #
+    # @api public
+    def hash
+      [self.class, *@metadata.keys.map { |name| send(name) }].hash
+    end
+  end # Metadata
+end # Slideck

data/lib/slideck/metadata_converter.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Slideck
+  # Responsible for converting custom metadata
+  #
+  # @api private
+  class MetadataConverter
+    # Create a MetadataConverter instance
+    #
+    # @example
+    #   Slideck::MetadataConverter.new(Slideck::Alignment)
+    #
+    # @param [Slideck::Alignment] alignment
+    #   the alignment initialiser
+    # @param [Slideck::Margin] margin
+    #   the margin initialiser
+    #
+    # @api public
+    def initialize(alignment, margin)
+      @alignment = alignment
+      @margin = margin
+    end
+
+    # Convert metadata values
+    #
+    # @example
+    #   metadata_converter.convert({align: "center"})
+    #
+    # @param [Hash{Symbol => Object}] custom_metadata
+    #   the custom metadata to convert
+    #
+    # @return [Hash{Symbol => Object}]
+    #
+    # @api public
+    def convert(custom_metadata)
+      custom_metadata.each_with_object({}) do |(key, val), new_metadata|
+        new_metadata[key] = convert_for(key, val)
+      end
+    end
+
+    private
+
+    # Convert a value for a metadata key
+    #
+    # @param [Symbol] key
+    #   the metadata key
+    # @param [Object] value
+    #   the metadata value
+    #
+    # @return [Hash, Slideck::Alignment, Slideck::Margin, String, Symbol]
+    #
+    # @api private
+    def convert_for(key, value)
+      case key
+      when :align
+        @alignment.from(value)
+      when :margin
+        @margin.from(value)
+      when :footer, :pager
+        convert_align_key(wrap_with_text_key(value), "bottom")
+      else
+        value
+      end
+    end
+
+    # Wrap value in Hash with text key
+    #
+    # @param [Hash, String] value
+    #   the value to wrap with text key
+    #
+    # @return [Hash{Symbol => String}]
+    #
+    # @api private
+    def wrap_with_text_key(value)
+      value.is_a?(::Hash) ? value : {text: value || ""}
+    end
+
+    # Convert value for align key in Hash to Alignment
+    #
+    # @param [Hash] value
+    #   the value with align key
+    # @param [String] default
+    #   the default vertical alignment
+    #
+    # @return [Hash{Symbol => Slideck::Alignment,String}]
+    #
+    # @api private
+    def convert_align_key(value, default)
+      return value unless value.key?(:align)
+
+      alignment = @alignment.from(value[:align], default: default)
+      value.merge(align: alignment)
+    end
+  end # MetadataConverter
+end # Slideck

data/lib/slideck/metadata_defaults.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Slideck
+  # Default metadata configuration
+  #
+  # @api private
+  class MetadataDefaults
+    # Create a MetadataDefaults instance
+    #
+    # @example
+    #   Slideck::MetadataDefaults.new(Slideck::Alignment)
+    #
+    # @param [Slideck::Alignment] alignment
+    #   the alignment initialiser
+    # @param [Slideck::Margin] margin
+    #   the margin initialiser
+    #
+    # @api public
+    def initialize(alignment, margin)
+      @alignment = alignment
+      @margin = margin
+      @defaults = create_defaults
+    end
+
+    # Merge given custom metadata with defaults
+    #
+    # @example
+    #   metadata_defaults.merge({align: "center"})
+    #
+    # @param [Hash{Symbol => Object}] custom_metadata
+    #   the custom metadata to merge
+    #
+    # @return [Hash{Symbol => Object}]
+    #
+    # @api public
+    def merge(custom_metadata)
+      @defaults.merge(custom_metadata) do |_, def_val, val|
+        def_val.is_a?(::Hash) ? def_val.merge(val) : val
+      end
+    end
+
+    private
+
+    # The default metadata configuration
+    #
+    # @return [Hash{Symbol => Object}]
+    #
+    # @api private
+    def create_defaults
+      {
+        align: @alignment["left", "top"],
+        footer: default_footer,
+        margin: @margin[0, 0, 0, 0],
+        pager: default_pager,
+        symbols: :unicode,
+        theme: {}
+      }.freeze
+    end
+
+    # The default footer configuration
+    #
+    # @return [Hash{Symbol => Slideck::Alignment,String}]
+    #
+    # @api private
+    def default_footer
+      {
+        align: @alignment["left", "bottom"],
+        text: ""
+      }.freeze
+    end
+
+    # The default pager configuration
+    #
+    # @return [Hash{Symbol => Slideck::Alignment,String}]
+    #
+    # @api private
+    def default_pager
+      {
+        align: @alignment["right", "bottom"],
+        text: "%<page>d / %<total>d"
+      }.freeze
+    end
+  end # MetadataDefaults
+end # Slideck