tabulo 0.6.2 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5a2f88a15024f1728f244d9f72a14b6f88a893fc
-  data.tar.gz: c6f23f4a1568575083122f501d2e61492057b2b7
+  metadata.gz: 6756f8ae92c219bb324358e9046e86ec756d3923
+  data.tar.gz: de3d6bedfcbea40b81d607d00ca07be75e4277a5
 SHA512:
-  metadata.gz: 703ef06a5ea3c9c0dbf1b01b1572b02f0eca2e9ef6dc64508cb7a93459211c1c420f32af29c95a22581dd31c6a02ed3308ee7e913dfa37be65cf592633650b14
-  data.tar.gz: f17355d77642115e8bca70c5601164dfe16e186d1b5c79e3577d1e292eda46942a1fd9f0f9ccd730bbedaf2c4ce2a526832425715ae0c6d13e11a470ff018a2c
+  metadata.gz: b5f10a9d672d15083bf96cb7d6f5e8a21030e98318fc13cd98d82ec9c22f5d83ea25d65cb792273c5840db056b7b6a0a961d71676a10bac430f5f874517521b6
+  data.tar.gz: c46bcc143a0447af136aab26c7dc960b1c4f53afdf72e27a57522428dab7d936ccc95cd8b2a4bbe19726100fd28de4547f978ed1280be9a491bc88bc9a18547d

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+### v0.6.3
+
+* Throw an exception if column labels are not unique.
+
 ### v0.6.2
 
 * Explicitly support only Ruby >= 2.1.10.

data/README.md

@@ -226,7 +226,12 @@ table will not overflow your terminal horizontally.
 
 Note that shrinkwrapping necessarily involves traversing the entire collection up front as
 the maximum cell width needs to be calculated for each column. You may not want to do this
-if the collection is very large.
+if the collection is very large. Note also the effect of `shrinkwrap!` is to fix the column widths
+as appropriate to the formatted cell contents given the state of the underlying collection
+_at the point of shrinkwrapping_. If the underlying collection changes between that point, and when
+the table is printed, then the columns will _not_ be resized yet again on printing. This is a
+consequence of the table always being essentially a "live view" on the underlying collection:
+formatted contents are never cached within the table itself.
 
 <a name="overflow-handling"></a>
 #### Overflow handling
@@ -368,8 +373,9 @@ end.to_enum  # <-- make an Enumerator
 ```
 
 Note the use of `.find_each`: we can start printing the table without having to load the entire
-underlying collection. (The cost of supporting this behaviour is that Tabulo requires us to set
-column widths up front, rather than adapting to the width of the widest value.)
+underlying collection. (This is negated if we [shrinkwrap](#shrinkwrap) the table, however, since
+in that case the entire collection must be traversed up front in order for column widths to be
+calculated.)
 
 ## Development
 
@@ -391,11 +397,11 @@ License](http://opensource.org/licenses/MIT).
 [Dependency Status]: https://gemnasium.com/matt-harvey/tabulo
 [Coverage Status]: https://coveralls.io/r/matt-harvey/tabulo
 [Code Climate]: https://codeclimate.com/github/matt-harvey/tabulo
-[Documentation]: http://www.rubydoc.info/gems/tabulo/0.6.2
+[Documentation]: http://www.rubydoc.info/github/matt-harvey/tabulo
 
 [GV img]: https://img.shields.io/gem/v/tabulo.svg?style=plastic
 [BS img]: https://img.shields.io/travis/matt-harvey/tabulo.svg?style=plastic
 [DS img]: https://img.shields.io/gemnasium/matt-harvey/tabulo.svg?style=plastic
 [CS img]: https://img.shields.io/coveralls/matt-harvey/tabulo.svg?style=plastic
 [CC img]: https://img.shields.io/codeclimate/github/matt-harvey/tabulo.svg?style=plastic
-[DC img]: https://img.shields.io/badge/docs-v0.6.2-blue.svg?style=plastic
+[DC img]: https://img.shields.io/badge/docs-latest-blue.svg?style=plastic

data/VERSION

@@ -1 +1 @@
-0.6.2
+0.6.3

data/lib/tabulo.rb

@@ -1,4 +1,5 @@
 require "tabulo/version"
+require "tabulo/exceptions"
 require "tabulo/table"
 require "tabulo/row"
 require "tabulo/column"

data/lib/tabulo/column.rb

@@ -4,13 +4,10 @@ module Tabulo
   class Column
 
     attr_accessor :width
-    attr_reader :header, :label
+    attr_reader :header
 
-    # @!visibility private
-    def initialize(label:, header:, width:, align_header:, align_body:,
-      formatter:, extractor:)
+    def initialize(header:, width:, align_header:, align_body:, formatter:, extractor:)
 
-      @label = label
       @header = header
       @width = width
       @align_header = align_header
@@ -19,17 +16,14 @@ module Tabulo
       @extractor = extractor
     end
 
-    # @!visibility private
     def header_subcells
       infilled_subcells(@header, @align_header)
     end
 
-    # @!visibility private
     def horizontal_rule
       Table::HORIZONTAL_RULE_CHARACTER * width
     end
 
-    # @!visibility private
     def body_subcells(source)
       cell_datum = body_cell_value(source)
       formatted_content = @formatter.call(cell_datum)
@@ -37,19 +31,16 @@ module Tabulo
       infilled_subcells(formatted_content, real_alignment)
     end
 
-    # @!visibility private
     def formatted_cell_content(source)
       @formatter.call(body_cell_value(source))
     end
 
-    # @!visibility private
     def body_cell_value(source)
       @extractor.call(source)
     end
 
     private
 
-    # @!visibility private
     def infilled_subcells(str, real_alignment)
       str.split($/, -1).flat_map do |substr|
         num_subsubcells = [1, (substr.length.to_f / width).ceil].max
@@ -59,7 +50,6 @@ module Tabulo
       end
     end
 
-    # @!visibility private
     def align_cell_content(content, real_alignment)
       padding = [@width - content.length, 0].max
       left_padding, right_padding =
@@ -76,7 +66,6 @@ module Tabulo
       "#{' ' * left_padding}#{content}#{' ' * right_padding}"
     end
 
-    # @!visibility private
     def infer_alignment(cell_datum)
       case cell_datum
       when Numeric

data/lib/tabulo/exceptions.rb

@@ -0,0 +1,5 @@
+module Tabulo
+
+  # Error indicating that the label of a column is invalid.
+  class InvalidColumnLabelError < StandardError; end
+end

data/lib/tabulo/row.rb

@@ -22,7 +22,7 @@ module Tabulo
     #     cell.class  # => Fixnum, => FalseClass
     #   end
     def each
-      @table.columns.each do |column|
+      @table.column_registry.each do |label, column|
         yield column.body_cell_value(@source)
       end
     end
@@ -31,7 +31,7 @@ module Tabulo
     #   any column headers that appear just above it in the {Table} (depending on where this Row is
     #   in the {Table} and how the {Table} was configured with respect to header frequency).
     def to_s
-      if @table.columns.any?
+      if @table.column_registry.any?
         @table.formatted_body_row(@source, with_header: @with_header)
       else
         ""
@@ -45,7 +45,7 @@ module Tabulo
     #   row = table.first
     #   row.to_h  # => { :itself => 1, :even? => false }
     def to_h
-      @table.columns.map(&:label).zip(to_a).to_h
+      @table.column_registry.map { |label, column| [label, column.body_cell_value(@source)] }.to_h
     end
   end
 end

data/lib/tabulo/table.rb

@@ -6,19 +6,30 @@ module Tabulo
   class Table
     include Enumerable
 
+    # @!visibility private
     DEFAULT_COLUMN_WIDTH = 12
+
+    # @!visibility private
     HORIZONTAL_RULE_CHARACTER = "-"
+
+    # @!visibility private
     VERTICAL_RULE_CHARACTER = "|"
+
+    # @!visibility private
     CORNER_CHARACTER = "+"
+
+    # @!visibility private
     PADDING_CHARACTER = " "
+
+    # @!visibility private
     TRUNCATION_INDICATOR = "~"
 
     # @!visibility private
-    attr_reader :columns
+    attr_reader :column_registry
 
     # @param [Enumerable] sources the underlying Enumerable from which the table will derive its data
-    # @param [Array[Symbol]] columns Specifies the initial columns.
-    #   Each element of the Array  will be used to create a column whose content is
+    # @param [Array[Symbol]] columns Specifies the initial columns. The Symbols provided must
+    #   be unique. Each element of the Array  will be used to create a column whose content is
     #   created by calling the corresponding method on each element of sources. Note
     #   the {#add_column} method is a much more flexible way to set up columns on the table.
     # @param [Fixnum, nil] column_width The default column width for columns in this
@@ -36,6 +47,7 @@ module Tabulo
     #   be wrapped for as many rows as required to accommodate it. If passed a Fixnum N (> 0), content will be
     #   wrapped up to N rows and then truncated thereafter.
     # @return [Table] a new Table
+    # @raise [InvalidColumnLabelError] if non-unique Symbols are provided to columns.
     def initialize(sources, columns: [], column_width: nil, header_frequency: :start,
       wrap_header_cells_to: nil, wrap_body_cells_to: nil)
 
@@ -46,7 +58,7 @@ module Tabulo
 
       @default_column_width = (column_width || DEFAULT_COLUMN_WIDTH)
 
-      @columns = []
+      @column_registry = { }
       columns.each { |item| add_column(item) }
 
       yield self if block_given?
@@ -81,24 +93,33 @@ module Tabulo
     #   that will be passed each of the Table sources to determine the value in each cell of this
     #   column. If this is not provided, then the column label will be treated as a method to be
     #   called on each source item to determine each cell's value.
+    # @raise [InvalidColumnLabelError] if label has already been used for another column in this
+    #   Table. (This is case-sensitive, but is insensitive to whether a String or Symbol is passed
+    #   to the label parameter.)
     def add_column(label, header: nil, align_header: :center, align_body: nil,
       width: nil, formatter: :to_s.to_proc, &extractor)
 
-      @columns << Column.new(
-        label: label.to_sym,
-        header: (header || label).to_s,
-        align_header: align_header,
-        align_body: align_body,
-        width: (width || @default_column_width),
-        formatter: formatter,
-        extractor: (extractor || label.to_proc)
-      )
+      column_label = label.to_sym
+
+      if column_registry.include?(column_label)
+        raise InvalidColumnLabelError, "Column label already used in this table."
+      end
+
+      @column_registry[column_label] =
+        Column.new(
+          header: (header || label).to_s,
+          align_header: align_header,
+          align_body: align_body,
+          width: (width || @default_column_width),
+          formatter: formatter,
+          extractor: (extractor || label.to_proc)
+        )
     end
 
     # @return [String] a graphical "ASCII" representation of the Table, suitable for
     #   display in a fixed-width font.
     def to_s
-      if @columns.any?
+      if column_registry.any?
         join_lines(map(&:to_s))
       else
         ""
@@ -131,7 +152,7 @@ module Tabulo
 
     # @return [String] an "ASCII" graphical representation of the Table column headers.
     def formatted_header
-      cells = @columns.map(&:header_subcells)
+      cells = column_registry.map { |label, column| column.header_subcells }
       format_row(cells, @wrap_header_cells_to)
     end
 
@@ -144,7 +165,9 @@ module Tabulo
     #   end
     #
     def horizontal_rule
-      inner = @columns.map { |column| surround(column.horizontal_rule, HORIZONTAL_RULE_CHARACTER) }
+      inner = column_registry.map do |label, column|
+        surround(column.horizontal_rule, HORIZONTAL_RULE_CHARACTER)
+      end
       surround_join(inner, CORNER_CHARACTER)
     end
 
@@ -157,6 +180,11 @@ module Tabulo
     # be traversed and all the column extractors and formatters to be applied in order
     # to calculate the required widths.
     #
+    # Note also that this method causes column widths to be fixed as appropriate to the
+    # formatted cell contents given the state of the source Enumerable at the point it
+    # is called. If the source Enumerable changes between that point, and the point when
+    # the Table is printed, then columns will *not* be resized yet again on printing.
+    #
     # @param [nil, Numeric] max_table_width (nil) If provided, stops the total table
     #   width (including padding and borders) from expanding beyond this number of characters.
     #   Width is deducted from columns if required to achieve this, with one character progressively
@@ -170,36 +198,41 @@ module Tabulo
     #   shrink itself.
     # @return [Table] the Table itself
     def shrinkwrap!(max_table_width: nil)
-      return self if columns.none?
+      return self if column_registry.none?
 
       wrapped_width = -> (str) { str.split($/).map(&:length).max || 1 }
 
-      columns.each do |column|
+      column_registry.each do |label, column|
         column.width = wrapped_width.call(column.header)
       end
 
       @sources.each do |source|
-        columns.each do |column|
+        column_registry.each do |label, column|
           width = wrapped_width.call(column.formatted_cell_content(source))
           column.width = width if width > column.width
         end
       end
 
       if max_table_width
-        total_columns_width = columns.inject(0) { |sum, column| sum + column.width }
-        total_padding = columns.count * 2
-        total_borders = columns.count + 1
+        total_columns_width = column_registry.inject(0) do |sum, label_with_column|
+          _label, column = label_with_column
+          sum + column.width
+        end
+        total_padding = column_registry.count * 2
+        total_borders = column_registry.count + 1
         unadjusted_table_width = total_columns_width + total_padding + total_borders
 
         # Ensure max table width is at least wide enough to accommodate table borders and padding
         # and one character of content.
-        min_table_width = total_padding + total_borders + columns.count
+        min_table_width = total_padding + total_borders + column_registry.count
         max_table_width = min_table_width if min_table_width > max_table_width
 
         required_reduction = [unadjusted_table_width - max_table_width, 0].max
 
         required_reduction.times do
-          widest_column = columns.inject(columns.first) do |widest, column|
+          _first_label, first_column = column_registry.first
+          widest_column = column_registry.inject(first_column) do |widest, label_with_column|
+            _label, column = label_with_column
             column.width >= widest.width ? column : widest
           end
 
@@ -212,7 +245,7 @@ module Tabulo
 
     # @!visibility private
     def formatted_body_row(source, with_header: false)
-      cells = @columns.map { |column| column.body_subcells(source) }
+      cells = column_registry.map { |label, column| column.body_subcells(source) }
       inner = format_row(cells, @wrap_body_cells_to)
       if with_header
         join_lines([horizontal_rule, formatted_header, horizontal_rule, inner])
@@ -245,7 +278,7 @@ module Tabulo
       row_height = ([wrap_cells_to, cells.map(&:size).max].compact.min || 1)
 
       subrows = (0...row_height).map do |subrow_index|
-        subrow_components = cells.map.with_index do |cell, column_index|
+        subrow_components = cells.zip(column_registry.values).map do |cell, column|
           num_subcells = cell.size
           cell_truncated = (num_subcells > row_height)
           append_truncator = (cell_truncated && subrow_index + 1 == row_height)
@@ -257,8 +290,7 @@ module Tabulo
             if subrow_index < num_subcells
               cell[subrow_index]
             else
-              column_width = @columns[column_index].width
-              PADDING_CHARACTER * column_width
+              PADDING_CHARACTER * column.width
             end
 
           "#{lpad}#{inner}#{rpad}"

data/lib/tabulo/version.rb

@@ -1,3 +1,3 @@
 module Tabulo
-  VERSION = "0.6.2"
+  VERSION = "0.6.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tabulo
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.6.3
 platform: ruby
 authors:
 - Matthew Harvey
@@ -159,6 +159,7 @@ files:
 - bin/setup
 - lib/tabulo.rb
 - lib/tabulo/column.rb
+- lib/tabulo/exceptions.rb
 - lib/tabulo/row.rb
 - lib/tabulo/table.rb
 - lib/tabulo/version.rb