command_kit 0.2.2 → 0.4.0

data/lib/command_kit/printing/tables/border_style.rb

@@ -0,0 +1,169 @@
+module CommandKit
+  module Printing
+    module Tables
+      #
+      # Represents the table's border style.
+      #
+      # @api private
+      #
+      class BorderStyle
+
+        # The top-left-corner border character.
+        #
+        # @return [String]
+        attr_reader :top_left_corner
+
+        # The top-border character.
+        #
+        # @return [String]
+        attr_reader :top_border
+
+        # The top-joined-border character.
+        #
+        # @return [String]
+        attr_reader :top_joined_border
+
+        # The top-right-corner border character.
+        #
+        # @return [String]
+        attr_reader :top_right_corner
+
+        # The left-hand-side border character.
+        #
+        # @return [String]
+        attr_reader :left_border
+
+        # The left-hand-side-joined-border character.
+        #
+        # @return [String]
+        attr_reader :left_joined_border
+
+        # The horizontal-separator character.
+        #
+        # @return [String]
+        attr_reader :horizontal_separator
+
+        # The vertical-separator character.
+        #
+        # @return [String]
+        attr_reader :vertical_separator
+
+        # The inner-joined border character.
+        #
+        # @return [String]
+        attr_reader :inner_joined_border
+
+        # The right-hand-side border character.
+        #
+        # @return [String]
+        attr_reader :right_border
+
+        # The right-hand-side joined border character.
+        #
+        # @return [String]
+        attr_reader :right_joined_border
+
+        # The bottom border character.
+        #
+        # @return [String]
+        attr_reader :bottom_border
+
+        # The bottom-left-corner border character.
+        #
+        # @return [String]
+        attr_reader :bottom_left_corner
+
+        # The bottom-joined border character.
+        #
+        # @return [String]
+        attr_reader :bottom_joined_border
+
+        # The bottom-right-corner border character.
+        #
+        # @return [String]
+        attr_reader :bottom_right_corner
+
+        #
+        # Initializes the border style.
+        #
+        # @param [String] top_left_corner
+        #   The top-left-corner border character.
+        #
+        # @param [String] top_border
+        # The top-border character.
+        #
+        # @param [String] top_joined_border
+        #   The top-joined-border character.
+        #
+        # @param [String] top_right_corner
+        #   The top-right-corner border character.
+        #
+        # @param [String] left_border
+        #   The left-hand-side border character.
+        #
+        # @param [String] left_joined_border
+        #   The left-hand-side-joined-border character.
+        #
+        # @param [String] horizontal_separator
+        #   The horizontal-separator character.
+        #
+        # @param [String] vertical_separator
+        #   The vertical-separator character.
+        #
+        # @param [String] inner_joined_border
+        #   The inner-joined border character.
+        #
+        # @param [String] right_border
+        #   The right-hand-side border character.
+        #
+        # @param [String] right_joined_border
+        #   The right-hand-side joined border character.
+        #
+        # @param [String] bottom_border
+        #   The bottom border character.
+        #
+        # @param [String] bottom_left_corner
+        #   The bottom-left-corner border character.
+        #
+        # @param [String] bottom_joined_border
+        #   The bottom-joined border character.
+        #
+        # @param [String] bottom_right_corner
+        #   The bottom-right-corner border character.
+        #
+        def initialize(top_left_corner:      ' ',
+                       top_border:           ' ',
+                       top_joined_border:    ' ',
+                       top_right_corner:     ' ',
+                       left_border:          ' ',
+                       left_joined_border:   ' ',
+                       horizontal_separator: ' ',
+                       vertical_separator:   ' ',
+                       inner_joined_border:  ' ',
+                       right_border:         ' ',
+                       right_joined_border:  ' ',
+                       bottom_border:        ' ',
+                       bottom_left_corner:   ' ',
+                       bottom_joined_border: ' ',
+                       bottom_right_corner:  ' ')
+          @top_left_corner      = top_left_corner
+          @top_border           = top_border
+          @top_joined_border    = top_joined_border
+          @top_right_corner     = top_right_corner
+          @left_border          = left_border
+          @left_joined_border   = left_joined_border
+          @horizontal_separator = horizontal_separator
+          @vertical_separator   = vertical_separator
+          @inner_joined_border  = inner_joined_border
+          @right_border         = right_border
+          @right_joined_border  = right_joined_border
+          @bottom_border        = bottom_border
+          @bottom_left_corner   = bottom_left_corner
+          @bottom_joined_border = bottom_joined_border
+          @bottom_right_corner  = bottom_right_corner
+        end
+
+      end
+    end
+  end
+end

data/lib/command_kit/printing/tables/cell_builder.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module CommandKit
+  module Printing
+    module Tables
+      #
+      # Build's a cell and calculates it's dimensions.
+      #
+      # @api private
+      #
+      class CellBuilder
+
+        # The lines within the cell.
+        #
+        # @return [Array<String>]
+        attr_reader :lines
+
+        # The height (in lines) of the cell.
+        #
+        # @return [Integer]
+        attr_reader :height
+
+        # The with (in characters) of the cell.
+        #
+        # @return [Integer]
+        attr_reader :width
+
+        #
+        # Initializes the cell.
+        #
+        # @param [#to_s] value
+        #   The value for the cell.
+        #
+        def initialize(value=nil)
+          @lines  = []
+          @height = 0
+          @width  = 0
+
+          if value
+            value.to_s.each_line(chomp: true) do |line|
+              self << line
+            end
+          end
+        end
+
+        #
+        # Calculates the width of a string, sans any ASNI escape sequences.
+        #
+        # @param [String] string
+        #   The string to calculate the width of.
+        #
+        # @return [Integer]
+        #   The display width of the string.
+        #
+        def self.line_width(string)
+          string.gsub(/\e\[\d+m/,'').length
+        end
+
+        #
+        # Adds a line to the cell.
+        #
+        # @param [String] line
+        #   A line to add to the cell.
+        #
+        # @return [self]
+        #
+        def <<(line)
+          line_width = self.class.line_width(line)
+
+          @height += 1
+          @width   = line_width if line_width > @width
+
+          @lines << line
+          return self
+        end
+
+        #
+        # Fetches a line from the cell.
+        #
+        # @param [Integer] line_index
+        #   The line index to fetch.
+        #
+        # @return [String]
+        #   The line at the line index or an empty String if the cell is empty.
+        #
+        def [](line_index)
+          @lines.fetch(line_index,'')
+        end
+
+      end
+    end
+  end
+end

data/lib/command_kit/printing/tables/row_builder.rb

@@ -0,0 +1,111 @@
+require 'command_kit/printing/tables/cell_builder'
+
+module CommandKit
+  module Printing
+    module Tables
+      #
+      # Builds a table row and calculates it's dimensions.
+      #
+      # @api private
+      #
+      class RowBuilder
+
+        include Enumerable
+
+        # The cells within the row.
+        #
+        # @return [Array<CellBuilder>]
+        attr_reader :cells
+
+        # The height (in lines) for the row.
+        #
+        # @return [Integer]
+        attr_reader :height
+
+        # The width (in characters) for the row.
+        #
+        # @return [Integer]
+        attr_reader :width
+
+        # The number of columns in the row.
+        #
+        # @return [Integer]
+        attr_reader :columns
+
+        #
+        # Initializes the row.
+        #
+        # @param [Array, nil] cells
+        #   The cells for the row.
+        #
+        def initialize(cells=nil)
+          @cells = []
+
+          @height = 0
+          @width  = 0
+
+          @columns = 0
+
+          if cells
+            cells.each { |value| self << value }
+          end
+        end
+
+        # An empty cell.
+        EMPTY_CELL = CellBuilder.new
+
+        #
+        # Appends a value to the row.
+        #
+        # @param [#to_s] value
+        #   The cell value to add to the row.
+        #
+        # @return [self]
+        #
+        def <<(value)
+          new_cell = if value then CellBuilder.new(value)
+                     else          EMPTY_CELL
+                     end
+
+          @height   = new_cell.height if new_cell.height > @height
+          @width   += new_cell.width
+          @columns += 1
+
+          @cells << new_cell
+          return self
+        end
+
+        #
+        # Fetches a cell from the row.
+        #
+        # @param [Integer] column_index
+        #   The column index.
+        #
+        # @return [CellBuilder]
+        #   The cell at the given column index or an empty cell if the row
+        #   does not have a cell at the given column index.
+        #
+        def [](column_index)
+          @cells.fetch(column_index,EMPTY_CELL)
+        end
+
+        #
+        # Enumerates over each cell in the row.
+        #
+        # @yield [cell]
+        #   The given block will be passed each cell within the row.
+        #
+        # @yieldparam [CellBuilder] cell
+        #   A cell within the row.
+        #
+        # @return [Enumerator]
+        #   If no block is given, an Enumerator will be returned.
+        #
+        def each(&block)
+          @cells.each(&block)
+        end
+
+      end
+    end
+  end
+end

data/lib/command_kit/printing/tables/style.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require 'command_kit/printing/tables/border_style'
+
+module CommandKit
+  module Printing
+    module Tables
+      #
+      # Contains the table's style configuration.
+      #
+      # @api private
+      #
+      class Style
+
+        # Built-in border styles.
+        BORDER_STYLES = {
+          ascii: BorderStyle.new(
+            top_left_corner:      '+',
+            top_border:           '-',
+            top_joined_border:    '+',
+            top_right_corner:     '+',
+            left_border:          '|',
+            left_joined_border:   '+',
+            horizontal_separator: '-',
+            vertical_separator:   '|',
+            inner_joined_border:  '+',
+            right_border:         '|',
+            right_joined_border:  '+',
+            bottom_border:        '-',
+            bottom_left_corner:   '+',
+            bottom_joined_border: '+',
+            bottom_right_corner:  '+'
+          ),
+
+          line: BorderStyle.new(
+            top_left_corner:      '┌',
+            top_border:           '─',
+            top_joined_border:    '┬',
+            top_right_corner:     '┐',
+            left_border:          '│',
+            left_joined_border:   '├',
+            horizontal_separator: '─',
+            vertical_separator:   '│',
+            inner_joined_border:  '┼',
+            right_border:         '│',
+            right_joined_border:  '┤',
+            bottom_border:        '─',
+            bottom_left_corner:   '└',
+            bottom_joined_border: '┴',
+            bottom_right_corner:  '┘'
+          ),
+
+          double_line: BorderStyle.new(
+            top_left_corner:      '╔',
+            top_border:           '═',
+            top_joined_border:    '╦',
+            top_right_corner:     '╗',
+            left_border:          '║',
+            left_joined_border:   '╠',
+            horizontal_separator: '═',
+            vertical_separator:   '║',
+            inner_joined_border:  '╬',
+            right_border:         '║',
+            right_joined_border:  '╣',
+            bottom_border:        '═',
+            bottom_left_corner:   '╚',
+            bottom_joined_border: '╩',
+            bottom_right_corner:  '╝'
+          )
+        }
+
+        # The border style.
+        #
+        # @return [BorderStyle]
+        attr_reader :border
+
+        # The padding to use for cells.
+        #
+        # @return [Integer]
+        attr_reader :padding
+
+        # The justification to use for cells.
+        #
+        # @return [:left, :right, :center]
+        attr_reader :justify
+
+        # The justification to use for header cells.
+        #
+        # @return [:left, :right, :center]
+        attr_reader :justify_header
+
+        # Specifies whether to separate rows with a border row.
+        #
+        # @return [Boolean]
+        attr_reader :separate_rows
+
+        #
+        # Initializes the style.
+        #
+        # @param [:line, :double_line, nil, Hash{Symbol => String}, :ascii] border
+        #   The border style or a custom Hash of border characters.
+        #
+        # @option border [String] :top_left_corner (' ')
+        #   The top-left-corner border character.
+        #
+        # @option border [String] :top_border (' ')
+        # The top-border character.
+        #
+        # @option border [String] :top_joined_border (' ')
+        #   The top-joined-border character.
+        #
+        # @option border [String] :top_right_corner (' ')
+        #   The top-right-corner border character.
+        #
+        # @option border [String] :left_border (' ')
+        #   The left-hand-side border character.
+        #
+        # @option border [String] :left_joined_border (' ')
+        #   The left-hand-side-joined-border character.
+        #
+        # @option border [String] :horizontal_separator (' ')
+        #   The horizontal-separator character.
+        #
+        # @option border [String] :vertical_separator (' ')
+        #   The vertical-separator character.
+        #
+        # @option border [String] :inner_joined_border (' ')
+        #   The inner-joined border character.
+        #
+        # @option border [String] :right_border (' ')
+        #   The right-hand-side border character.
+        #
+        # @option border [String] :right_joined_border (' ')
+        #   The right-hand-side joined border character.
+        #
+        # @option border [String] :bottom_border (' ')
+        #   The bottom border character.
+        #
+        # @option border [String] :bottom_left_corner (' ')
+        #   The bottom-left-corner border character.
+        #
+        # @option border [String] :bottom_joined_border (' ')
+        #   The bottom-joined border character.
+        #
+        # @option border [String] :bottom_right_corner (' ')
+        #   The bottom-right-corner border character.
+        #
+        # @param [Integer] padding
+        #   The number of characters to pad table cell values with.
+        #
+        # @param [:left, :right, :center] justify
+        #   Specifies how to justify the table cell values.
+        #
+        # @param [:left, :right, :center] justify_header
+        #   Specifies how to justify the table header cell values.
+        #
+        # @param [Boolean] separate_rows
+        #   Specifies whether to add separator rows in between the rows.
+        #
+        def initialize(border: nil,
+                       padding: 1,
+                       justify:        :left,
+                       justify_header: :center,
+                       separate_rows:  false)
+          @border = case border
+                    when Hash
+                      BorderStyle.new(**border)
+                    when Symbol
+                      BORDER_STYLES.fetch(border) do
+                        raise(ArgumentError,"unknown border style (#{border.inspect}) must be either #{BORDER_STYLES.keys.map(&:inspect).join(', ')}")
+                      end
+                    when nil then nil
+                    else
+                      raise(ArgumentError,"invalid border value (#{border.inspect}) must be either #{BORDER_STYLES.keys.map(&:inspect).join(', ')}, Hash, or nil")
+                    end
+
+          @padding = padding
+
+          @justify        = justify
+          @justify_header = justify_header
+
+          @separate_rows  = separate_rows
+        end
+
+        #
+        # Determines if the rows should be separated.
+        #
+        # @return [Boolean]
+        #   Specifies whether each row should be separated with a separator row.
+        #
+        def separate_rows?
+          @separate_rows
+        end
+
+      end
+    end
+  end
+end

data/lib/command_kit/printing/tables/table_builder.rb

@@ -0,0 +1,145 @@
+require 'command_kit/printing/tables/row_builder'
+
+module CommandKit
+  module Printing
+    module Tables
+      #
+      # Builds a table and calculates it's dimensions.
+      #
+      # @api private
+      #
+      class TableBuilder
+
+        include Enumerable
+
+        # The rows within the table.
+        #
+        # @return [Array<RowBuilder>]
+        attr_reader :rows
+
+        # Indicates whether the table has a header row.
+        #
+        # @return [Boolean]
+        attr_reader :header
+
+        # The height (in lines) of the table.
+        #
+        # @return [Integer]
+        attr_reader :height
+
+        # The width (in characters) of the table.
+        #
+        # @return [Integer]
+        attr_reader :width
+
+        # The maximum number of rows in the table.
+        #
+        # @return [Integer]
+        attr_reader :max_rows
+
+        # The maximum number of columns in the table.
+        #
+        # @return [Integer]
+        attr_reader :max_columns
+
+        # The widths of the columns in the table.
+        #
+        # @return [Array<Integer>]
+        attr_reader :column_widths
+
+        #
+        # Initializes the table.
+        #
+        # @param [Array<Array>] rows
+        #   The rows for the table.
+        #
+        # @param [Array] header
+        #   The header row.
+        #
+        def initialize(rows=[], header: nil)
+          @rows    = []
+          @height  = 0
+          @width   = 0
+          @column_widths = []
+
+          @max_rows    = 0
+          @max_columns = 0
+
+          @header = !header.nil?
+
+          self << header if header
+          rows.each { |row| self << row }
+        end
+
+        #
+        # Determines whether the table has a header row.
+        #
+        # @return [Boolean]
+        #   Indicates whether the first row of the table is a header row.
+        #
+        def header?
+          @header
+        end
+
+        #
+        # Appends a row to the table.
+        #
+        # @param [Array] row
+        #   The row to append.
+        #
+        # @return [self]
+        #
+        def <<(row)
+          new_row = RowBuilder.new(row)
+
+          new_row.each_with_index do |cell,index|
+            column_width = @column_widths[index] || 0
+
+            if cell.width > column_width
+              @column_widths[index] = cell.width
+            end
+          end
+
+          @height += new_row.height
+          @width   = new_row.width if new_row.width > @width
+
+          @max_rows   += 1
+          @max_columns = new_row.columns if new_row.columns > @max_columns
+
+          @rows << new_row
+          return self
+        end
+
+        #
+        # Fetches a row from the table.
+        #
+        # @param [Integer] row_index
+        #   The row index to fetch the row at.
+        #
+        # @return [RowBuilder, nil]
+        #   The row or `nil` if no row exists at the given row index.
+        #
+        def [](row_index)
+          @rows[row_index]
+        end
+
+        #
+        # Enumerates over each row in the table.
+        #
+        # @yield [row]
+        #   If a block is given, it will be passed each row within the table.
+        #
+        # @yieldparam [RowBuilder] row
+        #   A row within the table.
+        #
+        # @return [Enumerator]
+        #   If no block is given, an Enumerator will be returned.
+        #
+        def each(&block)
+          @rows.each(&block)
+        end
+
+      end
+    end
+  end
+end