command_kit 0.3.0 → 0.4.0

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

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

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module CommandKit
+  module Printing
+    module Tables
+      #
+      # @api private
+      #
+      class TableFormatter
+
+        #
+        # Initialies the table formatter.
+        #
+        # @param [TableBuilder] table
+        #   The table data to print.
+        #
+        # @param [Style] style
+        #   The table's style configuration.
+        #
+        def initialize(table,style)
+          @table = table
+          @style = style
+
+          @padding = ' ' * @style.padding
+          @extra_padding = @style.padding * 2
+
+          @last_column = @table.max_columns - 1
+          @last_row    = @table.max_rows - 1
+        end
+
+        #
+        # Formats the table.
+        #
+        # @yield [line]
+        #   The given block will be passed each formatted line of the table.
+        #
+        # @yieldparam [String]
+        #   A formatted line of the table.
+        #
+        def format(&block)
+          yield format_top_border if @style.border
+
+          separator_row = if @table.header? || @style.separate_rows?
+                            format_separator_row
+                          end
+
+          @table.max_rows.times do |row_index|
+            row = @table[row_index]
+
+            if @table.header? && row_index == 0
+              format_header_row(row,&block)
+
+              yield separator_row
+            else
+              format_row(row,&block)
+
+              if @style.separate_rows? && row_index < @last_row
+                yield separator_row
+              end
+            end
+          end
+
+          yield format_bottom_border if @style.border
+        end
+
+        private
+
+        #
+        # Builds a horizontal border row.
+        #
+        # @param [String] left_border
+        #   The left-hand side/corner border character.
+        #
+        # @param [String] column_border
+        #   The top/bottom/horizontal column border character.
+        #
+        # @param [String] joined_border
+        #   A joined border character.
+        #
+        # @param [String] right_border
+        #   The right-hand side/corner border character.
+        #
+        # @return [String]
+        #   The formatted border row.
+        #
+        def format_border_row(left_border: ,
+                              column_border: ,
+                              joined_border: ,
+                              right_border: )
+          line = String.new
+          line << left_border
+
+          @table.max_columns.times do |column_index|
+            column_width = @table.column_widths[column_index] + @extra_padding
+
+            line << (column_border * column_width)
+
+            line << if column_index < @last_column
+                      joined_border
+                    else
+                      right_border
+                    end
+          end
+
+          return line
+        end
+
+        #
+        # Builds the top border row.
+        #
+        # @return [String]
+        #   The formatted top border row.
+        #
+        def format_top_border
+          format_border_row(left_border:   @style.border.top_left_corner,
+                            column_border: @style.border.top_border,
+                            joined_border: @style.border.top_joined_border,
+                            right_border:  @style.border.top_right_corner)
+        end
+
+        #
+        # Builds the separator row.
+        #
+        # @return [String]
+        #   The formatted separator row.
+        #
+        def format_separator_row
+          if @style.border
+            format_border_row(left_border:   @style.border.left_joined_border,
+                              column_border: @style.border.horizontal_separator,
+                              joined_border: @style.border.inner_joined_border,
+                              right_border:  @style.border.right_joined_border)
+          else
+            ''
+          end
+        end
+
+        #
+        # Builds the top border row.
+        #
+        # @return [String]
+        #   The formatted bottom border row.
+        #
+        def format_bottom_border
+          format_border_row(left_border:   @style.border.bottom_left_corner,
+                            column_border: @style.border.bottom_border,
+                            joined_border: @style.border.bottom_joined_border,
+                            right_border:  @style.border.bottom_right_corner)
+        end
+
+        #
+        # Formats a cell value.
+        #
+        # @param [String] value
+        #   The value from the cell.
+        #
+        # @param [Integer] width
+        #   The desired width of the cell.
+        #
+        # @param [:left, :right, :center] justify
+        #   How to justify the cell's value.
+        #
+        # @return [String]
+        #   The formatted cell.
+        #
+        def format_cell(value, width: , justify: @style.justify)
+          justified_value = case justify
+                            when :center then value.center(width)
+                            when :left   then value.ljust(width)
+                            when :right  then value.rjust(width)
+                            else
+                              raise(ArgumentError,"invalid justify value (#{justify.inspect}), must be :left, :right, or :center")
+                            end
+
+          return "#{@padding}#{justified_value}#{@padding}"
+        end
+
+        #
+        # Formats a specific line within a row.
+        #
+        # @param [RowBuilder] row
+        #   The table row to format.
+        #
+        # @param [Integer] line_index
+        #   The line index within the row to specifically format.
+        #
+        # @param [:left, :right, :center] justify
+        #   How to justify each cell within the row.
+        #
+        # @return [String]
+        #   The formatted row line.
+        #
+        def format_row_line(row,line_index, justify: @style.justify)
+          line = String.new
+          line << @style.border.left_border if @style.border
+
+          @table.max_columns.times do |column_index|
+            column_width = @table.column_widths[column_index]
+            cell_line    = row[column_index][line_index]
+
+            line << format_cell(cell_line, width:   column_width,
+                                           justify: justify)
+
+            if (@style.border && (column_index < @last_column))
+              line << @style.border.vertical_separator
+            end
+          end
+
+          line << @style.border.right_border if @style.border
+          return line
+        end
+
+        #
+        # Formats a row.
+        #
+        # @param [RowBuilder] row
+        #   The table row to format.
+        #
+        # @param [:left, :right, :center] justify
+        #   How to justify each cell within the row.
+        #
+        # @yield [line]
+        #   The given block will be passed each formatted line within the row.
+        #
+        # @yieldparam [String] line
+        #   A formatted line of the row.
+        #
+        def format_row(row, justify: @style.justify)
+          row.height.times do |line_index|
+            yield format_row_line(row,line_index, justify: justify)
+          end
+        end
+
+        #
+        # Formats a header row.
+        #
+        # @param [RowBuilder] row
+        #   The header row to format.
+        #
+        # @yield [line]
+        #   The given block will be passed each formatted line within the header
+        #   row.
+        #
+        # @yieldparam [String] line
+        #   A formatted line of the header row.
+        #
+        def format_header_row(row,&block)
+          format_row(row, justify: @style.justify_header, &block)
+        end
+
+      end
+    end
+  end
+end