console_table 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2f72bfb44646e954c27cf46a4b3b3f4d50c629b0
-  data.tar.gz: 23402eb6500112776e41f43a988c0340552c1b65
+  metadata.gz: 0f4ac113386a891b3e7d95fa64d700214eba8798
+  data.tar.gz: 6f0979982d1a0e0996312a999b020c7f253bee8f
 SHA512:
-  metadata.gz: 3fb568ca9cac5df83ac89909b4988f56b464345ca938600926c84f747d734799ea64967d472420d0a30cc6be66b39afa0a9040d6eb63fd08be6d4a22573526a4
-  data.tar.gz: d2bdf4a87fe2dbf1a6f62a5a1a9bbfbf60250b28c36d96a480575e76fbe36597b71b275a60a9c700e2edff0bac2d7ff2b683b02f17a83d7cf4cfc8d24c55e5c2
+  metadata.gz: e0c0ccc7c271858afebdaa23bae2700d46fcf2b5f213815373685160b7ff8f50d5154bf22f0b23a33b39981d90d1462aa09574f6563308a5a8f6f7ed69c94e1b
+  data.tar.gz: 0d25ee5db8423d23545a950baeff579a4c68f0c57f2b33fbe1f8f1f5618ddf99c4c080dc27469d64eb313dc168ff005cf1f70ec661f7bc5597a8c77573450085

data/README.md

@@ -1,10 +1,16 @@
-#NOTE: I just pulled this code out of a skunkworks project into a gem, readme and tests coming soon.  Would not recommend this gem for any critical-path work at this time
+# ConsoleTable
 
----
+ConsoleTable is a helper class that allows you to print data to a console in a clean, table-like fashion.  It's intended for use
+in commandline applications with information-dense output.  It checks your terminal window size (or COLUMNS environment variable) to ensure
+your data will fit, allows you to define table column sizes, and then just supply the ConsoleTable instance with data which will be
+truncated or padded as needed to fit your specifications.
 
-# ConsoleTable
+It can be used to generate output similar to this screenshot:
+
+![image](console_table_screenshot.png =700x)
+
+You're able to specify left/right/center text justification, headers, footers, colors, and most importantly different sizes including exact character widths, screen percentages, and `*` for whatever is left.  If the window resizes the class will notice and output all new lines with recalculated locations (previous lines are not re-printed).
 
-TODO: Write a gem description
 
 ## Installation
 
@@ -22,11 +28,175 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+ConsoleTable needs a lot of information to get going, and it can be somewhat awkward to work with.
+
+First, we need to define the layout of our table.  This consists of the exact order of the columns we want, their identifiers, titles, and sizes.  Because we want to specify order, the layout config is an array, and each element of the array is a hash of config values for the column that element of the array defines.  For example:
+
+```ruby
+table_config = [
+   {:key=>:name, :size=>15, :title=>"Name"},
+   {:key=>:birthday, :size=>8, :title=>"DOB"},
+   {:key=>:nickname, :size=>0.3, :title=>"Nickname(s)"},
+   {:key=>:motto, :size=>"*", :title=>"Motto"},
+]
+
+ConsoleTable.define(table_config) do |table|
+	#Print data to the table here
+end
+```
+
+Here we've defined a table with four columns, a Name, DOB, Nickname, and Motto.  As we defined the details of the columns, by using an array we also defined their order.  
+
+* The Name column is exactly 15 characters wide, meaning that any data printed into that column will be right-padded with spaces to take up 15 characters, or if the name is longer than 15 characters it will be truncated. 
+* Next is the DOB, this is another field that's exactly 8 characters.  
+* After that is the Nickname, which has a size of 0.3, or 30%.  This column will take 30% of the available space in the window, but will never encroach on space allocated to exact-character sizes like DOB or Name.
+* Last is Motto, whose size is simply `"*"`. The `"*"` is the default size as well, so the entire `:size` could have been left out of this column definition.  `"*"` means to consume whatever is left of the window.  You can have multiple `"*"` entries, and the available space will be divided among them equally.
+
+Percentages and `*` sizes have no minimums, meaning they may not appear at all if the window is too small.  In this case, we have a table whose first column is 15 characters and whose second column is 8 characters.  The remaining columns will only appear if there is room, and there will be spaces between all four columns, so three spaces separating.  Thus, your window must be 15+8+3=26 characters wide or an exception will be thrown.
+
+Once we have our table, we must print to it.  Printing a line of data means supplying the table with a `Hash` whose keys match the values for `:key` in the column config.  So for example, we might do:
+
+```ruby
+ConsoleTable.define(table_config) do |table|
+	table.print({
+		:name=>"Rod",
+		:birthday=>"04-14-80",
+		:nickname=>"Chainsaw",
+		:motto=>"It works on my machine"
+	})
+end
+```
+
+If we run this in a console exactly 80 characters wide, the result is:
+
+```
+===============================================================================
+Name            DOB      Nickname(s)      Motto
+-------------------------------------------------------------------------------
+Rod             04-14-80 Chainsaw         It works on my machine
+===============================================================================
+```
+
+We can specify justification options for columns as well, and even overwrite them when we supply row data, simply by using `Hash`es instead of `String`s for the values.  For example:
+
+```ruby
+table_config = [
+   {:key=>:name, :size=>15, :title=>"Name"},
+   {:key=>:birthday, :size=>8, :title=>"DOB"},
+   {:key=>:nickname, :size=>0.3, :title=>"Nickname(s)", :justify=>:center},
+   {:key=>:motto, :size=>"*", :title=>"Motto", :justify=>:right},
+]
+
+ConsoleTable.define(table_config) do |table|
+	table.print({
+		:name=>"Rod",
+		:birthday=>"04-14-80",
+		:nickname=>{:text=>"Chainsaw", :justify=>:left},
+		:motto=>"It works on my machine"
+	})
+end
+```
+
+This will output:
+
+```
+===============================================================================
+Name            DOB        Nickname(s)                                    Motto
+-------------------------------------------------------------------------------
+Rod             04-14-80 Chainsaw                        It works on my machine
+===============================================================================
+```
+
+Notice how the Nickname column specifies that the justification will be centered, but when we actually output the data we say `{:text=>"Chainsaw", :justify=>:left}` thus overriding the justification to be left.  As a result, the header name is centered, but the data is left-aligned.  In the case of motto, we set the justification to the right-aligned, but never override it, so both the column header and the data itself are right-aligned.
+
+There are lots of different supported options for outputting the row data elements, here's a pretty comprehensive example and it's output
+
+```ruby
+table_config = [
+   {:key=>:name, :size=>15, :title=>"Name"},
+   {:key=>:birthday, :size=>8, :title=>"DOB"},
+   {:key=>:nickname, :size=>0.3, :title=>"Nickname(s)", :justify=>:center},
+   {:key=>:motto, :size=>"*", :title=>"Motto", :justify=>:right},
+]
+
+ConsoleTable.define(table_config) do |table|
+	table.print({
+		:name=>{:text=>"Rod", :highlight=>{:regex=>/[A-Z]/, :color=>:red},
+		:birthday=>{text: "04-14-80", :color=>:blue},
+		:nickname=>{:text=>"Chainsaw", :justify=>:left},
+		:motto=>{:text=>"This is a very long motto, I don't mind if it gets cut off but I'd like it to indicate as such with ellipses", :ellipsize=>true}
+	})
+end
+```
+
+will output
+
+```
+===============================================================================
+Name            DOB        Nickname(s)                                    Motto
+-------------------------------------------------------------------------------
+Rod             04-14-80 Chainsaw         This is a very long motto, I don't...
+```
+
+Due to limitations of this readme format, you'll have to take my word for it that the capital letters in the Name are highlighted Red, and the DOB is blue.
+
+You can also add a title and a footer to the table, or indent the entire table within the window using different options.  Again, here's another example that should more-or-less speak for itself.
+
+
+```ruby
+require 'console_table'
+require 'terminfo'
+
+puts TermInfo.screen_columns
+
+table_config = [
+   {:key=>:title, :size=>15, :title=>"Movie Title"},
+   {:key=>:name, :size=>15, :title=>"Name"},
+   {:key=>:release_date, :size=>8, :title=>"Release Date Too Long"},
+   {:key=>:tagline, :size=>"*", :title=>"Motto", :justify=>:right},
+]
+
+ConsoleTable.define(table_config, :left_margin=>5, :right_margin=>10, :title=>"Movie Killers") do |table|
+	table.print({
+		:title=>{:text=>"Friday the 13th", :highlight=>{:regex=>/[A-Z]/, :color=>:red}},
+		:name=>{:text=>"Jason", :justify=>:left},
+		:release_date=>{text: "05-09-80", :color=>:blue},
+		:tagline=>{:text=>"They were warned...They are doomed...And on Friday the 13th, nothing will save them.", :ellipsize=>true}
+	})
+
+	table.print({
+		:title=>{:text=>"Halloween", :highlight=>{:regex=>/[A-Z]/, :color=>:red}, :background=>:orange},
+		:name=>{:text=>"Michael Meyers", :justify=>:left},
+		:release_date=>{text: "10-25-80", :color=>:blue},
+		:tagline=>{:text=>"Everyone is entitled to one good scare", :ellipsize=>true}
+	})
+
+	table.add_footer("This is just a line of footer text")
+	table.add_footer("This is a second footer with \nlots of \nlinebreaks\n in it.")
+end
+```
+
+
+```
+     =================================================================
+                               Movie Killers
+     Movie Title     Name            Release                     Motto
+     -----------------------------------------------------------------
+     Friday the 13th Jason           05-09-80 They were warned...Th...
+     Halloween       Michael Meyers  10-25-80 Everyone is entitled ...
+     -----------------------------------------------------------------
+                                    This is just a line of footer text
+                                          This is a second footer with
+                                                               lots of
+                                                            linebreaks
+                                                                in it.
+     =================================================================  
+```
+
 
 ## Contributing
 
-1. Fork it ( http://github.com/<my-github-username>/console_table/fork )
+1. Fork it ( http://github.com/rodhilton/console_table/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/console_table.gemspec

@@ -4,7 +4,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = "console_table"
-  spec.version       = "0.0.4"
+  spec.version       = "0.0.5"
   spec.authors       = ["Rod Hilton"]
   spec.email         = ["consoletable@rodhilton.com"]
   spec.summary       = %q{Simplifies printing tables of information to commandline consoles}
@@ -22,4 +22,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'minitest', '~> 5.5'
 
   spec.add_runtime_dependency 'colorize', '~> 0.7'
+  spec.add_runtime_dependency 'ruby-terminfo', '~> 0.1'
 end

data/lib/console_table.rb

@@ -1,4 +1,5 @@
 require 'colorize'
+require 'terminfo'
 
 class ConsoleTable
 
@@ -47,7 +48,7 @@ class ConsoleTable
 
     @column_widths.each_with_index do |column, i|
       justify = column[:justify] || :left
-      title = column[:title].strip
+      title = (column[:title] || column[:key].to_s.capitalize).strip
       @out.print format(column[:size], title, false, justify)
       @out.print " " if i < @column_widths.size-1
     end
@@ -61,7 +62,7 @@ class ConsoleTable
   def add_footer(line)
     lines = line.split("\n")
     lines.each do |l|
-      @footer_lines << l.strip unless l.nil? or l.uncolorize.strip.blank?
+      @footer_lines << l.strip unless l.nil? or l.uncolorize.strip == ""
     end
   end
 
@@ -171,10 +172,10 @@ class ConsoleTable
     begin
       total_width = TermInfo.screen_columns
     rescue => ex
-      total_width = ENV["COLUMNS"].to_i || 150
+      total_width = ENV["COLUMNS"].to_i || 79
     end
 
-    keys = @original_column_layout.collect { |d| d[:key] }.uniq
+    keys = @original_column_layout.reject{|d| d[:key].nil?}.collect { |d| d[:key] }.uniq
     if keys.length < @original_column_layout.length
       raise("ConsoleTable configuration invalid, same key defined more than once")
     end
@@ -196,7 +197,7 @@ class ConsoleTable
     end
 
     percent_available = 1 - percent_used
-    stars = @original_column_layout.collect { |x| x[:size] }.find_all { |x| x.is_a? String }
+    stars = @original_column_layout.collect { |x| x[:size] or x[:size].nil?}.find_all { |x| x.is_a? String }
     num_stars = [stars.length, 1].max
     percent_for_stars = percent_available.to_f / num_stars
 
@@ -205,7 +206,7 @@ class ConsoleTable
         @column_widths << column_config #As-is when integer
       elsif column_config[:size].is_a? Float
         @column_widths << column_config.merge({:size => (column_config[:size]*available).floor})
-      elsif column_config[:size].is_a?(String) && column_config[:size] == "*"
+      elsif column_config[:size].nil? or column_config[:size].is_a?(String) && column_config[:size] == "*"
         @column_widths << column_config.merge({:size => (percent_for_stars*available).floor})
       else
         raise("ConsoleTable configuration invalid, '#{column_config[:size]}' is not a valid size")

data/test/test_console_table.rb

@@ -144,6 +144,60 @@ Row 2, Column 1      Row 2, Column 1                         Row 2, Column 3
     assert_output_equal expected, @mock_out.string
   end
 
+  def test_no_size_assumed_to_be_star
+    ENV["COLUMNS"] = "40"
+
+    commit_table_config = [
+        {:key=>:col1, :title=>"Column 1"},
+        {:key=>:col2, :title=>"Column 2"},
+    ]
+
+    ConsoleTable.define(commit_table_config, :output=>@mock_out) do |table|
+      table.print({
+                      :col1 => "Row 1, Column 1",
+                      :col2 => "Row 1, Column 2",
+                  })
+
+    end
+
+    expected=<<-END
+===============================================================================
+Column 1                                Column 2
+-------------------------------------------------------------------------------
+Row 1, Column 1                         Row 1, Column 2
+===============================================================================
+    END
+
+    assert_output_equal expected, @mock_out.string
+  end
+
+  def test_no_name_defaulted_to_capitalize_of_key_name
+    ENV["COLUMNS"] = "40"
+
+    commit_table_config = [
+        {:key=>:col1},
+        {:key=>:col2},
+    ]
+
+    ConsoleTable.define(commit_table_config, :output=>@mock_out) do |table|
+      table.print({
+                      :col1 => "Row 1, Column 1",
+                      :col2 => "Row 1, Column 2",
+                  })
+
+    end
+
+    expected=<<-END
+===============================================================================
+Col1                                    Col2
+-------------------------------------------------------------------------------
+Row 1, Column 1                         Row 1, Column 2
+===============================================================================
+    END
+
+    assert_output_equal expected, @mock_out.string
+  end
+
   def test_can_combine_percentages_fixed_and_stars
     ENV["COLUMNS"] = "160"
 
@@ -235,6 +289,17 @@ Row 2, Column 1      Row 2, Column 2                      Row  Row 2, Column 4
     assert_raises(RuntimeError) { ConsoleTable.define(commit_table_config) }
   end
 
+  def test_wont_allow_columns_with_no_key_name
+    ENV["COLUMNS"] = "50"
+
+    commit_table_config = [
+        {:key=>:col1, :size=>20, :title=>"Column 1"},
+        {:size=>20, :title=>"Column 2"},
+    ]
+
+    assert_raises(RuntimeError) { ConsoleTable.define(commit_table_config) }
+  end
+
   def test_can_truncate_output
     ENV["COLUMNS"] = "100"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: console_table
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Rod Hilton
@@ -80,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: ruby-terminfo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 description: Allows developers to define tables with specifically-sized columns, which
   can then have entries printed to them that are automatically formatted, truncated,
   and padded to fit in the console window.
@@ -95,6 +109,7 @@ files:
 - README.md
 - Rakefile
 - console_table.gemspec
+- console_table_screenshot.png
 - lib/console_table.rb
 - test/test_console_table.rb
 - todo.txt